Documentación de la API

Envíe un PDF, un documento de Word o una imagen y reciba JSON estructurado.

Introducción

Usted describe los datos que necesita como una categoría: una lista de campos, como el número de factura, la fecha o las líneas de detalle, que se configura en el panel. Parsevix lee el documento, rellena esos campos y los devuelve en JSON, junto con el texto leído y la posición en la que se encontró cada valor.

La API se sirve por HTTPS desde una única URL base. Las solicitudes y las respuestas son JSON, salvo las subidas de archivos, que se envían como multipart/form-data.

https://parsevix.com/api/v1

Cada clave de API pertenece a un proyecto. Una clave solo ve y modifica los documentos, las categorías y los webhooks de ese proyecto.

Además de llamar a la API, puede recibir los resultados mediante webhooks, conectar Zapier o enviar documentos a la dirección de correo electrónico de un proyecto.

Convenciones

Las respuestas de la API usan nombres de campo en camelCase. Los cuerpos de los webhooks y de los callbacks usan snake_case.
Las marcas de tiempo están en UTC, en formato ISO 8601 (2026-10-25T10:12:06.791Z).
Los mensajes de error están en inglés, alemán, turco, francés, español, italiano, neerlandés, polaco o portugués, según la cabecera Accept-Language.

Inicio rápido

1
Cree una clave de API
En el panel, abra su proyecto, vaya a Claves de API y cree una clave. Solo se muestra una vez; guárdela, por ejemplo, en la variable de entorno PARSEVIX_API_KEY. El plan Free incluye una clave y los planes de pago, más (consulte Límites y créditos).
2
Defina una categoría
En Categorías, cree una categoría para su tipo de documento y añada los campos que necesite, o parta de una plantilla integrada. Los ejemplos de esta página usan una categoría llamada Supplier invoice.
3
Envíe un documento
POST /extract sube el archivo y espera el resultado. La respuesta contiene los campos rellenados en extracted.

Para procesar muchos documentos sin mantener solicitudes abiertas, cárguelos de forma asíncrona y reciba los resultados mediante webhooks.

curl https://parsevix.com/api/v1/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice"

Respuesta200· abreviado

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Tutoriales en vídeo

Cinco vídeos cortos muestran los pasos principales del panel y su primera solicitud a la API. Cada uno tiene locución y subtítulos en nueve idiomas: elíjalos en el icono del engranaje del reproductor.

Los vídeos se reproducen desde YouTube (youtube-nocookie.com). No se carga nada de YouTube hasta que pulsa reproducir; entonces Google recibe su dirección IP y puede guardar cookies. Consulte nuestra Política de privacidad.

Autenticación

Envíe su clave de API en la cabecera X-API-Key con cada solicitud.

X-API-Key: psvx_…

Una clave solo funciona en /api/v1; no permite iniciar sesión en el panel. Las claves se crean y se revocan en Claves de API dentro del proyecto. Una clave revocada deja de funcionar de inmediato.

Guarde las claves en su servidor. Cualquiera que tenga una clave puede subir documentos y leer los resultados del proyecto, y esas subidas consumen sus créditos.

Cuándo se rechaza una clave

Estado	Código	Significado
401	`apikey.missing`	No se envió la cabecera `X-API-Key`.
401	`apikey.invalid`	La clave no existe o fue revocada.
403	`apikey.plan_disabled`	El plan de la cuenta no incluye acceso a la API.
403	`apikey.paused_by_plan`	La clave o su proyecto están en pausa porque el plan de la cuenta admite menos claves o proyectos.
403	`apikey.account_unavailable`	La cuenta está cerrada o programada para su eliminación.
403	`apikey.project_unavailable`	El proyecto de la clave fue eliminado.
429	`apikey.too_many_invalid`	Desde su red llegaron más de 30 claves no válidas en 10 minutos. Espere `Retry-After` segundos; una clave que ha funcionado hace poco no se bloquea.

Respuesta401

{
  "error": {
    "code": "apikey.invalid",
    "message": "The API key is not valid. It may have been revoked; create a new one in the project under API Keys."
  }
}

Modos de procesamiento

Cada subida se lee de una de estas cuatro formas.

Categoría automática (auto-classify). Parsevix elige la categoría del proyecto que mejor encaja y extrae sus campos. Se usa cuando no envía ninguna categoría o envía category=auto.
Solo clasificar (classify-only). Parsevix elige la categoría que mejor encaja y no extrae nada; sirve para ordenar documentos por tipo. Lee las 3 primeras páginas y cuesta 1 crédito por documento. Los campos se pueden extraer más tarde. Consulte Clasificar un documento.
Categoría específica (specific). Usted indica la categoría y se extraen sus campos.
Sin esquema (auto-entity). No se usa ninguna categoría. Parsevix devuelve los campos que encuentra, con los nombres de las propias etiquetas del documento. Consulte Extraer sin esquema.

El idioma del documento se detecta automáticamente. El parámetro opcional language solo es un valor de respaldo para documentos con muy poco texto para detectarlo.

Extraer un documento

POST/api/v1/extract

Sube un documento y espera hasta que se procesa. La respuesta contiene los campos extraídos.

filefileobligatorio: El documento: PDF, DOCX, PNG, JPEG o TIFF, de hasta 10 MB y 30 páginas.
categorystringopcional: Nombre de una categoría del proyecto. Omítalo, o envíe auto, para que Parsevix la elija.
languagestringopcional: Código ISO 639-1 de dos letras, como de. Solo se usa si no se puede detectar el idioma.

Espera y límites

La solicitud permanece abierta hasta que el resultado está listo, como máximo 285 segundos. Configure el tiempo de espera de su cliente HTTP por encima de ese valor.
Si el procesamiento tarda más, recibe 504 con document.sync_timeout y el documentId. El procesamiento continúa y el resultado se envía a sus webhooks.
Si el procesamiento falla, recibe 422 con document.sync_failed. reason indica el motivo; consulte los motivos de error.
Cada clave de API puede tener 5 solicitudes abiertas a la vez. Las demás devuelven 429 con document.sync_concurrency_limit. Una solicitud que cierre, o que agote el tiempo, conserva su plaza hasta que su documento se haya procesado. Para subidas masivas, use la subida asíncrona.

Respuesta

idstring: Id del documento.
fileNamestring: Nombre del archivo subido.
statusstring: Completed.
categorystring | null: La categoría usada; null sin esquema.
processingModestring: auto-classify, specific o auto-entity.
confidenceScorenumber: Entre 0 y 1: el grado de certeza de la extracción.
pageCountinteger: Páginas procesadas; cada una cuesta un crédito.
languagestring: Idioma detectado, ISO 639-1.
retainedboolean: Si Parsevix conserva el archivo y el resultado. Consulte Conservación de datos.
extractedobject: Los campos extraídos. Consulte El resultado.

curl https://parsevix.com/api/v1/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice"

Respuesta200· abreviado

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Respuesta422

{
  "error": {
    "code": "document.sync_failed",
    "message": "The file is damaged or is not a valid PDF, Word document or image.",
    "reason": "file_unreadable",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Respuesta504

{
  "error": {
    "code": "document.sync_timeout",
    "message": "Extraction did not finish within 285 seconds. Large documents may need to be split.",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Extraer sin esquema

POST/api/v1/extract-auto

Como POST /extract, pero sin categoría: Parsevix devuelve todos los campos que encuentra en el documento.

filefileobligatorio: El documento: PDF, DOCX, PNG, JPEG o TIFF, de hasta 10 MB y 30 páginas.
languagestringopcional: Código ISO 639-1 de dos letras. Solo se usa si no se puede detectar el idioma.

La salida se mantiene en el idioma del documento. Las claves son las propias etiquetas del documento en snake_case (una factura en alemán da rechnungsnummer), y los valores se copian tal como aparecen impresos: las fechas en el formato del documento y los importes como cadenas, por ejemplo "2.430,09".

Úselo para explorar un tipo de documento nuevo. Para los datos que procesa de forma automática, una categoría le ofrece claves fijas y valores normalizados.

La respuesta tiene los mismos campos que POST /extract, con processingMode auto-entity y category null.

curl https://parsevix.com/api/v1/extract-auto \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf

Clasificar un documento

POST/api/v1/classify

Sube un documento y espera hasta que Parsevix elige una de las categorías del proyecto. No se extrae ningún campo. Úselo para ordenar o encaminar documentos por tipo.

Las candidatas son las categorías propias del proyecto, no las plantillas integradas. Parsevix lee las 3 primeras páginas, por lo que una clasificación cuesta 1 crédito, sea cual sea la longitud del documento.

filefileobligatorio: El documento: PDF, DOCX, PNG, JPEG o TIFF, de hasta 10 MB y 30 páginas.
languagestringopcional: Código ISO 639-1 de dos letras. Solo se usa si no se puede detectar el idioma.

La espera y los errores funcionan igual que en POST /extract: como máximo 285 segundos, 504 con document.sync_timeout si tarda más y 422 con document.sync_failed si el documento no se puede procesar. Las 5 solicitudes abiertas por clave se comparten entre ambos endpoints.

Respuesta

idstring: Id del documento.
fileNamestring: Nombre del archivo subido.
statusstring: Completed.
categorystring: La categoría que eligió Parsevix.
processingModestring: classify-only.
pageCountinteger: Páginas del documento. Se leyeron las 3 primeras.
languagestring: Idioma detectado, ISO 639-1.
retainedboolean: Si Parsevix conserva el archivo. Solo se puede extraer más tarde un documento conservado.

Extraer más tarde

POST /documents/{id}/extract extrae los campos del documento según la categoría asignada o la que usted indique. Cuesta las páginas del documento menos el crédito ya pagado: un documento de 5 páginas cuesta 4 más, 5 en total.

Para ello se necesita el archivo, por lo que el proyecto debe conservar las subidas por API (consulte Conservación de datos). Los documentos enviados desde el panel o por correo electrónico se conservan siempre. Las subidas asíncronas también se pueden clasificar: processingMode=classify-only en POST /documents.

curl https://parsevix.com/api/v1/classify \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf

Respuesta200

{
  "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "classify-only",
  "pageCount": 1,
  "language": "en",
  "retained": true
}

Subida asíncrona

POST/api/v1/documents

Pone un documento en cola y responde de inmediato con 202 y el registro del documento. Úsela para subidas masivas y para clientes que no pueden mantener una solicitud abierta, como Zapier.

filefileobligatorio: El documento: PDF, DOCX, PNG, JPEG o TIFF, de hasta 10 MB y 30 páginas.
categorystringopcional: Nombre de una categoría. Omítalo, o envíe auto, para que Parsevix la elija.
processingModestringopcional: auto-classify, specific, auto-entity o classify-only. Opcional: de forma predeterminada se deduce de category. classify-only no se puede combinar con una categoría.
languagestringopcional: Código ISO 639-1 de dos letras. Solo se usa si no se puede detectar el idioma.
callbackUrlstringopcional: Una URL https pública. Parsevix envía allí el resultado una vez, como un POST con el mismo cuerpo que un evento de webhook.

Obtener el resultado

Los webhooks del proyecto reciben extraction.completed o extraction.failed. Una subida classify-only envía classification.completed en lugar de extraction.completed.
callbackUrl, si se indica, recibe el mismo evento, con los mismos reintentos. No está firmado, así que incluya un token secreto en la URL y compruébelo.
Consultar periódicamente GET /documents/{id} muestra el estado, y el resultado solo si el proyecto conserva las subidas por API (consulte Conservación de datos).

curl https://parsevix.com/api/v1/documents \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice" \
  -F callbackUrl="https://example.com/parsevix/callback?token=a-secret-only-you-know"

Respuesta202

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "status": "Pending",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "discardFiles": true,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": null,
  "reprocessCount": 0,
  "lastReprocessedAt": null,
  "approvalStatus": "Unapproved",
  "isTrainingExample": false
}

El resultado

extracted

Un objeto cuyas claves son los nombres de campo de la categoría (fieldName en el esquema de la categoría). Los objetos y las listas siguen el esquema.

Las fechas tienen el formato YYYY-MM-DD. Los números son números JSON, sin símbolos de moneda ni separadores de miles. Un campo que el documento no contiene se omite o es null.

Los datos personales, como nombres e IBAN, se devuelven tal como están escritos en el documento. Solo se enmascaran en el camino hacia el modelo de IA y se restauran antes de que usted los reciba.

_field_blocks

Dónde se encontró cada valor. Las claves son rutas de campo como seller.name o line_items[0].total; cada entrada enumera las líneas de texto con página, recuadro y texto. Un valor que no se pudo localizar no aparece. Ignore las claves que empiezan por _ si solo necesita los datos.

Coordenadas

PDF y DOCX: puntos PDF (1/72 de pulgada). El origen es la esquina inferior izquierda de la página; y es el borde superior del recuadro, medido desde abajo.
Imágenes: píxeles. El origen es la esquina superior izquierda; y es el borde superior, medido desde arriba.

extracted200· abreviado

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Documentos

Los documentos del proyecto, de todas las fuentes: el panel, la API y el correo electrónico.

Listar documentos

GET/api/v1/documents

Los más recientes primero. Solo lista los documentos almacenados: las subidas por API aparecen solo si el proyecto las conserva.

pageintegeropcional: Número de página, desde 1.
pageSizeintegeropcional: De 1 a 100; 20 de forma predeterminada.
statusstringopcional: Pending, Processing, Completed o Failed.
categorystringopcional: Nombre de la categoría.
searchstringopcional: Parte del nombre del archivo.
fileTypestringopcional: pdf, docx o image.
sourcestringopcional: dashboard, api o email.
processingModestringopcional: auto-classify, specific, auto-entity o classify-only.

Obtener un documento

GET/api/v1/documents/{id}

El documento con su resultado. outputDeanonymized son los datos extraídos, el mismo objeto que extracted. Un documento classify-only tiene su categoría en categoryName y no tiene outputDeanonymized. Un documento fallido tiene errorCode y errorMessage. Si el proyecto no conserva las subidas por API, el estado está disponible, pero el resultado no.

Volver a procesar un documento

POST/api/v1/documents/{id}/reprocess

Vuelve a ejecutar la extracción, por ejemplo después de cambiar los campos de la categoría. Cuerpo JSON opcional: category (un nombre o auto) y processingMode. Responde 202; el resultado llega como el de una subida asíncrona. Los créditos se cobran de nuevo. Un documento classify-only se vuelve a clasificar (1 crédito) salvo que indique una categoría. No es posible para subidas por API cuyos archivos no se conservaron (document.files_not_retained).

Extraer un documento clasificado

POST/api/v1/documents/{id}/extract

Para un documento subido con classify-only: extrae sus campos según la categoría asignada o según la category indicada en el cuerpo JSON opcional. Cuesta las páginas del documento menos el crédito que costó la clasificación. Responde 202; el resultado llega como el de una subida asíncrona, como extraction.completed. Para cualquier otro documento responde 400 con document.not_classify_only; en ese caso, vuelva a procesarlo.

Eliminar un documento

DELETE/api/v1/documents/{id}

Elimina el documento, su archivo y sus resultados. Responde 204.

Un id que no existe en el proyecto de la clave devuelve 404 con document.not_found.

cURL

curl "https://parsevix.com/api/v1/documents?status=Completed&pageSize=20" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Respuesta200· abreviado

{
  "data": [
    {
      "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
      "status": "Completed",
      "categoryName": "Supplier invoice",
      "processingMode": "specific",
      "fileName": "invoice.pdf",
      "fileSize": 22579,
      "source": "api",
      "discardFiles": false,
      "createdAt": "2026-10-25T10:12:06.791Z",
      "completedAt": "2026-10-25T10:12:15.212Z",
      "reprocessCount": 0,
      "lastReprocessedAt": null,
      "approvalStatus": "Unapproved",
      "isTrainingExample": false
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20
}

curl https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581 \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Respuesta200· abreviado

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "status": "Completed",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "language": "en",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "outputDeanonymized": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  },
  "errorMessage": null,
  "errorCode": null,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": "2026-10-25T10:12:15.212Z"
}

cURL

curl https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581/reprocess \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category": "auto"}'

cURL

curl https://parsevix.com/api/v1/documents/01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Respuesta202

{
  "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
  "status": "Pending",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "discardFiles": false,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": null,
  "reprocessCount": 1,
  "lastReprocessedAt": "2026-10-25T11:04:12.530Z",
  "approvalStatus": "Unapproved",
  "isTrainingExample": false
}

cURL

curl -X DELETE https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581 \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Categorías

Las categorías del proyecto, incluidas las plantillas integradas (isGlobal: true). Las categorías se crean y se editan en el panel.

Listar categorías

GET/api/v1/categories

Obtener el esquema de una categoría

GET/api/v1/categories/{name}

Los campos que extrae una categoría. fieldName es la clave en extracted. fieldType es string, number, date, boolean, object o array; los objetos y los arrays tienen sus campos en children. El nombre de la ruta no distingue entre mayúsculas y minúsculas.

cURL

curl https://parsevix.com/api/v1/categories \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Respuesta200· abreviado

[
  {
    "id": 1,
    "name": "Invoice",
    "description": "Invoices and billing documents with seller/buyer info, line items, and totals",
    "isGlobal": true,
    "fieldCount": 48
  },
  {
    "id": 54,
    "name": "Supplier invoice",
    "description": "Commercial invoice: seller, buyer, line items and totals.",
    "isGlobal": false,
    "fieldCount": 26
  }
]

cURL

curl "https://parsevix.com/api/v1/categories/Supplier%20invoice" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Respuesta200· abreviado

{
  "id": 54,
  "name": "Supplier invoice",
  "description": "Commercial invoice: seller, buyer, line items and totals.",
  "fields": [
    {
      "fieldName": "invoice_number",
      "displayName": "Invoice number",
      "fieldType": "string",
      "description": null,
      "children": []
    },
    {
      "fieldName": "invoice_date",
      "displayName": "Invoice date",
      "fieldType": "date",
      "description": null,
      "children": []
    },
    {
      "fieldName": "seller",
      "displayName": "Seller",
      "fieldType": "object",
      "description": null,
      "children": [
        {
          "fieldName": "name",
          "displayName": "Name",
          "fieldType": "string",
          "description": null,
          "children": []
        },
        {
          "fieldName": "vat_id",
          "displayName": "VAT / tax id",
          "fieldType": "string",
          "description": null,
          "children": []
        }
      ]
    }
  ]
}

Clave y créditos

GET/api/v1/me

El proyecto de la clave y el saldo de créditos de la cuenta. Los créditos pertenecen a la cuenta y los comparten todos sus proyectos; resetsOn es el inicio del siguiente periodo. En un plan anual, el periodo es el año de facturación y monthlyLimit contiene los créditos de todo el año.

cURL

curl https://parsevix.com/api/v1/me \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Respuesta200

{
  "projectId": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "projectName": "Accounts payable",
  "projectSlug": "accounts-payable",
  "keyName": "ERP connector",
  "keyPrefix": "psvx_nyskxlv",
  "email": "you@example.com",
  "credits": {
    "period": "2026-10-04",
    "resetsOn": "2026-11-04",
    "monthlyLimit": 1000,
    "used": 312,
    "remaining": 688,
    "planName": "Growth"
  }
}

Gestionar webhooks

Los webhooks se pueden gestionar en el panel (Webhooks) o mediante estos endpoints.

Crear un webhook

POST/api/v1/webhooks

urlstringobligatorio: Una URL https pública. Se rechazan las direcciones de redes privadas.
eventsstring[]obligatorio: Uno o varios de extraction.completed, extraction.failed y classification.completed.
filtersobjectopcional: Opcional. sources (dashboard, api, email) y categories (nombres) limitan qué documentos envían eventos.

La respuesta contiene el secret de firma una sola vez. Guárdelo para verificar las firmas.

Listar webhooks

GET/api/v1/webhooks

Eliminar un webhook

DELETE/api/v1/webhooks/{id}

Eventos de ejemplo

GET/api/v1/webhooks/samples

Los últimos documentos del proyecto como cuerpos de evento, para probar su receptor. Parámetros de consulta: event (obligatorio), limit (1–10, 3 de forma predeterminada), category. Si aún no hay ningún documento así, se genera un ejemplo a partir del esquema de la categoría.

cURL

curl https://parsevix.com/api/v1/webhooks \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/parsevix/webhook",
    "events": ["extraction.completed", "extraction.failed"],
    "filters": { "sources": ["api", "email"] }
  }'

Respuesta201

{
  "secret": "d0726faeb5c655d349fc30ed226e93e531ac2499800aacde100e83554b48701c",
  "id": "01a17295-c761-7b8f-b173-388bc754b1ba",
  "url": "https://example.com/parsevix/webhook",
  "events": [
    "extraction.completed",
    "extraction.failed"
  ],
  "filters": {
    "sources": [
      "api",
      "email"
    ],
    "categories": null
  },
  "isActive": true,
  "disabledAt": null,
  "disabledReason": null,
  "managedBy": null,
  "createdAt": "2026-10-25T10:23:09.311Z"
}

cURL

curl "https://parsevix.com/api/v1/webhooks/samples?event=extraction.completed&limit=1" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Webhooks

Cuando un documento termina, Parsevix envía un POST con un cuerpo JSON a cada uno de los webhooks del proyecto. Los webhooks reciben documentos de todas las fuentes: panel, API y correo electrónico.

Eventos

Evento	Descripción
extraction.completed	Se procesó un documento. `data` contiene los campos extraídos.
classification.completed	Un documento `classify-only` recibió su categoría: `document.category`, con las páginas del documento en `document.page_count`. No hay `data`.
extraction.failed	No se pudo procesar un documento, también uno `classify-only`. `error_code` es uno de los motivos de error; `error` es el mensaje que se muestra en el panel.
test.ping	Lo envía el botón Probar de la página de un webhook en el panel.

Cabeceras

Cabecera	Descripción
X-Webhook-Id	Id del evento. Es el mismo en todos los intentos; úselo para ignorar duplicados. También es el `id` del cuerpo.
X-Webhook-Event	El nombre del evento.
X-Webhook-Timestamp	Hora Unix de este intento, en segundos.
X-Webhook-Signature	`sha256=` seguido del HMAC-SHA256 en hexadecimal de `{timestamp}.{raw body}`, con el secreto del webhook como clave.
X-Webhook-Attempt	Número de intento, desde 1.

Verificar la firma

Calcule el HMAC sobre el cuerpo sin procesar de la solicitud exactamente como se recibió, antes de analizarlo. Rechace los eventos cuya marca de tiempo tenga más de 5 minutos.

Responder

Responda con un estado 2xx en un plazo de 10 segundos y procese después el evento. Cualquier otra respuesta cuenta como fallo. Las redirecciones no se siguen.
Las entregas fallidas se reintentan al cabo de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas y 24 horas: 7 intentos en unas 33 horas.
Responder 410 Gone desactiva el webhook de inmediato. También se desactiva cuando tres eventos han fallado en todos sus intentos y ninguna entrega ha tenido éxito durante 3 días. El propietario recibe un correo electrónico; vuelva a activarlo en el panel. Los eventos intermedios no se vuelven a enviar.
El secreto se puede rotar en el panel. El secreto anterior deja de funcionar de inmediato.

extraction.completed200· abreviado

{
  "id": "01a172a0-3f1e-7d42-9b6c-8e2f5a7d1c90",
  "event": "extraction.completed",
  "timestamp": "2026-10-25T10:12:21.592Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "specific",
    "language": "en",
    "confidence_score": 0.97
  },
  "data": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

classification.completed200

{
  "id": "01a172b5-8e47-7a13-b2c9-4f6d0a8e3b51",
  "event": "classification.completed",
  "timestamp": "2026-10-25T10:14:02.334Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "classify-only",
    "language": "en",
    "page_count": 1
  }
}

extraction.failed200

{
  "id": "01a172a1-0c55-7e18-a3d4-6b9f2e8c1d07",
  "event": "extraction.failed",
  "timestamp": "2026-10-25T10:12:23.711Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "specific"
  },
  "error_code": "file_unreadable",
  "error": "The file is damaged or is not a valid PDF, Word document or image."
}

import hashlib
import hmac
import time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"]  # "sha256=<hex>"
    if abs(time.time() - int(timestamp)) > 300:
        return False  # más de 5 minutos de antigüedad: posiblemente reenviado
    expected = hmac.new(
        secret.encode(),
        timestamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, "sha256=" + expected)

Zapier

La aplicación de Parsevix para Zapier se conecta con una clave de API de un proyecto. Añádala mediante el enlace de invitación de la página Zapier del proyecto en el panel o aquí.

Disparadores

Extraction Completed: se procesó un documento. Opcionalmente, solo de una categoría o fuente.
Extraction Failed: no se pudo procesar un documento.
Document Classified: un documento enviado solo para clasificarlo recibió su categoría, por ejemplo desde una dirección de correo electrónico configurada para solo clasificar.

Acciones

Extract Document envía un archivo de un paso anterior, opcionalmente con una categoría, y pasa los campos extraídos a los pasos siguientes. Si elige una categoría, puede asignar sus campos mientras crea el Zap.
Classify Document envía un archivo y pasa a los pasos siguientes la categoría que eligió Parsevix, sin extraer campos. Úsela para encaminar documentos por tipo.

Los Zaps que active aparecen en la página Zapier del proyecto y en Webhooks.

Correo electrónico

A partir del plan Starter, cada proyecto tiene una dirección de correo electrónico en Bandeja de entrada de correo. Cada archivo adjunto de un correo enviado a ella se convierte en un documento; los resultados aparecen en el panel y se envían a sus webhooks con la fuente email.

Las direcciones tienen el formato name+inbox@inbox.parsevix.com. Según el plan, un proyecto puede tener más de una, por ejemplo una por proveedor o departamento.

Por dirección

Qué ocurre con los adjuntos: extraer cada adjunto con una categoría fija; dejar que Parsevix elija la categoría y luego extraer; o solo elegir la categoría (classify-only, 1 crédito por documento) y extraer los campos más tarde si los necesita.
Remitentes permitidos: solo se acepta el correo de estos dominios, y solo si supera DKIM o SPF para ese dominio, de modo que se rechaza un remitente falsificado.

Qué se procesa

Archivos adjuntos PDF, DOCX, PNG, JPEG y TIFF, incluidos los de correos reenviados. Las imágenes que se muestran en el cuerpo del correo, como los logotipos de las firmas, se omiten.
Un correo puede tener hasta 30 MB, y sus 20 primeros adjuntos se convierten en documentos. Una dirección acepta hasta 1.000 correos y genera hasta 1.000 documentos en 24 horas; por encima de eso, el correo se rechaza y los adjuntos figuran como no importados. La recepción es gratuita; cada documento cuesta créditos como cualquier otro.
El mismo correo entregado dos veces (mismo Message-ID) se procesa una sola vez.

Errores

Los errores tienen un estado HTTP y un cuerpo con un code estable y un message legible. Tome decisiones según code; los mensajes pueden cambiar.

Códigos de estado

Estado	Significado
400	La solicitud no es válida: un parámetro ausente o incorrecto, un archivo no admitido, créditos insuficientes. `validation.failed` enumera los problemas por parámetro en `fields`.
401	No hay clave de API o no es válida.
403	La clave es válida, pero no se puede usar. Consulte Autenticación.
404	El documento, la categoría, el webhook o el endpoint no existe en este proyecto.
413	La subida supera el límite de tamaño de la solicitud.
422	`POST /extract` o `POST /classify` se ejecutó, pero el documento no se pudo procesar.
429	Se alcanzó el límite de frecuencia o de simultaneidad. Espere los segundos indicados en `Retry-After`.
5xx	Un error del servidor (con una referencia para indicar al soporte), mantenimiento (`503`) o un tiempo de espera agotado (`504`).

Códigos habituales

Código	Significado
validation.file_required	No se envió ningún `file`.
document.content_not_supported	El contenido del archivo no es PDF, DOCX, PNG, JPEG ni TIFF, diga lo que diga su nombre.
credit.file_size_exceeds_plan	El archivo es más grande de lo que permite el plan.
validation.language_invalid	`language` no es un código de dos letras.
document.callback_url_*	`callbackUrl` no es una URL `https` pública de 2000 caracteres como máximo.
credit.insufficient_credits	No quedan créditos suficientes en este periodo.
document.refund_pending	Se está revisando un reembolso de la suscripción; no se procesa nada hasta que se resuelva.
category.not_found	No hay ninguna categoría con ese nombre en el proyecto.
document.classify_only_category	Se envió `classify-only` junto con una categoría. Este modo elige la categoría por sí mismo.
document.not_classify_only	Se llamó a `POST /documents/{id}/extract` para un documento que no se cargó con `classify-only`.
document.files_not_retained	Los archivos de la subida por API no se conservaron, por lo que no se puede volver a procesar.
webhook.url_*	La URL del webhook no es una URL `https` pública.
*.limit_reached	Se alcanzó un límite del plan, como el número de webhooks por proyecto.

Motivos de error

Por qué falló un documento: reason en el 422 de POST /extract o POST /classify, error_code en extraction.failed y errorCode en el documento.

Código	Significado
too_many_pages	Más de 30 páginas. Divida el archivo.
sync_too_many_pages	Más páginas de las que aceptan `POST /extract` y `POST /classify`.
pdf_encrypted	El PDF está protegido con contraseña.
file_unreadable	El archivo está dañado o no es un documento válido.
no_text	No se encontró texto: está en blanco o el escaneo es ilegible.
no_categories	La categoría debía elegirse automáticamente, pero el proyecto no tiene categorías.
no_schema_fields	La categoría no tiene campos.
no_fields_found	No se encontró en el documento ninguno de los campos de la categoría; probablemente está en la categoría equivocada. Reprocéselo con la correcta.
no_data_found	La extracción automática no encontró datos en el documento.
insufficient_credits	El documento necesita más créditos de los que quedan en este periodo. No se cobró nada; vuelva a procesarlo tras mejorar el plan o cuando se restablezcan los créditos.
refund_pending	Se estaba revisando un reembolso de la suscripción. Si se rechaza, reprocese el documento.
masking_failed	Los datos personales no se pudieron enmascarar, por lo que el documento no se envió al modelo de IA. Vuelva a intentarlo.
worker_unavailable	El procesamiento no estaba disponible temporalmente. Vuelva a intentarlo.
ai_failed	El modelo de IA falló temporalmente. Vuelva a intentarlo.
processing_failed	Un error interno. Vuelva a intentarlo; si se repite, contacte con el soporte.
processing_timeout	El procesamiento se detuvo antes de terminar (por ejemplo, durante un reinicio). Vuelva a intentarlo.

Los cinco últimos son temporales: reprocese el documento o envíelo de nuevo. Las ejecuciones fallidas no se cobran por página.

Respuesta400

{
  "error": {
    "code": "validation.failed",
    "message": "The file field is required.",
    "fields": {
      "file": [
        "The file field is required."
      ]
    }
  }
}

Respuesta422

{
  "error": {
    "code": "document.sync_failed",
    "message": "The file is damaged or is not a valid PDF, Word document or image.",
    "reason": "file_unreadable",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Límites y créditos

Archivos

PDF, DOCX, PNG, JPEG y TIFF (también de varias páginas). El tipo se determina por el contenido del archivo, no por su nombre.
Hasta 10 MB y 30 páginas por documento.

Créditos

Cada página procesada cuesta 1 crédito. Elegir la categoría automáticamente no tiene coste adicional.
Solo clasificar (classify-only) cuesta 1 crédito por documento. Extraer más tarde un documento así cuesta sus páginas menos ese crédito, por lo que el total sigue siendo 1 crédito por página.
Una ejecución fallida no cuesta nada por sus páginas. Volver a procesar un documento cuesta créditos de nuevo. La recepción de correo electrónico es gratuita.
Cuando se agotan los créditos de un periodo, las subidas se rechazan con credit.insufficient_credits hasta el siguiente periodo o hasta que mejore el plan. Los créditos de un documento se reservan en cuanto se cuentan sus páginas; si ya no alcanzan, por ejemplo tras muchas subidas en paralelo, el documento falla con insufficient_credits y no se cobra nada.

Frecuencia de solicitudes

Cada clave de API puede hacer un número de solicitudes por minuto que depende del plan. Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (hora Unix). Si supera el límite, recibe 429 con Retry-After.

Por plan

Plan	Solicitudes / minuto	Créditos / mes	Claves de API	Webhooks / proyecto
Free	10	20	1	1
Starter	30	500	2	2
Growth	60	2000	3	5
Pro	120	6000	10	10
Business	300	20.000	ilimitado	25

Además: POST /extract y POST /classify esperan como máximo 285 segundos y admiten entre ambos 5 solicitudes abiertas por clave.

Respuesta429

{
  "error": {
    "code": "apikey.rate_limited",
    "message": "Too many requests for this API key: the limit is 60 per minute. Retry in 18 s.",
    "limit": 60,
    "retryAfterSeconds": 18
  }
}

Conservación de datos

Lo que Parsevix conserva de una subida por API es un ajuste del proyecto: Subidas por API, en Configuración del proyecto. De forma predeterminada está elegido Eliminar después del procesamiento.

Eliminar después del procesamiento: el archivo se elimina cuando termina el procesamiento y el resultado no se almacena. La respuesta de la API, el webhook o el callback es la única copia. Estos documentos no aparecen en la lista y no se pueden volver a procesar ni descargar; retained es false.
Conservar como las subidas del panel: los archivos y los resultados se almacenan como las subidas desde el panel, hasta que usted los elimine.

Las subidas desde el panel y por correo electrónico se almacenan siempre. Los datos personales se enmascaran antes de que cualquier texto llegue al modelo de IA; consulte Seguridad.