Desarrolladores

API de extracción de datos de facturas y pedidos

Envía un PDF, un escaneo o una foto del móvil y recibe un JSON con el proveedor o cliente, referencias, fechas, totales, IVA y líneas de producto, ya cuadradas con los totales del documento. Tres tipos de documento: facturas de proveedor, pedidos a proveedor y pedidos de cliente.

En resumen

  • API REST síncrona, JSON de entrada y de salida
  • PDF, JPEG y PNG; cualquier formato o idioma, sin plantillas
  • 1 crédito por documento procesado; los errores y reintentos no se cobran
  • Cabecera Idempotency-Key para reintentar sin riesgo

Primeros pasos

  1. 1

    Crea una cuenta y una API key en upinvoice.eu/api/tokens.

  2. 2

    Envía el archivo como data URI en base64 a POST /api/process-document con su document_type.

  3. 3

    Lee el JSON, revisa los avisos y crea el documento en tu sistema.

curl -sS https://upinvoice.eu/api/process-document \
  -H "Authorization: Bearer $UPINVOICE_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --max-time 120 \
  -d @- <<EOF
{
  "document_type": "supplier_invoice",
  "invoice_file": "data:application/pdf;base64,$(base64 -w0 invoice.pdf)",
  "company_name": "Demo Company SL",
  "company_tax_id": "B12345678"
}
EOF

Endpoints

  • POST/api/process-document

    Extrae un documento. Es el que debes usar.

  • GET/api/check

    Gratis. Valida la clave y devuelve el plan, los créditos restantes y los tipos de documento admitidos.

  • POST/api/process-invoice

    Antiguo, solo facturas de proveedor. Se mantiene para módulos de Dolibarr anteriores.

Autenticación

Envía tu API key como bearer token y añade siempre Accept: application/json; si no, una clave no válida se responde con una redirección en lugar de un 401.

Authorization: Bearer <your-api-key>
Accept: application/json

Petición

Campo Descripción
document_type Obligatorio. supplier_invoice (factura o abono recibido), supplier_order (tu pedido de compra o la confirmación de pedido de un proveedor) o customer_order (un pedido que te envía un cliente).
invoice_file Obligatorio, con el mismo nombre para todos los tipos. Data URI data:<mime>;base64,<contenido>. Admite application/pdf, image/jpeg e image/png, de hasta 5 MB por archivo.
company_name, company_tax_id Recomendado. Nombre y NIF de tu propia empresa, para que la IA no te confunda con el proveedor o el cliente.

El proceso es síncrono: normalmente de 3 a 6 segundos, hasta 30 segundos en PDF largos de varias páginas. Usa un timeout de cliente de al menos 90 segundos y hasta 5 peticiones en paralelo.

Respuesta

El objeto data depende del tipo de documento. Las facturas de proveedor devuelven supplier, ref_supplier, date, totales, IVA y líneas (los abonos con importes negativos). Los pedidos devuelven thirdparty, ref_document, fechas de pedido y de entrega, divisa, notas, líneas y avisos. Todos los campos están descritos en la especificación OpenAPI.

{
  "success": true,
  "data": {
    "supplier": {
      "name": "Example Supplies SL",
      "idprof1": "B00000000",
      "tva_intra": "ESB00000000",
      "address": "Calle Mayor 1",
      "zip": "46001",
      "town": "Valencia",
      "country_code": "ES",
      ...
    },
    "ref_supplier": "F-2026-0457",
    "date": "2026-11-12",
    "total_ht": 230,
    "total_tva": 48.3,
    "total_ttc": 278.3,
    "tva_tx": 21,
    "lines": [
      {
        "product_desc": "Printer toner, black",
        "product_ref": "TN-2420",
        "qty": 4,
        "subprice": 50,
        "remise_percent": 10,
        "tva_tx": 21,
        "total_ht": 180,
        "total_tva": 37.8,
        "total_ttc": 217.8,
        "product_type": 0,
        "accounting_code": "602"
      },
      ...
    ],
    "available_points": 72
  }
}

Conviene saber

  • Los campos de texto que faltan llegan como cadena vacía; las fechas, en AAAA-MM-DD o vacías.
  • Los totales de línea ya incluyen los descuentos; úsalos como importes de referencia.
  • Si un pedido trae avisos (document_type_mismatch, thirdparty_matches_own_company), pide confirmación a una persona antes de crearlo.
  • Los pedidos sin precios llegan con importes a cero: toma los precios de tu catálogo.

Errores

Código Significado
401 Falta la API key o no es válida.
409 Sigue en curso una petición con la misma Idempotency-Key. Espera lo que indique Retry-After y reintenta con la misma clave.
422 Campo no válido, o Idempotency-Key reutilizada con otro archivo. Corrige la petición.
400 Data URI no válido, archivo no admitido, sin créditos o documento ilegible. No se cobra nada. Llama a /api/check para distinguir un problema de créditos de uno del archivo.

El campo error es un mensaje para personas, no un código estable.

Reintentos seguros con Idempotency-Key

Envía una Idempotency-Key única por documento (un UUID o tu propio ID de documento). Si se corta la conexión, repite la misma petición con la misma clave: recibirás el resultado guardado con la cabecera Idempotent-Replayed: true y no se cobra dos veces. Las claves se guardan 48 horas.

Precio

La extracción la hace la IA de UpInvoice y se paga en créditos: un crédito por documento procesado. Los créditos vienen con un plan mensual o anual, o en packs extra cuando necesitas más. Los 10 primeros documentos son gratis, sin tarjeta.

Ver planes y precios →

Ejemplos de código

import base64, os, uuid
import requests  # pip install requests

with open("invoice.pdf", "rb") as fh:
    data_uri = "data:application/pdf;base64," + base64.b64encode(fh.read()).decode()

resp = requests.post(
    "https://upinvoice.eu/api/process-document",
    headers={
        "Authorization": "Bearer " + os.environ["UPINVOICE_API_KEY"],
        "Accept": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it if you retry
    },
    json={
        "document_type": "supplier_invoice",
        "invoice_file": data_uri,
        "company_name": "Demo Company SL",
        "company_tax_id": "B12345678",
    },
    timeout=120,
)
result = resp.json()
if resp.ok:
    invoice = result["data"]
    print(invoice["supplier"]["name"], invoice["ref_supplier"], invoice["total_ttc"])
else:
    print(resp.status_code, result.get("error") or result.get("message"))
$dataUri = 'data:application/pdf;base64,' . base64_encode(file_get_contents('invoice.pdf'));

$ch = curl_init('https://upinvoice.eu/api/process-document');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('UPINVOICE_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)), // reuse it if you retry
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'document_type' => 'supplier_invoice',
        'invoice_file' => $dataUri,
        'company_name' => 'Demo Company SL',
        'company_tax_id' => 'B12345678',
    ]),
]);
$result = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($status === 200) {
    $invoice = $result['data'];
    echo $invoice['supplier']['name'], ' ', $invoice['ref_supplier'], ' ', $invoice['total_ttc'], PHP_EOL;
} else {
    echo $status, ' ', $result['error'] ?? $result['message'] ?? '', PHP_EOL;
}
curl -sS https://upinvoice.eu/api/process-document \
  -H "Authorization: Bearer $UPINVOICE_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --max-time 120 \
  -d @- <<EOF
{
  "document_type": "supplier_invoice",
  "invoice_file": "data:application/pdf;base64,$(base64 -w0 invoice.pdf)",
  "company_name": "Demo Company SL",
  "company_tax_id": "B12345678"
}
EOF

Para agentes de IA

Todo lo que necesita un asistente de IA para crear una integración o para leer facturas por ti.

Agent Skill

Instrucciones, reglas de los campos y un script de ayuda para que un agente de IA (Claude Code y otros agentes compatibles con SKILL.md) escriba una integración correcta a la primera.

Abrir →

Servidor MCP

Conecta Claude, Cursor o cualquier cliente MCP a UpInvoice y deja que extraiga facturas y pedidos como una herramienta más.

Abrir →

OpenAPI 3.1

Referencia legible por máquinas: impórtala en Postman, genera un cliente o pásasela a tu asistente de IA.

Abrir →

llms.txt

Resumen de UpInvoice para modelos de lenguaje: producto, tipos de documento, precios y enlaces.

Abrir →

¿Usas Dolibarr?

No necesitas programar: el módulo gratuito de UpInvoice para Dolibarr ya usa esta API y crea las facturas y los pedidos por ti.

Ver el módulo para Dolibarr →