ComprovaFácil

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.

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 as credenciais e a chave de API somente nos cabeçalhos indicados abaixo — o endpoint não espera payload JSON.

Headers (exemplo)
Email: user@mail.com.br
Password: xHXaV....
X-Api-Key: d4...

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

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

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.

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).
  • key
    Chave da nota fiscal / entrega.
  • 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>

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)

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.

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.

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.

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.
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.

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
GET /v1/deliveries/NFE-KEY-001

Authorization: Bearer <token>

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.

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.

Resposta 200
{
  "deleted": true
}

Exemplos (cURL)

Obter sessão
curl -s -X POST 'https://api.integracao.comprovafacil.com.br/v1/auth' \
  -H 'Email: user@mail.com.br' \
  -H 'Password: xHXaV....' \
  -H 'X-Api-Key: d4...'
Listar entregas (query mínima)
curl -s -G 'https://api.integracao.comprovafacil.com.br/v1/deliveries' \
  -H 'Authorization: Bearer <token>' \
  --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"
    }
  ]
}