Documentação da API

A API do ExtrAI permite extrair dados de documentos de forma programática. Toda requisição é feita por HTTPS e autenticada com uma chave de API. O endereço base é:

https://extrai.kanam.com.br/api/v1

O acesso à API está incluído em todos os planos, com limites de uso conforme o plano contratado. Você gerencia suas chaves dentro do app, em Conta → API Keys.

Autentique cada requisição enviando sua chave no cabeçalho Authorization como Bearer token. As chaves começam com extrai_live_.

Authorization: Bearer extrai_live_sua_chave_aqui

Atenção: a chave é mostrada uma única vez no momento da criação. Guarde-a em local seguro e nunca a exponha no frontend. Se vazar, revogue e gere outra.

Extrai os campos de um único PDF. A requisição usa multipart/form-data com os campos:

• file— o arquivo PDF (obrigatório).
• fields— os campos a extrair (obrigatório). Aceita um array JSON ["nome","cpf"] ou uma lista separada por vírgulas nome,cpf,valor.

Exemplo de requisição

curl -X POST https://extrai.kanam.com.br/api/v1/extract \
  -H "Authorization: Bearer extrai_live_sua_chave_aqui" \
  -F "file=@contrato_servico.pdf" \
  -F 'fields=["nome completo","CPF","valor total","data de vencimento"]'

Resposta (200)

{
  "id": "clx9a1b2c3...",
  "status": "success",
  "fileName": "contrato_servico.pdf",
  "data": {
    "nome completo": "João Carlos Lima",
    "CPF": "123.456.789-00",
    "valor total": "R$ 3.240,00",
    "data de vencimento": "15/08/2025"
  },
  "confidence": {
    "nome completo": 0.98,
    "CPF": 0.95,
    "valor total": 0.99,
    "data de vencimento": 0.97
  },
  "processedAt": "2026-06-27T14:03:21.000Z"
}

Quando um campo não é encontrado, ele retorna null e o status da resposta é partial. Recomendamos conferir dados críticos.

Envia vários PDFs de uma vez, aplicando os mesmos campos a todos. Use multipart/form-data com múltiplos arquivos no campo files, os fields e um name opcional para identificar o lote.

curl -X POST https://extrai.kanam.com.br/api/v1/batch \
  -H "Authorization: Bearer extrai_live_sua_chave_aqui" \
  -F "files=@boleto_01.pdf" \
  -F "files=@boleto_02.pdf" \
  -F "name=Boletos Julho" \
  -F 'fields=["beneficiário","valor","vencimento"]'

Resposta (202)

{
  "batchId": "clx9z8y7...",
  "status": "processing"
}

O processamento do lote é assíncrono. Use o batchId para consultar o andamento no endpoint a seguir.

Retorna o andamento de um lote e os resultados já processados.

curl https://extrai.kanam.com.br/api/v1/jobs/clx9z8y7... \
  -H "Authorization: Bearer extrai_live_sua_chave_aqui"

Resposta (200)

{
  "id": "clx9z8y7...",
  "status": "done",
  "total": 2,
  "done": 2,
  "errors": 0,
  "results": [
    {
      "id": "clxaa11...",
      "fileName": "boleto_01.pdf",
      "status": "success",
      "data": { "beneficiário": "...", "valor": "R$ 189,90", "vencimento": "10/07/2025" },
      "confidence": { "beneficiário": 0.97, "valor": 0.99, "vencimento": 0.98 }
    }
  ]
}

O campo status do lote pode ser pending, processing, done ou done_with_errors.

Para proteger a estabilidade do serviço, a API aplica limites de requisições por minuto:

• • Até 120 requisições/min por IP de origem.
• • Até 60 requisições/min por chave de API.

Ao exceder, a resposta é 429 com o cabeçalho Retry-After em segundos. Além disso, cada documento processado consome 1 unidade da cota mensal do seu plano.

Erros retornam um JSON com os campos error e message.