Documentação da API

Envie um PDF, um documento Word ou uma imagem e receba JSON estruturado.

Introdução

Descreve os dados que pretende como uma categoria: uma lista de campos, como número da fatura, data ou linhas de artigos, configurada no painel. O Parsevix lê o documento, preenche esses campos e devolve-os em JSON, juntamente com o texto que leu e o local onde cada valor foi encontrado.

A API é servida por HTTPS a partir de um único URL base. Os pedidos e as respostas são JSON, exceto os carregamentos de ficheiros, que são multipart/form-data.

https://parsevix.com/api/v1

Cada chave de API pertence a um projeto. Uma chave só vê e altera os documentos, as categorias e os webhooks desse projeto.

Além de chamar a API, pode receber resultados através de webhooks, ligar o Zapier ou enviar documentos para o endereço de e-mail de um projeto.

Convenções

As respostas da API usam nomes de campos em camelCase. Os corpos de webhooks e callbacks usam snake_case.
As datas e horas estão em UTC, no formato ISO 8601 (2026-10-25T10:12:06.791Z).
As mensagens de erro estão em inglês, alemão, turco, francês, espanhol, italiano, neerlandês, polaco ou português, conforme o cabeçalho Accept-Language.

Início rápido

1
Criar uma chave de API
No painel, abra o seu projeto, aceda a Chaves de API e crie uma chave. A chave é mostrada uma única vez; guarde-a, por exemplo, na variável de ambiente PARSEVIX_API_KEY. O plano Free inclui uma chave, os planos pagos mais (consulte Limites e créditos).
2
Definir uma categoria
Em Categorias, crie uma categoria para o seu tipo de documento e adicione os campos de que precisa, ou comece a partir de um modelo predefinido. Os exemplos desta página usam uma categoria chamada Supplier invoice.
3
Enviar um documento
POST /extract carrega o ficheiro e aguarda o resultado. A resposta contém os campos preenchidos em extracted.

Para processar muitos documentos sem manter pedidos abertos, carregue de forma assíncrona e receba os resultados através de webhooks.

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

Resposta200· 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"
        }
      ]
    }
  }
}

Tutoriais em vídeo

Cinco vídeos curtos mostram os passos principais no painel e o seu primeiro pedido à API. Cada um tem narração e legendas em nove idiomas: escolha-as no ícone da roda dentada do leitor.

Os vídeos são reproduzidos a partir do YouTube (youtube-nocookie.com). Nada é carregado do YouTube até clicar em reproduzir; depois, a Google recebe o seu endereço IP e pode guardar cookies. Consulte a nossa Política de Privacidade.

Autenticação

Envie a sua chave de API no cabeçalho X-API-Key em cada pedido.

X-API-Key: psvx_…

Uma chave só funciona em /api/v1; não permite iniciar sessão no painel. As chaves são criadas e revogadas em Chaves de API, no projeto. Uma chave revogada deixa de funcionar de imediato.

Mantenha as chaves no seu servidor. Quem tiver uma chave pode carregar documentos e ler os resultados do projeto, e esses carregamentos consomem os seus créditos.

Quando uma chave é recusada

Estado	Código	Significado
401	`apikey.missing`	Não foi enviado nenhum cabeçalho `X-API-Key`.
401	`apikey.invalid`	A chave não existe ou foi revogada.
403	`apikey.plan_disabled`	O plano da conta não inclui acesso à API.
403	`apikey.paused_by_plan`	A chave ou o respetivo projeto está em pausa porque o plano da conta permite menos chaves ou projetos.
403	`apikey.account_unavailable`	A conta foi encerrada ou tem a eliminação agendada.
403	`apikey.project_unavailable`	O projeto da chave foi eliminado.
429	`apikey.too_many_invalid`	Chegaram mais de 30 chaves inválidas da sua rede em 10 minutos. Aguarde `Retry-After` segundos; uma chave que funcionou recentemente não é bloqueada.

Resposta401

{
  "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 processamento

Cada carregamento é lido de uma de quatro formas.

Categoria automática (auto-classify). O Parsevix escolhe a categoria do projeto que melhor corresponde e, em seguida, extrai os respetivos campos. É usado quando não envia nenhuma categoria ou envia category=auto.
Apenas classificar (classify-only). O Parsevix escolhe a categoria que melhor corresponde e não extrai nada, para ordenar documentos por tipo. Lê as primeiras 3 páginas e custa 1 crédito por documento. Os campos podem ser extraídos mais tarde. Consulte Classificar um documento.
Categoria específica (specific). Indica a categoria; os respetivos campos são extraídos.
Sem esquema (auto-entity). Não é usada nenhuma categoria. O Parsevix devolve os campos que encontra, com os nomes das etiquetas do próprio documento. Consulte Extrair sem esquema.

O idioma do documento é detetado automaticamente. O parâmetro opcional language serve apenas de alternativa para documentos com texto insuficiente para a deteção.

Extrair um documento

POST/api/v1/extract

Carrega um documento e aguarda até estar processado. A resposta contém os campos extraídos.

filefileobrigatório: O documento: PDF, DOCX, PNG, JPEG ou TIFF, até 10 MB e 30 páginas.
categorystringopcional: Nome de uma categoria do projeto. Omita-o, ou envie auto, para deixar o Parsevix escolher.
languagestringopcional: Código ISO 639-1 de duas letras, como de. Só é usado se não for possível detetar o idioma.

Espera e limites

O pedido fica aberto até o resultado estar pronto, no máximo 285 segundos. Defina o tempo limite do seu cliente HTTP acima desse valor.
Se o processamento demorar mais, recebe 504 com document.sync_timeout e o documentId. O processamento continua; o resultado é enviado para os seus webhooks.
Se o processamento falhar, recebe 422 com document.sync_failed. reason indica o motivo; consulte motivos de falha.
Cada chave de API pode ter 5 pedidos abertos em simultâneo. Os seguintes devolvem 429 com document.sync_concurrency_limit. Um pedido que feche, ou que exceda o tempo limite, mantém o seu lugar até o documento ser processado. Para carregamentos em massa, use o carregamento assíncrono.

Resposta

idstring: Id do documento.
fileNamestring: O nome do ficheiro carregado.
statusstring: Completed.
categorystring | null: A categoria usada; null sem esquema.
processingModestring: auto-classify, specific ou auto-entity.
confidenceScorenumber: Entre 0 e 1: o grau de certeza da extração.
pageCountinteger: Páginas processadas; cada uma custa um crédito.
languagestring: Idioma detetado, ISO 639-1.
retainedboolean: Se o Parsevix guarda o ficheiro e o resultado. Consulte Retenção de dados.
extractedobject: Os campos extraídos. Consulte O resultado.

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

Resposta200· 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"
        }
      ]
    }
  }
}

Resposta422

{
  "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"
  }
}

Resposta504

{
  "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"
  }
}

Extrair sem esquema

POST/api/v1/extract-auto

Como POST /extract, mas sem categoria: o Parsevix devolve os campos que encontrar no documento.

filefileobrigatório: O documento: PDF, DOCX, PNG, JPEG ou TIFF, até 10 MB e 30 páginas.
languagestringopcional: Código ISO 639-1 de duas letras. Só é usado se não for possível detetar o idioma.

O resultado mantém-se no idioma do documento. As chaves são as etiquetas do próprio documento em snake_case (uma fatura em alemão dá rechnungsnummer) e os valores são copiados tal como estão impressos: datas no formato do documento, montantes como texto, por exemplo "2.430,09".

Use-o para explorar um novo tipo de documento. Para dados que processa automaticamente, uma categoria dá-lhe chaves fixas e valores normalizados.

A resposta tem os mesmos campos que POST /extract, com processingMode igual a auto-entity e category igual a null.

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

Classificar um documento

POST/api/v1/classify

Carrega um documento e aguarda até o Parsevix escolher uma das categorias do projeto. Não são extraídos campos. Use-o para ordenar ou encaminhar documentos por tipo.

As candidatas são as categorias do próprio projeto, não os modelos predefinidos. O Parsevix lê as primeiras 3 páginas, pelo que uma classificação custa 1 crédito, seja qual for o tamanho do documento.

filefileobrigatório: O documento: PDF, DOCX, PNG, JPEG ou TIFF, até 10 MB e 30 páginas.
languagestringopcional: Código ISO 639-1 de duas letras. Só é usado se não for possível detetar o idioma.

A espera e os erros funcionam como em POST /extract: no máximo 285 segundos, 504 com document.sync_timeout se demorar mais, 422 com document.sync_failed se não for possível processar o documento. Os 5 pedidos abertos por chave são partilhados pelos dois endpoints.

Resposta

idstring: Id do documento.
fileNamestring: O nome do ficheiro carregado.
statusstring: Completed.
categorystring: A categoria escolhida pelo Parsevix.
processingModestring: classify-only.
pageCountinteger: Páginas do documento. Foram lidas as primeiras 3.
languagestring: Idioma detetado, ISO 639-1.
retainedboolean: Se o Parsevix guarda o ficheiro. Só um documento guardado pode ser extraído mais tarde.

Extrair mais tarde

POST /documents/{id}/extract extrai os campos do documento segundo a categoria que lhe foi atribuída ou uma que indicar. Custa as páginas do documento menos o 1 crédito já pago: um documento de 5 páginas custa mais 4, 5 no total.

Para isso é necessário o ficheiro, pelo que o projeto tem de guardar os carregamentos via API (consulte Retenção de dados). Os documentos enviados a partir do painel ou por e-mail são sempre guardados. Os carregamentos assíncronos também podem ser classificados: processingMode=classify-only em POST /documents.

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

Resposta200

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

Carregar de forma assíncrona

POST/api/v1/documents

Coloca um documento em fila e responde de imediato com 202 e o registo do documento. Use-o para carregamentos em massa e para clientes que não conseguem manter um pedido aberto, como o Zapier.

filefileobrigatório: O documento: PDF, DOCX, PNG, JPEG ou TIFF, até 10 MB e 30 páginas.
categorystringopcional: Nome de uma categoria. Omita-o, ou envie auto, para deixar o Parsevix escolher.
processingModestringopcional: auto-classify, specific, auto-entity ou classify-only. Opcional: por predefinição, resulta de category. classify-only não pode ser combinado com uma categoria.
languagestringopcional: Código ISO 639-1 de duas letras. Só é usado se não for possível detetar o idioma.
callbackUrlstringopcional: Um URL https público. O Parsevix envia o resultado para lá uma vez, como um POST com o mesmo corpo de um evento de webhook.

Obter o resultado

Os webhooks do projeto recebem extraction.completed ou extraction.failed. Um carregamento classify-only envia classification.completed em vez de extraction.completed.
O callbackUrl, se indicado, recebe o mesmo evento, com as mesmas novas tentativas. Não é assinado, por isso inclua um token secreto no URL e verifique-o.
A consulta periódica de GET /documents/{id} mostra o estado e o resultado apenas se o projeto guardar os carregamentos via API (consulte Retenção de dados).

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"

Resposta202

{
  "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
}

O resultado

extracted

Um objeto cujas chaves são os nomes dos campos da categoria (fieldName no esquema da categoria). Os objetos e as listas seguem o esquema.

As datas são YYYY-MM-DD. Os números são números JSON, sem símbolos de moeda nem separadores de milhares. Um campo que não conste do documento é omitido ou fica null.

Os dados pessoais, como nomes e IBAN, são devolvidos tal como estão escritos no documento. Só são mascarados a caminho do modelo de IA e são restaurados antes de os receber.

_field_blocks

Onde cada valor foi encontrado. As chaves são caminhos de campos, como seller.name ou line_items[0].total; cada entrada lista as linhas de texto com página, caixa e texto. Um valor que não foi possível localizar não aparece aqui. Ignore as chaves que começam por _ se só precisar dos dados.

Coordenadas

PDF e DOCX: pontos PDF (1/72 de polegada). A origem é o canto inferior esquerdo da página; y é o limite superior da caixa, medido a partir de baixo.
Imagens: píxeis. A origem é o canto superior esquerdo; y é o limite superior, medido a partir de cima.

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

Os documentos do projeto, de todas as origens: o painel, a API e o e-mail.

Listar documentos

GET/api/v1/documents

Os mais recentes primeiro. Lista apenas os documentos guardados: os carregamentos via API só aparecem se o projeto os guardar.

pageintegeropcional: Número da página, a partir de 1.
pageSizeintegeropcional: De 1 a 100; predefinição 20.
statusstringopcional: Pending, Processing, Completed ou Failed.
categorystringopcional: Nome da categoria.
searchstringopcional: Parte do nome do ficheiro.
fileTypestringopcional: pdf, docx ou image.
sourcestringopcional: dashboard, api ou email.
processingModestringopcional: auto-classify, specific, auto-entity ou classify-only.

Obter um documento

GET/api/v1/documents/{id}

O documento com o respetivo resultado. outputDeanonymized são os dados extraídos, o mesmo objeto que extracted. Um documento classify-only tem a categoria em categoryName e não tem outputDeanonymized. Um documento falhado tem errorCode e errorMessage. Se o projeto não guardar os carregamentos via API, o estado está disponível, mas o resultado não.

Reprocessar um documento

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

Executa novamente a extração, por exemplo depois de alterar os campos da categoria. Corpo JSON opcional: category (um nome ou auto) e processingMode. Responde 202; o resultado chega como no carregamento assíncrono. Os créditos são cobrados novamente. Um documento classify-only é classificado novamente (1 crédito), a menos que indique uma categoria. Não é possível para carregamentos via API cujos ficheiros não foram guardados (document.files_not_retained).

Extrair um documento classificado

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

Para um documento carregado com classify-only: extrai os respetivos campos segundo a categoria que lhe foi atribuída ou a category indicada no corpo JSON opcional. Custa as páginas do documento menos o 1 crédito que a classificação custou. Responde 202; o resultado chega como no carregamento assíncrono, como extraction.completed. Para qualquer outro documento, responde 400 com document.not_classify_only; nesse caso, use o reprocessamento.

Eliminar um documento

DELETE/api/v1/documents/{id}

Elimina o documento, o respetivo ficheiro e os resultados. Responde 204.

Um id que não existe no projeto da chave devolve 404 com document.not_found.

cURL

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

Resposta200· 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"

Resposta200· 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 '{}'

Resposta202

{
  "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"

Categorias

As categorias do projeto, incluindo os modelos predefinidos (isGlobal: true). As categorias são criadas e editadas no painel.

Listar categorias

GET/api/v1/categories

Obter o esquema de uma categoria

GET/api/v1/categories/{name}

Os campos que uma categoria extrai. fieldName é a chave em extracted. fieldType é string, number, date, boolean, object ou array; os objetos e as listas têm os respetivos campos em children. O nome no caminho não distingue maiúsculas de minúsculas.

cURL

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

Resposta200· 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"

Resposta200· 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": []
        }
      ]
    }
  ]
}

Chave e créditos

GET/api/v1/me

O projeto da chave e o saldo de créditos da conta. Os créditos pertencem à conta e são partilhados por todos os seus projetos; resetsOn é o início do período seguinte. Num plano anual, o período é o ano de faturação e monthlyLimit contém os créditos do ano inteiro.

cURL

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

Resposta200

{
  "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"
  }
}

Gerir webhooks

Os webhooks podem ser geridos no painel (Webhooks) ou através destes endpoints.

Criar um webhook

POST/api/v1/webhooks

urlstringobrigatório: Um URL https público. Os endereços em redes privadas são recusados.
eventsstring[]obrigatório: Um ou mais de extraction.completed, extraction.failed e classification.completed.
filtersobjectopcional: Opcional. sources (dashboard, api, email) e categories (nomes) limitam os documentos que enviam eventos.

A resposta contém o secret de assinatura uma única vez. Guarde-o para verificar assinaturas.

Listar webhooks

GET/api/v1/webhooks

Eliminar um webhook

DELETE/api/v1/webhooks/{id}

Eventos de exemplo

GET/api/v1/webhooks/samples

Os documentos mais recentes do projeto como corpos de eventos, para testar o seu recetor. Parâmetros: event (obrigatório), limit (1–10, predefinição 3), category. Se ainda não existir nenhum documento assim, é criado um exemplo a partir do esquema da categoria.

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"] }
  }'

Resposta201

{
  "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

Quando um documento fica concluído, o Parsevix envia um POST com um corpo JSON para cada um dos webhooks do projeto. Os webhooks recebem documentos de todas as origens: painel, API e e-mail.

Eventos

Evento	Descrição
extraction.completed	Um documento foi processado. `data` contém os campos extraídos.
classification.completed	Um documento `classify-only` recebeu a sua categoria: `document.category`, com as páginas do documento em `document.page_count`. Não há `data`.
extraction.failed	Não foi possível processar um documento, incluindo um `classify-only`. `error_code` é um dos motivos de falha; `error` é a mensagem mostrada no painel.
test.ping	Enviado pelo botão Testar na página de um webhook no painel.

Cabeçalhos

Cabeçalho	Descrição
X-Webhook-Id	Id do evento. É o mesmo em todas as tentativas; use-o para ignorar duplicados. É também o `id` do corpo.
X-Webhook-Event	O nome do evento.
X-Webhook-Timestamp	Hora Unix desta tentativa, em segundos.
X-Webhook-Signature	`sha256=` seguido do HMAC-SHA256 em hexadecimal de `{timestamp}.{raw body}`, com o secret do webhook como chave.
X-Webhook-Attempt	Número da tentativa, a partir de 1.

Verificar a assinatura

Calcule o HMAC sobre o corpo bruto do pedido exatamente como foi recebido, antes de o analisar. Rejeite eventos cuja data e hora tenha mais de 5 minutos.

Responder

Responda com um estado 2xx no prazo de 10 segundos e só depois processe o evento. Qualquer outra resposta conta como falha. Os redirecionamentos não são seguidos.
As entregas falhadas são repetidas após 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas e 24 horas: 7 tentativas ao longo de cerca de 33 horas.
Responder 410 Gone desativa o webhook de imediato. Também é desativado quando três eventos falharam em todas as tentativas e nenhuma entrega teve êxito durante 3 dias. O proprietário recebe um e-mail; volte a ativá-lo no painel. Os eventos entretanto ocorridos não são reenviados.
O secret pode ser renovado no painel. O secret antigo deixa de funcionar de imediato.

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  # com mais de 5 minutos: possivelmente reenviado
    expected = hmac.new(
        secret.encode(),
        timestamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, "sha256=" + expected)

Zapier

A app Parsevix para o Zapier liga-se com uma chave de API de um projeto. Adicione-a através da ligação de convite na página Zapier do projeto, no painel, ou aqui.

Acionadores

Extraction Completed: um documento foi processado. Opcionalmente, apenas de uma categoria ou origem.
Extraction Failed: não foi possível processar um documento.
Document Classified: um documento enviado apenas para ser classificado recebeu a sua categoria, por exemplo de um endereço de e-mail configurado para apenas classificar.

Ações

Extract Document envia um ficheiro de um passo anterior, opcionalmente com uma categoria, e passa os campos extraídos aos passos seguintes. Com uma categoria escolhida, os respetivos campos podem ser mapeados enquanto constrói o Zap.
Classify Document envia um ficheiro e passa a categoria escolhida pelo Parsevix aos passos seguintes, sem extrair campos. Use-o para encaminhar documentos por tipo.

Os Zaps que ativar aparecem na página Zapier do projeto e em Webhooks.

E-mail

A partir do plano Starter, cada projeto tem um endereço de e-mail em Caixa de entrada de e-mail. Cada anexo de um e-mail enviado para esse endereço torna-se um documento; os resultados aparecem no painel e são enviados para os seus webhooks com a origem email.

Os endereços têm o formato name+inbox@inbox.parsevix.com. Consoante o plano, um projeto pode ter mais do que um, por exemplo um por fornecedor ou departamento.

Por endereço

Anexos: extrair todos os anexos segundo uma categoria fixa; deixar o Parsevix escolher a categoria e depois extrair; ou apenas escolher a categoria (classify-only, 1 crédito por documento), com os campos extraídos mais tarde, se precisar deles.
Remetentes permitidos: só é aceite e-mail destes domínios e apenas se passar o DKIM ou o SPF desse domínio, pelo que um remetente falsificado é rejeitado.

O que é processado

Anexos PDF, DOCX, PNG, JPEG e TIFF, incluindo os que estão dentro de e-mails reencaminhados. As imagens mostradas no corpo do e-mail, como logótipos de assinatura, são ignoradas.
Um e-mail pode ter até 30 MB e os seus primeiros 20 anexos tornam-se documentos. Um endereço aceita até 1000 e-mails e cria até 1000 documentos em 24 horas; acima disso, o e-mail é recusado e os anexos são listados como não importados. A receção é gratuita; cada documento custa créditos como qualquer outro.
O mesmo e-mail entregue duas vezes (mesmo Message-ID) é processado uma vez.

Erros

Os erros têm um estado HTTP e um corpo com um code estável e uma message legível. Decida com base no code; as mensagens podem mudar.

Códigos de estado

Estado	Significado
400	O pedido é inválido: um parâmetro em falta ou incorreto, um ficheiro não suportado, créditos insuficientes. `validation.failed` lista os problemas por parâmetro em `fields`.
401	Nenhuma chave de API ou uma chave inválida.
403	A chave é válida, mas não pode ser usada. Consulte Autenticação.
404	O documento, a categoria, o webhook ou o endpoint não existe neste projeto.
413	O carregamento excede o limite do pedido.
422	`POST /extract` ou `POST /classify` foi executado, mas não foi possível processar o documento.
429	Foi atingido o limite de pedidos ou de simultaneidade. Aguarde `Retry-After` segundos.
5xx	Um erro do servidor (com uma referência a indicar ao suporte), manutenção (`503`) ou tempo limite excedido (`504`).

Códigos comuns

Código	Significado
validation.file_required	Não foi enviado nenhum `file`.
document.content_not_supported	O conteúdo do ficheiro não é PDF, DOCX, PNG, JPEG nem TIFF, seja qual for o nome.
credit.file_size_exceeds_plan	O ficheiro é maior do que o plano permite.
validation.language_invalid	`language` não é um código de duas letras.
document.callback_url_*	`callbackUrl` não é um URL `https` público com, no máximo, 2000 caracteres.
credit.insufficient_credits	Não restam créditos suficientes neste período.
document.refund_pending	Está a ser analisado um reembolso da subscrição; nada é processado até estar resolvido.
category.not_found	Não existe nenhuma categoria com esse nome no projeto.
document.classify_only_category	`classify-only` foi enviado juntamente com uma categoria. O modo escolhe a categoria por si.
document.not_classify_only	`POST /documents/{id}/extract` foi chamado para um documento não carregado com `classify-only`.
document.files_not_retained	Os ficheiros do carregamento via API não foram guardados, pelo que não pode ser reprocessado.
webhook.url_*	O URL do webhook não é um URL `https` público.
*.limit_reached	Foi atingido um limite do plano, como o número de webhooks por projeto.

Motivos de falha

Porque é que um documento falhou: reason no 422 de POST /extract ou POST /classify, error_code em extraction.failed, errorCode no documento.

Código	Significado
too_many_pages	Mais de 30 páginas. Divida o ficheiro.
sync_too_many_pages	Mais páginas do que `POST /extract` e `POST /classify` aceitam.
pdf_encrypted	O PDF está protegido por palavra-passe.
file_unreadable	O ficheiro está danificado ou não é um documento válido.
no_text	Não foi encontrado texto: está em branco ou a digitalização é ilegível.
no_categories	A categoria devia ser escolhida automaticamente, mas o projeto não tem categorias.
no_schema_fields	A categoria não tem campos.
no_fields_found	Nenhum dos campos da categoria foi encontrado no documento; provavelmente está na categoria errada. Reprocesse-o com a categoria certa.
no_data_found	A extração automática não encontrou dados no documento.
insufficient_credits	O documento precisa de mais créditos do que os que restam neste período. Nada foi cobrado; reprocesse-o depois de um upgrade ou da reposição.
refund_pending	Estava a ser analisado um reembolso da subscrição. Se for recusado, reprocesse o documento.
masking_failed	Não foi possível mascarar os dados pessoais, pelo que o documento não foi enviado ao modelo de IA. Tente novamente.
worker_unavailable	O processamento esteve temporariamente indisponível. Tente novamente.
ai_failed	O modelo de IA falhou temporariamente. Tente novamente.
processing_failed	Um erro interno. Tente novamente; contacte o suporte se se repetir.
processing_timeout	O processamento parou antes de terminar (por exemplo, durante um reinício). Tente novamente.

Os últimos cinco são temporários: reprocesse o documento ou envie-o novamente. As execuções falhadas não são cobradas por página.

Resposta400

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

Resposta422

{
  "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"
  }
}

Limites e créditos

Ficheiros

PDF, DOCX, PNG, JPEG e TIFF (também com várias páginas). O tipo é determinado pelo conteúdo do ficheiro, não pelo nome.
Até 10 MB e 30 páginas por documento.

Créditos

Cada página processada custa 1 crédito. A escolha automática da categoria não tem custo adicional.
Apenas classificar (classify-only) custa 1 crédito por documento. Extrair esse documento mais tarde custa as respetivas páginas menos esse crédito, pelo que o total continua a ser 1 crédito por página.
Uma execução falhada não custa nada pelas suas páginas. O reprocessamento custa créditos novamente. A receção de e-mail é gratuita.
Quando os créditos de um período se esgotam, os carregamentos são recusados com credit.insufficient_credits até ao período seguinte ou a um upgrade. Os créditos de um documento são reservados assim que as suas páginas são contadas; se já não chegarem, por exemplo após muitos carregamentos em paralelo, o documento falha com insufficient_credits e nada é cobrado.

Taxa de pedidos

Cada chave de API pode fazer um determinado número de pedidos por minuto, consoante o plano. Todas as respostas incluem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (hora Unix). Acima do limite, recebe 429 com Retry-After.

Por plano

Plano	Pedidos / minuto	Créditos / mês	Chaves de API	Webhooks / projeto
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

Além disso: POST /extract e POST /classify aguardam no máximo 285 segundos e permitem, em conjunto, 5 pedidos abertos por chave.

Resposta429

{
  "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
  }
}

Retenção de dados

O que o Parsevix guarda de um carregamento via API é uma definição do projeto: Carregamentos via API, em Definições do projeto. Por predefinição, é Eliminar após o processamento; Guardar como os carregamentos pelo painel guarda-os.

Eliminar após o processamento: o ficheiro é eliminado quando o processamento termina e o resultado não é guardado. A resposta da API, o webhook ou o callback é a única cópia. Esses documentos não são listados e não podem ser reprocessados nem transferidos; retained é false.
Guardar como os carregamentos pelo painel: os ficheiros e os resultados ficam guardados, tal como os carregados pelo painel, até os eliminar.

Os carregamentos a partir do painel e por e-mail são sempre guardados. Os dados pessoais são mascarados antes de qualquer texto chegar ao modelo de IA; consulte Segurança.