API de extracción de facturas: cómo pasar facturas a JSON

Una API de extracción de facturas recibe una factura en PDF o imagen y devuelve JSON estructurado: los campos de cabecera (número de factura, proveedor, fechas y totales) más las líneas de factura, cada valor con su puntuación de confianza y, en las mejores, el lugar de la página del que se leyó. Con anyformat describes los campos una sola vez como esquema, ejecutas un workflow y lees el resultado. Esta guía muestra el flujo completo con código, qué devuelve la API, cuánto cuesta y cómo se compara con otras formas de hacerlo. Última evaluación: octubre de 2026.

Qué debería devolver una API de extracción de facturas

Para cuentas a pagar, lo útil no es el texto, sino un registro que puedas contabilizar en un ERP o en un programa de contabilidad:

• Campos de cabecera: número de factura, nombre del proveedor, fecha de emisión, fecha de vencimiento, moneda, base imponible, importe del impuesto, importe total.
• Líneas de factura: descripción, cantidad, precio unitario e importe de cada fila.
• Una puntuación de confianza por valor, para decidir qué se contabiliza automáticamente y qué revisa una persona.
• Evidencia: el texto y la página de los que salió cada valor, para que quien revise lo compruebe en segundos en lugar de releer la factura.
• Sin valores inventados: cuando un campo no está en el documento, la respuesta correcta es vacío, no una suposición.

Los dos últimos son lo que separa una API de extracción de un OCR con un script por encima. Para el caso general, mira cómo extraer datos estructurados de un PDF con un LLM.

El flujo: tres llamadas

La API tiene tres pasos. Crea un workflow con un esquema, sube una factura y ejecútalo, y recoge el resultado.

1. Crea el workflow (un nodo parse y un nodo extract, conectados):

curl -X POST 'https://api.anyformat.ai/v3/workflows/' \
  -H "Authorization: Bearer $ANYFORMAT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Invoice extractor",
    "nodes": [
      { "id": "parse_1", "type": "parse" },
      {
        "id": "extract_1",
        "type": "extract",
        "extraction_schema": {
          "fields": [
            { "name": "invoice_number", "description": "Invoice ID printed on the document", "data_type": "string" },
            { "name": "vendor_name", "description": "Company that issued the invoice", "data_type": "string" },
            { "name": "issue_date", "description": "Date the invoice was issued", "data_type": "date" },
            { "name": "due_date", "description": "Payment due date", "data_type": "date" },
            { "name": "subtotal", "description": "Total before tax", "data_type": "float" },
            { "name": "tax_amount", "description": "Total tax", "data_type": "float" },
            { "name": "total_amount", "description": "Grand total to pay", "data_type": "float" },
            { "name": "currency", "description": "Currency of the amounts", "data_type": "enum",
              "enum_options": [
                { "name": "USD", "description": "US dollar" },
                { "name": "EUR", "description": "Euro" },
                { "name": "GBP", "description": "Pound sterling" }
              ] },
            {
              "name": "line_items",
              "description": "One row per line on the invoice",
              "data_type": "object",
              "nested_fields": [
                { "name": "description", "data_type": "string" },
                { "name": "quantity", "data_type": "integer" },
                { "name": "unit_price", "data_type": "float" },
                { "name": "amount", "data_type": "float" }
              ]
            }
          ]
        }
      }
    ],
    "edges": [ { "source": "parse_1", "target": "extract_1" } ]
  }'
# returns { "id": "<workflow_id>", ... }

2. Sube una factura y ejecútalo:

curl -X POST "https://api.anyformat.ai/v3/workflows/<workflow_id>/upload/run/" \
  -H "Authorization: Bearer $ANYFORMAT_API_KEY" \
  -F "files=@invoice.pdf"
# returns 202 { "run_id": "<run_id>", "document_packet_id": "...", "workflow_id": "...", "status": "queued" }

3. Recoge el resultado. El endpoint responde siempre 200; el campo status indica en qué punto está la ejecución (queued, in_progress, processed, error o cancelled) y los resultados aparecen cuando es processed:

curl -H "Authorization: Bearer $ANYFORMAT_API_KEY" \
  "https://api.anyformat.ai/v3/runs/<run_id>/"

El mismo flujo como función de Python, con sondeo y espera creciente (instala antes la librería con pip install requests):

import os
import time
import requests
 
API = "https://api.anyformat.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['ANYFORMAT_API_KEY']}"}
 
 
def extract_invoice(path: str, workflow_id: str) -> dict:
    with open(path, "rb") as f:
        run = requests.post(
            f"{API}/v3/workflows/{workflow_id}/upload/run/",
            headers=HEADERS,
            files={"files": f},
            timeout=60,
        )
    run.raise_for_status()
    run_id = run.json()["run_id"]
 
    url = f"{API}/v3/runs/{run_id}/"
    delay = 4
    for _ in range(60):
        res = requests.get(url, headers=HEADERS, timeout=30)
        res.raise_for_status()
        body = res.json()
        status = body["status"]
        if status == "processed":
            return body["results"]["extractions"][0]["fields"]
        if status in ("error", "cancelled"):
            raise RuntimeError(f"Run {run_id} ended with status {status}")
        time.sleep(delay)  # queued or in_progress
        delay = min(delay * 2, 30)
    raise TimeoutError("Invoice still processing after 60 attempts")
 
 
fields = extract_invoice("invoice.pdf", workflow_id="<workflow_id>")
print(fields["invoice_number"]["value"], fields["total_amount"]["value"])

Los envíos están limitados a 60 peticiones por minuto y el resto de endpoints a 600. Envía una cabecera Idempotency-Key en las peticiones POST para que un reintento no duplique el trabajo. Consulta la referencia de la API.

Qué devuelve la API

Cada campo de results.extractions[0].fields devuelve su valor, una puntuación de confianza, un estado de verificación y la evidencia de la que se leyó. Salida real para una factura ficticia, recortada a dos campos de cabecera y a la primera línea:

{
  "invoice_number": {
    "value": "INV-2026-0417",
    "value_override": null,
    "verification_status": "not_verified",
    "confidence": 91.0,
    "evidence": [
      {
        "text": "Invoice number: INV-2026-0417\nIssue date: 2026-09-15\nDue date: 2026-10-15",
        "page_number": 1
      }
    ]
  },
  "total_amount": {
    "value": "2141.7",
    "value_override": null,
    "verification_status": "not_verified",
    "confidence": 92.0,
    "evidence": [
      {
        "text": "Total due (EUR) 2,141.70",
        "page_number": 1
      }
    ]
  },
  "line_items": [
    {
      "description": {
        "value": "Cloud hosting, September",
        "value_override": null,
        "verification_status": "not_verified",
        "confidence": 98.0,
        "evidence": [
          {
            "text": "Cloud hosting, September | 1 | 1,200.00 | 1,200.00",
            "page_number": 1
          }
        ]
      },
      "amount": {
        "value": "1200.0",
        "value_override": null,
        "verification_status": "not_verified",
        "confidence": 98.0,
        "evidence": [
          {
            "text": "Cloud hosting, September | 1 | 1,200.00 | 1,200.00",
            "page_number": 1
          }
        ]
      }
    }
  ]
}

Tres detalles que ahorran tiempo de depuración:

• Los valores llegan como cadenas de texto, también los números y las fechas. Conviértelos con el tipo de dato que declaraste.
• null significa que no se ha encontrado. El modelo no inventa un valor cuando el documento no lo contiene; usa la puntuación de confianza para decidir qué revisar.
• Las líneas de factura llegan como una lista de filas. fields["line_items"] es una lista con una entrada por cada fila de la factura, y cada entrada asocia el nombre de una columna (description, quantity, unit_price, amount) con una celda con la misma forma que cualquier otro campo: value, confidence y evidence.

Una puntuación de confianza solo sirve si actúas sobre ella: fija un umbral, contabiliza automáticamente las facturas que lo superan y envía el resto a una persona que vea la evidencia junto al valor.

Formas de extraer datos de facturas, comparadas

AWS Textract y Azure listan sus modelos de factura preentrenados a 10 $ por 1.000 páginas, más barato por página que una API basada en esquema, y encajan bien cuando tus facturas se ajustan a su modelo y trabajas en una sola nube. Google factura por documento, 0,10 $ hasta 10 páginas, así que una factura de una página sale más cara por página que en cualquier otra opción de esta tabla. La contrapartida de las tres son los campos personalizados: un campo que no habían previsto obliga a entrenar o a usar una segunda herramienta.

Cuánto cuesta

Los precios se basan en créditos, por página y por operador. A tarifa pública, Parse Standard son 25 créditos y Extract Standard 35 créditos por página, así que una página de factura son 60 créditos. Un crédito cuesta 0,001 € en Business y 0,0015 € en Free y pago por uso: son 0,06 € por página en Business, o 60 € por 1.000 páginas, y 0,09 € por página en pago por uso. El modo Agentic, para facturas densas o complejas, cuesta 100 créditos en Parse y 150 en Extract. El plan Free incluye 50.000 créditos únicos sin tarjeta de crédito, lo que cubre unas 800 facturas de una página a tarifas Standard.

Es más por página que los modelos de factura preentrenados de AWS y Azure, a 10 $ por 1.000 páginas. La diferencia paga un esquema que controlas, evidencia para cada valor y la misma API para otros tipos de documento. Haz las cuentas con tu propio volumen antes de elegir.

Límites, dichos con claridad

• Escaneos y fotos: la precisión baja con la inclinación, el ruido y la letra manuscrita. Usa un umbral de confianza y un paso de revisión para estos casos.
• Facturas de varias páginas: prueba una factura larga de cada proveedor con el que trabajes; las tablas densas que cruzan páginas son para lo que sirve el modo Agentic, y el modo Agentic todavía no admite documentos de varios archivos.
• Varias facturas en un mismo PDF: añade un paso de división para extraer cada factura por separado, y lee extractions, que lista una entrada por cada documento detectado.
• Las facturas son datos de empresa y, a veces, personales. La retención cero es una opción Enterprise que hay que activar para tu organización, así que en los planes Free y Business usa facturas ficticias para las pruebas y lee nuestra guía de RGPD.
• La precisión depende de tus documentos. Antes de fiarte de la cifra de cualquier proveedor, la nuestra incluida, prueba cincuenta facturas tuyas y mide la precisión por campo y el porcentaje que pasa sin intervención humana.

Cómo elegir una API de extracción de facturas

Si tus facturas encajan con un modelo preentrenado y trabajas en una sola nube, empieza por el analizador de facturas de esa nube. Si necesitas campos personalizados, varios proveedores con maquetaciones distintas o evidencia que un revisor pueda comprobar, una API basada en esquema encaja mejor. Hazle a cada proveedor la misma pregunta: cuando un valor es incorrecto, ¿qué ve mi equipo? Para el proceso completo, mira el procesamiento de facturas con anyformat y la página de cuentas a pagar.

Preguntas frecuentes

Empieza con tus documentos más difíciles. Sube las facturas que rompen tu pipeline actual, define los campos que necesitas y mira los valores con su confianza y su evidencia en la página. El plan Free incluye 50.000 créditos sin tarjeta de crédito.

Divulgación: anyformat vende extracción de documentos; el ejemplo es ficticio y los criterios de comparación y las fechas se indican.