Envie um documento.
Receba dados estruturados e validados.

Autenticação

Toda chamada, exceto o login, exige um token. Faça Login, guarde o token retornado e envie-o no cabeçalho Authorization em todas as requisições seguintes.

Authorization: Bearer {{token}}
Accept: application/json

A base de todos os caminhos é a variável {{endpoint_base}} da collection. As variáveis token, webhook_id e delivery_id são preenchidas conforme você avança.

Padrão de retorno

As respostas seguem uma estrutura previsível. Em caso de sucesso, os dados vêm em data; mensagens legíveis vêm em message.

Sucesso

{
  "message": "Operação realizada.",
  "data": { /* recurso ou lista */ }
}

Erro de validação (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "url": ["The url must be a valid HTTPS URL."]
  }
}

Collection do Postman

Importe a collection para ter todos os endpoints prontos, com variáveis e exemplos de corpo já configurados.

⬇ Baixar alethor_api__V06.postman_collection.json

Login

Autentica o usuário e devolve o token de acesso. É o primeiro passo de qualquer integração.

Corpo (form-data)

Guarde o token retornado na variável {{token}}.

Me

Retorna os dados do usuário autenticado. Útil para confirmar que o token é válido e a qual empresa ele pertence.

Logout

Invalida o token atual. Após o logout, é necessário fazer login novamente para obter um novo token.

Enviar documento

Envia um arquivo para processamento. A API separa páginas, extrai os campos e valida. O resultado é consultado depois pelo endpoint de resultado, ou entregue por webhook quando finaliza.

Corpo (form-data)

A resposta traz o identificador do documento (UUID), usado para consultar o resultado.

Enviar com reconciliação

Além de extrair, a API confere os campos extraídos contra valores que você já conhece. Envie reconciliation_input com os campos esperados e a API informa se batem.

Corpo (form-data)

Exemplo de reconciliation_input

[
  { "field": "cnh.nome_completo", "value": "JOSE DA SILVA", "match_mode": "strict" },
  { "field": "cnh.cpf",           "value": "099.123.456-79", "match_mode": "strict" }
]

Resultado do documento

Consulta o resultado de um documento pelo seu UUID: os dados extraídos, o resultado da validação e, quando houver, o resultado da reconciliação.

Este é também o endereço que chega no payload do webhook, no campo result_url — é como seu sistema recupera o resultado completo após ser notificado.

Documento trancado pelo prazo de retenção

Vencido o prazo de retenção, o conteúdo do documento é trancado e deixa de ser servido. A resposta continua 200 com status deleted e extracted_data vazio, e traz o motivo:

{
  "document_id": "uuid",
  "document_type": "holerite",
  "status": "deleted",
  "extracted_data": {},
  "error_code": "documento_trancado_lgpd",
  "message": "O conteúdo deste documento foi trancado pelo prazo de retenção. Para contestação de extração, abra um chamado no Console, assunto 'Contestação de extração'."
}

Tipos e formatos suportados

Formatos de arquivo

Tipos de documento (document_type)

Acesso do titular (LGPD)

Atende ao direito de acesso do titular (art. 18 da LGPD). Como a Alethor é operadora, o acesso é exercido pela sua empresa (a controladora): localize os documentos de um titular dentro da janela de retenção, antes do trancamento.

Parâmetros (query)

Exemplo

GET {{endpoint_base}}lgpd/documents/holder?cpf=12345678900&name=João da Silva

Resposta

{
  "count": 1,
  "has_more": false,
  "documents": [
    {
      "document_id": "uuid",
      "file_original": "holerite_joao.pdf",
      "stage": "FINALIZADO",
      "created_at": "2026-07-29T...",
      "extracted_data_public": { /* campos servidos ao cliente */ }
    }
  ],
  "observacao": "Documentos com conteúdo trancado não aparecem nesta consulta; o pedido do titular sobre eles é atendido pelo encarregado (lgpd@inroot.com.br)."
}

Webhooks — ordem de configuração

Um webhook notifica seu sistema quando um documento é finalizado. A configuração segue uma ordem: você cria, o endpoint é verificado, e só então ele passa a receber. Siga os passos abaixo.

1. Criar o webhook — POST /webhooksO webhook nasce inativo. A resposta traz o secret em texto claro uma única vez — guarde-o.
2. Verificação de posse (automática)A API envia um desafio ao seu endpoint. Seu endpoint precisa devolver o mesmo desafio para provar que a URL é sua.
3. AtivaçãoSe o desafio for devolvido corretamente, o webhook é ativado. A partir daí ele recebe os documentos finalizados.
4. Reverificar quando necessário — POST /webhooks/{id}/verifySe a verificação falhou (endpoint fora do ar, URL errada), corrija e chame verify para tentar de novo — sem recadastrar.

Criar webhook

Registra um endpoint. Nasce inativo até a verificação de posse.

Corpo

{
  "url": "https://seu-sistema.com.br/webhooks/alethor",
  "events": ["document.finalized"],
  "payload_mode": "full"
}

Verificar webhook

Dispara (ou repete) a verificação de posse. A API envia um desafio à URL; seu endpoint deve devolvê-lo no corpo da resposta. Em caso de sucesso, o webhook é ativado — e os demais webhooks ativos da empresa são desativados. O desafio precisa ser respondido na própria URL cadastrada: a API não segue redirecionamentos, e destino que aponta para endereço privado ou que não resolve não recebe o desafio.

Seu endpoint deve responder ao desafio

// a API envia:  { "type": "verification", "challenge": "aB3xK9..." }
// seu endpoint devolve o mesmo challenge:
{ "challenge": "aB3xK9..." }

Listar webhooks

Retorna todos os webhooks da sua empresa, ativos e inativos.

Detalhar webhook

Mostra a configuração e o estado de um webhook: se está ativo, quando foi verificado, últimos sucessos e falhas. O secret nunca é retornado aqui.

Atualizar webhook

Altera events, payload_mode ou is_active. Reativar um webhook (is_active: true) desativa o que estiver ativo na empresa. Só webhook verificado pode ser ativado: sem verificação a resposta é 409 e nada muda — chame verify antes.

{
  "events": ["document.finalized"],
  "payload_mode": "reference",
  "is_active": true
}

Remover webhook

Remove o webhook. O histórico de auditoria da remoção é preservado.

Testar webhook

Envia um payload de exemplo (com dados fictícios) ao seu endpoint. Serve para validar a integração sem esperar um documento real. Não gera registro de entrega. A resposta traz o status e o corpo que o seu endpoint devolveu, e redirecionamentos não são seguidos. Destino que aponta para endereço privado, ou cujo host não resolve, responde 422 sem que nada seja enviado.

Rotacionar segredo

Gera um novo secret de assinatura e invalida o anterior. O novo valor é retornado em texto claro uma única vez. Use quando perder o segredo ou suspeitar de exposição.

Auditoria

Histórico de todas as mudanças de configuração — criação, alteração, ativação, desativação, rotação de segredo e remoção. O segredo nunca aparece em texto claro nos registros. O histórico da empresa inclui webhooks já removidos.

Listar entregas

Lista as tentativas de entrega de um webhook. Cada documento finalizado gera uma entrega. Use os filtros para investigar falhas.

Filtros (query)

Resposta do seu endpoint

response_body traz o que o seu endpoint respondeu. Quando o conteúdo do documento é trancado ou apagado pela política de retenção, essa resposta deixa de ser guardada: response_body vem null e conteudo_indisponivel diz o motivo.

{
  "id": "9d3c…",
  "status": "success",
  "response_status": 200,
  "response_body": null,
  "conteudo_indisponivel": "trancado",
  …
}

Reenviar uma entrega — Redeliver

Reenvia uma entrega específica, identificada pelo seu delivery_id. É cirúrgico: uma entrega, uma vez.

Use quando você viu, na listagem, exatamente qual entrega falhou e quer reenviá-la após corrigir seu endpoint.

Janela de reenvio

O reenvio só é possível enquanto o conteúdo do documento não estiver trancado. Pela política de retenção, o conteúdo é trancado:

Entrega não encontrada

Um delivery_id que não existe responde 404 com error_code delivery_not_found e o bloco retention:

{
  "message": "Delivery not found. It may never have existed, or it may have been removed by the retention policy.",
  "error_code": "delivery_not_found",
  "retention": {
    "note": "Delivery records are kept. A delivery can be redelivered only while its document's content is not locked under the data retention policy. …",
    "redelivery_window_days": {
      "after_first_successful_delivery": 3,
      "completed_without_successful_delivery": 7,
      "permanent_error": 7,
      "never_processed": 7
    },
    "not_retained_before": null,
    "oldest_surviving_delivery_at": "2026-10-11T12:00:00+00:00"
  },
  "data": null
}

Reenviar em lote — Replay

Reenvia todas as entregas que casam com um filtro. Você não aponta IDs — descreve um critério (data + status) e a API reenvia o lote.

Corpo

{
  "date": "2026-07-26",
  "status": "exhausted"
}

Redeliver × Replay — qual usar

Os dois reenviam entregas. A diferença é escala e seletor.