ComprovaFácil
Atualizado em 27/03/2026

Bem-vindo à documentação da API Comprova Fácil!

A API Comprova Fácil foi desenvolvida para oferecer uma integração simples, eficiente e confiável. Nossa API permite consultas e cadastro de dados orientada às necessidades do cliente. Apos o login, todas as rotas protegidas exigem o header Authorization (Bearer JWT) e o header x-api-key (a mesma chave usada na autenticacao).

Consultas Personalizadas

Filtre entregas do jeito que o seu negócio precisa: por período, status, documento, participantes e muito mais. Você enxerga só o que importa, com respostas objetivas para tomar decisão na hora.

Manipulação de dados

Cadastre novas entregas, acompanhe o ciclo completo e remova registros quando a regra do seu processo permitir — tudo em um fluxo pensado para integrar o Comprova Fácil ao seu dia a dia operacional.

Padrões de qualidade

Comunicação clara, respostas previsíveis e desempenho consistente: construímos a integração para aguentar volume real de uso, com a segurança que documentos fiscais e comprovações exigem.

Atualizações e Estabilidade

Investimos continuamente em melhorias e na estabilidade do serviço. Quando algo evoluir no produto, priorizamos transições suaves para que sua operação siga tranquila.

Ambientes

Server

Ambiente de producao

Autenticação

POST/v1/auth

Autentica um usuário integrador ativo e retorna um JWT de sessão com expiração de 2 horas. Envie email e password no corpo JSON e a chave de API no cabeçalho x-api-key (conforme o exemplo abaixo).

Exemplo de requisição
POST /v1/auth
Content-Type: application/json

x-api-key: d4...
Corpo (JSON)
{
  "email": "user@mail.com.br",
  "password": "xHXaV...."
}

Resposta 200: token JWT, tipo Bearer e tempo de expiração (ex.: 2h).

Resposta
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": "2h"
}

Rotas protegidas

Vale para todas as rotas exceto POST /v1/auth. Cada requisição deve incluir os dois cabeçalhos abaixo; se faltar Authorization ou x-api-key, a API recusa o acesso.

  • Authorization
    Envie o JWT retornado no login no formato Bearer <token>.
  • x-api-key
    A mesma chave de API usada no cabeçalho x-api-key da autenticação (POST /v1/auth).
Headers em rotas protegidas (exemplo)
Authorization: Bearer <token>
x-api-key: d4...

Listar entregas

GET/v1/deliveries

Lista entregas da empresa identificada pelo CNPJ, com filtros opcionais e paginação por cursor. A API resolve a empresa pelo parâmetro cnpj e confirma se o usuário autenticado (JWT) tem permissão de acesso antes de consultar. Em toda requisição envie Authorization: Bearer e x-api-key (a mesma chave do login).

Parâmetros obrigatórios

  • cnpj
    CNPJ da empresa dona das entregas.
  • from / to
    Intervalo de datas no formato dd-mm-yyyy (UTC). Ambos são inclusivos e filtram o campo definido em dateField.

Qual data entra no intervalo

O parâmetro dateField define qual campo de data recebe os limites from e to.

  • issueDate
    Padrão quando omitido — data de emissão do documento/nota.
  • receivementDate
    Data da comprovação.
  • readingDate
    Data de leitura do código de barras.

Paginação

  • pageSize
    Quantidade de itens por página; inteiro entre 1 e 200 (padrão 20).
  • cursor
    Token devolvido em nextCursor na resposta anterior; omita na primeira página.

Ordenação

  • sort
    ASC ou DEC conforme updatedAt (padrão DEC).

Filtros de status da entrega

Parâmetro type.

  • Valores: ALL, OPEN, UNUSABLE, ONLY_OPEN, ONLY_TRANSFER, PROVED. Padrão: ALL.

Filtro de tipo de recebimento

Parâmetro status.

  • Valores: ALL, PARTIAL, DEVOLUTION.
  • Regra: se status for informado, type não pode ser OPEN, ONLY_OPEN, ONLY_TRANSFER nem UNUSABLE.

Filtros de conteúdo e participantes

  • document
    Busca pelo número do documento (texto ou intervalo numérico, conforme regras da API).
  • receiver
    Filtro textual relacionado ao recebedor.
  • emitter
    Filtro textual relacionado ao emitente.
  • person
    Filtro textual relacionado à pessoa envolvida.
  • carrier
    Filtro textual relacionado à transportadora.
  • extraField
    Filtro pelo campo extra associado à entrega.
  • docNumberAiCheck
    DOCUMENT_NUMBER_VERIFIED ou DOCUMENT_NUMBER_NOT_VERIFIED — verificação do número do documento na imagem do comprovante.

Padrões quando parâmetros opcionais são omitidos

type=ALL·sort=DEC·pageSize=20·dateField=issueDate

Exemplo de requisição
GET /v1/deliveries?cnpj=13872724000177&from=01-01-2026&to=31-01-2026&pageSize=20

Authorization: Bearer <token>
x-api-key: d4...

O que a API pode retornar?

data

Um array de objetos com informações sobre cada entrega. Cada item pode conter:

id

Identificador único da entrega. (string)

document

Série da NF-e concatenada com o número do documento. (string)

key

Chave da NF-e. (string)

issueDate

Data/hora de emissão da NF-e (ISO 8601). (string, date-time)

status

Estado da entrega: OPEN, TRANSFER, PROVED ou UNUSABLE. (string)

owner

Identificador do proprietário/contexto da entrega. (string)

createdAt

Criação do registro. (string, date-time)

updatedAt

Última atualização (usada na ordenação). (string, date-time)

unusable

Indica entrega marcada como inutilizável. (boolean)

deliveryPerson

Lista de objetos sobre quem carregou a entrega e quando. Pode conter:

  • documentReadingDate

    Quando a entrega foi carregada / lida. (string, date-time)

  • userName

    Nome do responsável pelo carregamento. (string)

  • phoneModel

    Modelo do aparelho utilizado. (string)

emitter

Emitente da NF-e. Pode conter:

  • state

    UF. (string)

  • name

    Razão social ou nome. (string)

  • document

    Documento da empresa emitente. (string)

  • city

    Cidade. (string)

carrier

Transportadora (quando houver). Mesmos campos que o emitente:

  • state

    UF. (string)

  • name

    Nome da transportadora. (string)

  • document

    Documento. (string)

  • city

    Cidade. (string)

receiver

Destinatário da entrega. Pode conter:

  • state

    UF. (string)

  • name

    Nome de quem recebe. (string)

  • document

    Documento do recebedor. (string)

  • city

    Cidade. (string)

receivementInfos

Dados da comprovação, quando existir. Pode conter:

  • type

    ALL, PARTIAL ou DEVOLUTION. (string)

  • date

    Data/hora da confirmação. (string, date-time)

  • images

    URLs das fotos tiradas na confirmação. (array of strings)

  • note

    Anotação do motorista. (string)

  • geolocation

    Coordenadas no momento da confirmação:

    • latitude

      Latitude. (number)

    • longitude

      Longitude. (number)

  • recipient

    Quem recebeu no comprovante:

    • name

      Nome. (string)

    • document

      Documento. (string)

  • receiptInspection

    Checagens da imagem do comprovante (quando disponível):

    • isValidNumDoc

      Número do documento conferido. (boolean)

    • includesSignature

      Presença de assinatura. (boolean)

    • includesDate

      Presença de data. (boolean)

    • otifDate

      Campo data OTIF. (string, date-time)

receivementInfosRemoved

Registro do último comprovante removido ou substituído (quando houver). Estrutura espelha a comprovação vigente, com metadados da remoção. Pode conter:

  • type

    ALL, PARTIAL ou DEVOLUTION — escopo do comprovante removido. (string)

  • date

    Data/hora associada ao comprovante removido. (string, date-time)

  • images

    URLs das imagens do comprovante removido. (array of strings)

  • notes

    Anotações do comprovante removido, quando existirem. (string | null)

  • geolocation

    Coordenadas no momento da captura removida:

    • latitude

      Latitude. (number)

    • longitude

      Longitude. (number)

  • deliveryPersonId

    Identificador do registro em deliveryPerson vinculado à remoção. (string)

  • username

    Usuário que efetuou a remoção. (string)

  • reason

    Motivo informado para a remoção (ex.: foto ilegível). (string)

  • removedAt

    Data/hora em que o comprovante foi removido. (string, date-time)

  • recipient

    Destinatário no comprovante removido, quando aplicável. (object | null)

  • audit

    Dados de auditoria da remoção, quando existirem. (object | null)

  • receiptInspection

    Checagens da imagem do comprovante removido (quando disponível):

    • isValidNumDoc

      Número do documento conferido. (boolean)

    • includesSignature

      Presença de assinatura. (boolean)

    • includesDate

      Presença de data. (boolean)

    • otifDate

      Campo data OTIF. (string, date-time)

nextCursor

Token para solicitar a próxima página; ausente ou nulo quando não há mais resultados. (string | null)

Exemplo JSON (resumo)
{
  "data": [
    {
      "id": "67d1a3cb0e0f0f0f0f0f0f0f",
      "document": "NF-0001",
      "status": "OPEN",
      "key": "25260241277706000344550020000136661999897496",
      "owner": "67d1a3cb0e0f0f0f0f0f0f99",
      "issueDate": "2026-02-23T13:45:51.000Z",
      "createdAt": "2026-02-23T16:45:58.671Z",
      "updatedAt": "2026-02-23T16:45:58.671Z",
      "emitter": {
        "document": "41277706000344",
        "name": "CAMPINA GRANDE TRANSPORTES LTDA",
        "city": "CAMPINA GRANDE PB",
        "state": "PB"
      },
      "receiver": {
        "document": "00255303000100",
        "name": "FALCAO DE CARROS LTDA",
        "city": "SANTA RITA DO SAPUCAI PB",
        "state": "PB"
      }
    }
  ],
  "nextCursor": "next-cursor-token"
}

Cadastrar entrega

POST/v1/deliveries

A API valida e sanitiza o corpo da requisição, resolve a empresa pelo cnpj, confere se o usuário autenticado tem acesso e impede chaves duplicadas (key). Antes de gravar, o campo receiver.document é criptografado. Inclua nos cabeçalhos Authorization: Bearer e x-api-key (mesma chave do POST /v1/auth).

Campos obrigatórios (raiz do JSON)

  • cnpj
    CNPJ da empresa à qual a entrega pertence (conta integradora / tomador).
  • document
    Número do documento fiscal tal como na NF-e/CT-e (ex.: número da nota, combinação série/número ou identificador operacional que sua operação usa para a entrega).
  • key
    Chave de acesso da NF-e ou CT-e (referência única da nota; em NF-e, tipicamente 44 caracteres).
  • issueDate
    Data/hora de emissão do documento, em ISO 8601 (ex.: 2026-02-20T10:00:00.000Z).

Emitente na nota

Objeto emitter — quem emite a NF-e/CT-e. Mesma estrutura de pessoa: documento, nome, cidade e UF.

  • document
    CNPJ ou CPF do emitente da nota fiscal. Apenas caracteres alfanuméricos são considerados na sanitização.
  • name
    Razão social ou nome do emitente; caracteres especiais podem ser normalizados no processamento.
  • city
    Município do emitente (até 100 caracteres).
  • state
    UF do emitente — exatamente 2 caracteres (ex.: PR).

Destinatário / recebedor

Objeto receiver — destinatário da mercadoria na nota. O documento é persistido de forma criptografada.

  • document
    Documento do recebedor (CNPJ/CPF conforme a operação).
  • name
    Nome ou razão social do recebedor.
  • city
    Município do recebedor.
  • state
    UF do recebedor (2 caracteres).

Transportadora

Objeto carrier (opcional). Transportadora envolvida na entrega. Todos os subcampos são opcionais; quando enviados, seguem o mesmo significado que em emitente/recebedor.

  • document
    Documento da transportadora.
  • name
    Nome da transportadora.
  • city
    Município da transportadora.
  • state
    UF da transportadora (2 caracteres).

Campo extra

Parâmetro extraField (opcional).

Texto livre curto (máx. 10 caracteres após sanitização) para referência interna — ex.: código de pedido ou ID legado.

Resumo

Obrigatórios: cnpj, document, key, issueDate, objetos completos emitter e receiver. Opcionais: carrier e extraField.

Exemplo de requisição
POST /v1/deliveries
Content-Type: application/json

Authorization: Bearer <token>
x-api-key: d4...
Corpo (JSON)
{
  "cnpj": "13872724000177",
  "document": "NF-0001",
  "key": "NFE-KEY-NEW-001",
  "issueDate": "2026-02-20T10:00:00.000Z",
  "emitter": {
    "document": "12345678000199",
    "name": "Emitente Teste",
    "city": "Londrina",
    "state": "PR"
  },
  "receiver": {
    "document": "00255303000100",
    "name": "FALCAO DE CARROS LTDA",
    "city": "SANTA RITA DO SAPUCAI PB",
    "state": "PB"
  },
  "carrier": {
    "document": "11223344000155",
    "name": "Transportadora Sul",
    "city": "Curitiba",
    "state": "SC"
  },
  "extraField": "pedido1"
}
Resposta 200
{
  "deliveryId": "delivery-created-id"
}

Grupo de entregas e QR Code

POST/v1/deliveries/qrcode

A operação exige que todas as chaves informadas existam, pertençam à empresa resolvida pelo cnpj e ainda estejam abertas. Se alguma entrega já tiver recebimentos, a requisição falha. Quando o mesmo conjunto de chaves já tiver um grupo criado, o groupId existente é reutilizado e os dados do QR Code correspondem a esse grupo. Envie Authorization: Bearer e x-api-key em toda chamada.

Corpo da requisição

JSON com os campos abaixo.

  • cnpj
    CNPJ da empresa à qual as entregas do grupo pertencem (mesma regra das outras rotas de entregas).
  • deliveriesKeys
    Lista de chaves das NF-e/entregas que entram no grupo (mínimo 1 item). Cada string é a key cadastrada na API.

Resposta 200

Corpo JSON em caso de sucesso.

  • groupId
    Identificador único do grupo (novo ou já existente para o mesmo conjunto de chaves).
  • qrCodeData
    Conteúdo do QR (ex.: deep link comprovafacil://group?groupId=...) para uso no app.
  • qrCodeDataUrl
    URL assinada para obter a imagem ou recurso do QR Code pronto para exibição/download.
Exemplo de requisição
POST /v1/deliveries/qrcode
Content-Type: application/json

Authorization: Bearer <token>
x-api-key: d4...
Corpo (JSON)
{
  "cnpj": "13872724000177",
  "deliveriesKeys": ["NFE-KEY-000001"]
}
Resposta 200
{
  "groupId": "group-created-id",
  "qrCodeData": "comprovafacil://group?groupId=group-created-id",
  "qrCodeDataUrl": "https://signed-url.example.com/group-created-id"
}

Buscar entrega por chave

GET/v1/deliveries/{key}

Carrega uma entrega pela key informada na URL (path parameter). A API valida se o usuário autenticado tem acesso à empresa dona da entrega e confirma se a empresa vinculada ao campo owner no registro ainda existe antes de devolver o payload. Use Authorization: Bearer e x-api-key nos cabeçalhos.

Parâmetro de rota

Identificador na URL do endpoint.

  • key
    Chave única da entrega (a mesma key usada no cadastro / listagem — ex.: chave da NF-e).

Resposta 200

Objeto JSON com a propriedade data contendo o modelo Delivery: id, document, status, emitter, receiver, deliveryPerson, receivementInfos, entre outros campos conforme o contrato da API.

Exemplo de requisição
GET /v1/deliveries/NFE-KEY-001

Authorization: Bearer <token>
x-api-key: d4...

Remover entrega

DELETE/v1/deliveries/{key}

Permite remoção apenas quando a entrega existir, não possuir recebimentos e o usuário autenticado tiver permissão sobre a empresa dona da entrega. A requisição exige Authorization: Bearer e x-api-key.

Parâmetro de rota

Identificador na URL do endpoint.

  • key
    Chave única da entrega (a mesma key usada no cadastro / listagem — ex.: chave da NF-e).

Resposta 200

Corpo JSON com deleted: true quando a exclusão for concluída com sucesso.

Exemplo de requisição
DELETE /v1/deliveries/NFE-KEY-001

Authorization: Bearer <token>
x-api-key: d4...
Resposta 200
{
  "deleted": true
}

Exemplos (cURL)

Obter sessão
curl -s -X POST 'https://api.integracao.comprovafacil.com.br/v1/auth' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: d4...' \
  -d '{"email":"user@mail.com.br","password":"xHXaV...."}'
Listar entregas (query mínima)
curl -s -G 'https://api.integracao.comprovafacil.com.br/v1/deliveries' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-api-key: d4...' \
  --data-urlencode 'cnpj=13872724000177' \
  --data-urlencode 'from=01-01-2026' \
  --data-urlencode 'to=31-01-2026'

Respostas de erro

Quando uma requisição não pode ser concluída, a API responde com mensagens objetivas para você identificar o motivo e corrigir o fluxo sem perder tempo.

Erro padrão (ex.: 401)
{
  "message": "Invalid access token",
  "name": "AuthorizationError"
}
Erro de validação (ex.: 400)
{
  "message": "ValidationError",
  "field": [
    {
      "path": "emitter.state",
      "message": "Estado da pessoa invalido"
    }
  ]
}

Como a API expõe erros

  • ZodError → HTTP 400, message: ValidationError e lista de campos inválidos.
  • ApplicationError → usa o statusCode, name e message definidos no erro.
  • InternalServerError — quando a API responde com HTTP 500 e name: InternalServerError, pode indicar falha do nosso lado. Recomendamos conferir quais documentos não foram enviados ou buscados com sucesso e executar uma nova varredura no seu fluxo.
  • AuthorizationError — token inválido/expirado/malformado → 401 AuthorizationError (Invalid access token). Várias causas internas de auth aparecem hoje como essa mesma 401.
  • TooManyRequests — limite global: 50 requisições/minuto por IP → HTTP 429 quando excedido.

Validação de entrada (400)

Validações retornam message: ValidationError (corpo com detalhes por campo quando aplicável).

POST/v1/auth

  • Email e obrigatorio — campo email no corpo JSON ausente ou vazio.
  • Email invalido — formato de e-mail inválido.
  • Senha e obrigatoria — campo password no corpo JSON ausente ou vazio.

GET/v1/deliveries

  • CNPJ da empresa e obrigatorio — query cnpj ausente ou vazia.
  • Formato de data invalido. Informe uma data valida no formato dd-mm-yyyy. Exemplo: 05-12-2024. — from ou to ausentes, vazios ou fora do formato dd-MM-yyyy.
  • `from` deve ser menor ou igual a `to` — intervalo de datas invertido.
  • Enums Zod — dateField, type, status, sort ou docNumberAiCheck com valor não permitido.
  • `type` nao pode ser um dos seguintes valores: OPEN, ONLY_OPEN, ONLY_TRANSFER, UNUSABLE quando `status` for preenchido — combinação inválida entre type e status.
  • pageSize — não numérico, não inteiro, menor que 1 ou maior que 200.
  • Cursor invalido — base64url inválido ou payload interno inconsistente.

POST/v1/deliveries

  • CNPJ da empresa e obrigatorio
  • Documento e obrigatorio
  • Chave da nota e obrigatoria
  • Documento da pessoa e obrigatorio
  • Nome da pessoa e obrigatorio
  • Cidade da pessoa e obrigatoria
  • Cidade da pessoa invalida
  • Estado da pessoa e obrigatorio
  • Estado da pessoa invalido
  • Campo invalido — carrier opcional sanitizado ficou vazio após sanitização.
  • Cidade do transportador invalida
  • Estado do transportador invalido
  • extraField invalido — vazio após sanitização.
  • extraField deve ter no maximo 10 caracteres
  • issueDate — coerção para data inválida (Zod).

POST/v1/deliveries/qrcode

  • CNPJ da empresa e obrigatorio
  • deliveriesKeys e obrigatorio — lista ausente ou vazia.
  • Key de entrega invalida — algum item de deliveriesKeys vazio.

GET/v1/deliveries/:key

  • Chave da entrega e obrigatoria — parâmetro key ausente ou vazio.

DELETE/v1/deliveries/:key

  • Chave da entrega e obrigatoria — parâmetro key ausente ou vazio.

Autenticação e autorização

Nas rotas protegidas, exemplos típicos de corpo (JSON):

  • 400 — MissingParamError — AccessToken Not Provided — header Authorization não enviado.
  • 401 — AuthorizationError — Invalid access token — falha na validação do Bearer ou contexto do usuário.

O documento técnico completo lista causas internas que hoje colapsam nessa 401 (JWT, usuário inativo, perfil, empresa, produtos, etc.).

POST/v1/auth (respostas do próprio login)

  • 401 UnauthorizedError — Invalid credentials — usuário/senha incorretos ou usuário inativo na autenticação.
  • 403 ForbiddenError — Usuario nao possui acesso a esta API — perfil não é integrator.
  • 401 UnauthorizedError — Usuario nao possui empresa — sem empresa principal.
  • 401 UnauthorizedError — Usuario nao possui produtos — nenhum produto ativo.
  • 401 UnauthorizedError — Usuario nao possui produto necessario — falta produto obrigatório da integração.
  • 400 BadRequestError — Empresa do usuario nao encontrada — empresa principal não encontrada ao montar contexto.
  • 403 ForbiddenError — Nenhuma empresa ativa com acesso ao produto foi encontrada para o usuario — empresa principal desabilitada.
  • 403 ForbiddenError — Empresa nao possui o produto necessario — empresa sem o produto requerido.

Regras de negócio (4xx)

GET/v1/deliveries

  • 404 NotFoundError — Empresa nao encontrada — cnpj sem empresa.
  • 403 ForbiddenError — Usuario nao possui acesso a empresa informada — usuário não admin sem acesso à empresa do cnpj.

GET/v1/deliveries/:key

  • 404 NotFoundError — Entrega nao encontrada
  • 403 ForbiddenError — Usuario nao possui acesso a empresa informada — sem acesso ao owner da entrega.
  • 404 NotFoundError — Empresa nao encontrada — entrega existe, mas empresa dona (owner) não encontrada.

POST/v1/deliveries

  • 404 NotFoundError — Empresa nao encontrada
  • 403 ForbiddenError — Usuario nao possui acesso a empresa informada
  • 409 DeliveryAlreadyExistError — Entrega ja cadastrada — key duplicada.

POST/v1/deliveries/qrcode

  • 404 NotFoundError — Empresa nao encontrada
  • 403 ForbiddenError — Usuario nao possui acesso a empresa informada
  • 404 DeliveryNotExistError — Entrega nao encontrada — chave inexistente, de outra empresa ou não aberta/usável.
  • 409 DeliveryAlreadyHasReceivementsError — Entrega ja possui recebimentos e nao pode ser excluida — alguma entrega do grupo já está PROVED (mensagem reutilizada no fluxo de grupo).

DELETE/v1/deliveries/:key

  • 404 DeliveryNotExistError — Entrega nao encontrada — não existe ou inconsistência na exclusão.
  • 409 DeliveryAlreadyHasReceivementsError — Entrega ja possui recebimentos e nao pode ser excluida
  • 403 UserDoesntHasPermissionToDeleteDeliveryError — Usuario nao possui permissao para remover esta entrega

Resumo por status e rota

POST /v1/auth — 400 validação; 401/403 credenciais, perfil e empresa/produto; 500 operacional.

GET /v1/deliveries — 400 token ausente/validação/cursor; 401; 403; 404; 429; 500.

GET /v1/deliveries/:key — 400; 401; 403; 404; 500.

POST /v1/deliveries — 400; 401; 403; 404; 409; 500.

POST /v1/deliveries/qrcode — 400; 401; 403; 404; 409; 500.

DELETE /v1/deliveries/:key — 400; 401; 403; 404; 409; 500.