Skip to main content

​
Visão Geral

Consulta notas fiscais de entrada que já foram recebidas e confirmadas pelo AG, retornando informações de cabeçalho (NF, datas, AG, emitente, destinatário e totais) ainda não consumidas por um sistema de integração específico. Esse endpoint é normalmente utilizado por sistemas externos (ERP, TMS, WMS, BI, etc.) para identificar quais notas fiscais já deram entrada física no armazém e estão disponíveis para processamento, garantindo controle de consumo, idempotência e rastreabilidade por integração. Método HTTP: POST /v1/consultar_recebimento

​
Headers

NomeValor
Content-Typeapplication/json
AuthorizationBearer <token>

​
Campos

NomeTipoDescrição
destinostringIdentificador lógico do sistema consumidor da integração.
Usado para controle de idempotência (garante que a mesma NF não seja processada duas vezes pelo mesmo sistema).
emitente_documentostringDocumento (CNPJ/CPF) do Emitente a ser filtrado
limitintQuantidade máxima de notas fiscais retornadas na consulta.

​
Exemplo

{
  "destino": "ERP",
  "emitente_documento": "11.222.333/0001-44",
  "limit": 50
}

{
  "status": 200,
  "message": "Processado",
  "destino": "ERP",
  "resultado": [
    {
      "ok": true,
      "status": 200,
      "message": "NF recebida",
      "data": {
        "empresa_id": "0c3e1d9c-7a2b-4f4b-9b8c-91d7c7d1a111",
        "ag_id": "b47043ef-8501-4dfd-b73c-1ab687f8ab6d",
        "ag_nome": "AG LOGISTICA SUL",
        "ag_documento": "12.345.678/0001-99",
        "nf_entrada": "NF123456",
        "data_emissao": "2026-02-01",
        "data_recebimento_ag": "2026-02-03",
        "lead_time_dias": 2,
        "tipo_operacao": "AG-CLIENTE",
        "emitente_id": "1b2c3d4e-aaaa-bbbb-cccc-123456789000",
        "emitente_nome": "INDUSTRIA ABC LTDA",
        "emitente_documento": "11.222.333/0001-44",
        "destinatario_id": "b47043ef-8501-4dfd-b73c-1ab687f8ab6d",
        "destinatario_nome": "AG LOGISTICA SUL",
        "destinatario_documento": "12.345.678/0001-99",
        "qtd_total": 350,
        "valor_total": 18500.75
      }
    }
  ]
}

​
Erros comuns

CódigoMensagemCausa Provável
403Usuário sem acesso ao a empresaSem vínculo com empresa
404Nenhuma movimentação de entrada encontradaNF já confirmada
500Erro internoViolação de política RLS, chave duplicada etc
  • A consulta retorna apenas NFs que possuem movimentações com tipo_movimentacao = 'ENTRADA' e data_entrada preenchida (ou seja, recebimento confirmado pelo AG).
  • O endpoint filtra automaticamente as NFs que já tenham registro de consumo na tabela para o mesmo destino, garantindo que cada integração processe apenas o que ainda está pendente.
  • Se ag_documento não for informado, o sistema retorna notas recebidas de qualquer AG (respeitando a empresa do usuário autenticado).