Ir al contenido

API REST para automatizar extracción

Conecta idpura a n8n, Make, Zapier o cualquier cliente HTTP. Envía documentos, recibe datos estructurados.

Inicio rápido

  1. Genera tu API key

    Entra en tu cuenta → sección API → Crear key. La key solo se muestra una vez, guárdala en un lugar seguro.

  2. Envía tu primer request

    Sube documentos y recibe un job_id para consultar el resultado.

    curl -X POST https://api.idpura.com/v1/ai-extract \
  -H "X-API-Key: ipd_tu_api_key" \
  -F "files=@factura.pdf" \
  -F 'template=[{"field":"nif","type":"string"},{"field":"total","type":"currency"}]' \
  -F "output_format=json"

# Respuesta:
# { "job_id": "abc-123", "status": "processing", "total_pages": 3, "credits_used": 9 }

  3. Descarga el resultado

    Consulta el estado del job y descarga cuando esté listo.

    # 1. Consultar estado
curl https://api.idpura.com/v1/jobs/abc-123 \
  -H "X-API-Key: ipd_tu_api_key"

# 2. Descargar resultado (cuando status=done)
curl https://api.idpura.com/v1/jobs/abc-123/result?format=json \
  -H "X-API-Key: ipd_tu_api_key"

Endpoints

Todos los endpoints requieren el header X-API-Key.

Método Ruta Descripción Créditos
POST /v1/ai-extract Extrae campos con IA según tu template (PDF, DOCX, imágenes) 3 cr/pág
POST /v1/extract Extrae texto y tablas de PDF/DOCX sin IA 1 cr/pág
POST /v1/section Compara y secciona 3+ documentos del mismo tipo 1–3 cr/pág
GET /v1/jobs/{id} Consulta el estado de un job (processing, done, error) 0
GET /v1/jobs/{id}/result Descarga el resultado en json, xlsx o csv 0

Ejemplos de integración

cURL
curl -X POST https://api.idpura.com/v1/ai-extract \
  -H "X-API-Key: ipd_tu_api_key" \
  -F "files=@contrato.pdf" \
  -F "files=@contrato2.pdf" \
  -F 'template=[
    {"field":"nombre","type":"string","description":"Nombre completo"},
    {"field":"fecha_firma","type":"date"},
    {"field":"importe","type":"currency"}
  ]' \
  -F "language_hint=es" \
  -F "output_format=json"
Python
import requests, json, time

API_KEY = "ipd_tu_api_key"
BASE    = "https://api.idpura.com"
headers = {"X-API-Key": API_KEY}

template = [
    {"field": "nif",    "type": "string"},
    {"field": "total",  "type": "currency"},
    {"field": "fecha",  "type": "date"},
]

with open("factura.pdf", "rb") as f:
    resp = requests.post(
        f"{BASE}/v1/ai-extract",
        headers=headers,
        files={"files": f},
        data={"template": json.dumps(template), "output_format": "json"},
    )
job = resp.json()
job_id = job["job_id"]

# Polling hasta que termine
while True:
    status = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=headers).json()
    if status["status"] == "done":
        break
    if status["status"] == "error":
        raise Exception(status.get("error_message"))
    time.sleep(3)

result = requests.get(
    f"{BASE}/v1/jobs/{job_id}/result",
    headers=headers,
    params={"format": "json"},
)
print(result.json())
n8n
# Flow n8n en 4 nodos:

# 1. HTTP Request (POST /v1/ai-extract)
#    - Method: POST
#    - URL: https://api.idpura.com/v1/ai-extract
#    - Auth header: X-API-Key = {{ $vars.IDPURA_API_KEY }}
#    - Body: multipart/form-data
#      files: (Binary field con tu documento)
#      template: [{"field":"nif","type":"string"},{"field":"total","type":"currency"}]
#      output_format: json

# 2. Wait (1-5 segundos según tamaño del lote)

# 3. HTTP Request (GET /v1/jobs/{id})
#    - URL: https://api.idpura.com/v1/jobs/{{ $json.job_id }}
#    - Repetir con IF hasta status = done

# 4. HTTP Request (GET /v1/jobs/{id}/result?format=json)
#    - Usar los datos en nodos siguientes (Spreadsheet, Database, etc.)

Coste por herramienta

Los créditos se deducen al enviar el job, no al descargar el resultado.

Herramienta Coste Notas
Extractor IA (/v1/ai-extract) 3 cr/pág Incluye imágenes y PDFs escaneados
Extractor (/v1/extract) 1 cr/pág PDFs digitales y DOCX
Seccionar (/v1/section sin IA) 1 cr/pág Mínimo 3 documentos
Seccionar (/v1/section con IA) 3 cr/pág use_ai=true

Rate limiting

100 requests/hora por API key. Si superas el límite, recibes un 429 con el header Retry-After indicando cuántos segundos esperar.

  • X-RateLimit-Limit Requests permitidos por ventana (100)
  • X-RateLimit-Remaining Requests restantes en la ventana actual
  • X-RateLimit-Reset Timestamp Unix cuando se reinicia el contador

Códigos de error

Código Significado
400 Request inválido — revisa los parámetros enviados
401 API key ausente o inválida
402 Créditos insuficientes — recarga tu saldo
403 Sin acceso al job (pertenece a otro usuario)
404 Job expirado o no encontrado (TTL: 24h)
409 Job todavía no ha terminado — consulta el estado primero
429 Rate limit superado — usa el header Retry-After

¿Todo claro?

Documentación interactiva (Swagger) Ver planes y créditos