Pular para o conteúdo principal

Introducao API Fiscal-Documents

A API Fiscal Documents oferece uma interface unificada e padronizada para consulta de documentos fiscais recebidos por sellers em marketplaces. Com ela, você pode acessar as notas fiscais eletrônicas (NF-e), Conhecimentos de Transporte Eletrônicos (CT-e) e seus respectivos eventos (como cancelamento, inutilização, etc), de forma simples e centralizada.

Esta API foi desenvolvida para facilitar a integração de sistemas que precisam consultar documentos fiscais de forma eficiente, com suporte a filtros, paginação e acesso ao conteúdo completo dos documentos (XML).

Principais funcionalidades​

  • Consulta de documentos fiscais com diversos filtros (data, marketplace, pedido, tipo de documento, etc).

  • Acesso ao histórico de eventos de um documento (ex: autorizado, cancelado).

  • Visualização de relacionamentos entre documentos (ex: notas referenciadas por CT-e).

  • Download do XML completo de um evento específico.

  • Estrutura pensada para facilitar integrações B2B e automações fiscais.

Fluxo recomendado​

imagem (7).png

1. Habilite o recebimento de notificações​

No painel de parâmetros do ANYMARKET, habilite o tópico de Documentos fiscais de uma callback para receber notificações push sempre que um novo documento for criado ou editado.

Isso garante que seu sistema seja atualizado em tempo real, sem depender de varreduras frequentes.

A estrutura da notificação incluirá os seguintes campos em metadata:

{
  "type": "FISCAL_DOCUMENTS",
  "event": "UPDATE",
  "content": {
    "id": "1",
    "oi": "47.",
    "metadata": {
      "documentTypeValue": "symbolic_inbound_return",
      "marketplace": "MERCADO_LIVRE",
      "type": "NFE"
    }
  }
}

2. Ao receber a notificação, consulte o documento completo​

Com o id do documento notificado, utilize o endpoint: GET /v2/fiscalDocuments/{id}

Esse endpoint retorna todos os dados consolidados do documento, incluindo:

  • Chave de acesso (documentKey)

  • Datas de criação e atualização

  • Informações fiscais (tipo, subtipo, CFOP, metadados, etc.)

  • Histórico de eventos com status e links

  • Documentos relacionados (ex: notas referenciadas)

3. Baixe o XML do documento​

Para acessar o conteúdo completo do documento fiscal em formato XML, utilize:

GET /v2/fiscalDocuments/download/{document_item_id}

O endpoint acima, além do {document_item_id} será retornado no objeto path, dentro do array documents, retornado na consulta do documento.

4. Como fallback, utilize a listagem paginada​

Em casos onde o push não esteja habilitado, ou para sincronismos periódicos, utilize o endpoint:

GET /v2/fiscalDocuments

Com suporte a filtros por:

  • orderId
  • marketplace
  • createdAtFrom, createdAtTo
  • lastUpdateFrom, lastUpdateTo
  • documentTypeValue

Esse endpoint retorna os documentos paginados, além de informações básicas e o histórico de eventos.

Esse fluxo garante:

✅ Rapidez com notificações

✅ Confiabilidade com consulta direta por ID

✅ Eficiência no tráfego de dados (evita requisições desnecessárias)

✅ Simplicidade na conciliação e rastreamento fiscal