Pular para o conteúdo principal

Documentos Fiscais

Na operação logística do Magalu (seja no modelo de Fulfillment ou coletas), o trânsito e a venda de mercadorias geram uma série de obrigações tributárias e documentos legais, como a Nota Fiscal Eletrônica (NF-e) e o Conhecimento de Transporte Eletrônico (CT-e).

Para que a sua empresa possa realizar a contabilidade, o fechamento do mês e a conciliação financeira de forma automatizada, esta API atua como a sua porta de entrada. Ela substitui o trabalho manual de baixar nota por nota em um portal, permitindo a extração de documentos unitários ou em grandes lotes de forma totalmente integrada ao seu ERP.

Abaixo, detalhamos a jornada de uso para as consultas unitárias e massivas:

1. Consulta e Extração Unitária​

Esta jornada é ideal para o dia a dia do seu atendimento ao cliente (SAC) ou para verificações pontuais de uma venda específica, onde você precisa do documento imediatamente.

Download Unitário por Chave​

GET/logistics/v1/fiscal-documents/:access_key

Finalidade: Se o seu sistema já possui a chave de acesso de 44 dígitos da nota, esta rota permite o download direto do documento.

O que ela retorna: O sistema processa a requisição e devolve o XML estruturado do documento fiscal solicitado.

2. Extração Massiva (Download em Lote)​

Esta é a funcionalidade mais valiosa para as equipes financeiras e fiscais. Ideal para o fechamento contábil do mês, permitindo baixar muitas de notas de uma só vez. Por lidar com um volume imenso de dados, esta jornada é assíncrona.

Solicitação de Lote​

POST/logistics/v1/fiscal-documents/batch-download

Finalidade: É o seu pedido formal de geração do pacote de notas. Você informa os filtros desejados e um parâmetro indicando se deseja exportar CT-es ou NF-es.

Como funciona: O Magalu recebe o pedido, gera uma tarefa de processamento em background e responde imediatamente com um taskId e o status PENDING. As NF-es, por exemplo, serão organizadas e compactadas em pastas estruturadas.

2.1 Acompanhamento e Notificação (Lote)​

Após solicitar o lote (passo 2), o seu sistema precisa saber quando o arquivo final (geralmente um arquivo ZIP) estará pronto para download. Você tem duas formas de fazer isso: Consulta Ativa ou Webhook.

Consulta Ativa / Polling​

GET/logistics/v1/fiscal-documents/batch-export/:task_id

  • Finalidade: Permite consultar manualmente o andamento da sua solicitação. Informando o taskId recebido anteriormente, a API retornará se o processamento está PROCESSING, FAILED, ou COMPLETED.

  • Download Final: Quando o status mudar para COMPLETED, a resposta incluirá a métrica de quantos arquivos foram gerados com sucesso e a URL/Chave para você realizar o download do arquivo ZIP contendo todos os XMLs.

Notificações em Tempo Real (Webhooks)​

POST/logistics/v1/fiscal-documents/batch-export/status-callback

  • Finalidade: A melhor prática de integração. Em vez de você ficar fazendo requisições repetidas para a rota GET para verificar se o lote terminou, o Magalu avisa você.

  • Como funciona: Você configura um endpoint (URL) no seu sistema. Assim que a nossa infraestrutura terminar de empacotar as suas notas, ela disparará uma requisição enviando as informações da conclusão diretamente para a sua aplicação, informando que o link de download está disponível e eliminando o desperdício de recursos do seu servidor.

Escopos necessários​

Para a utilização das APIs os seguintes escopos poderão ser necessários:

ValorDescrição
open:logistic-fiscal-documents-seller:readPermite a consulta de documentos fiscais individuais.
open:logistic-fiscal-documents-seller:writePermite a solicitação e visualização do download de documentos fiscais em lote.

📄️ Solicitação de download em lote de documentos fiscais

Esta rota é utilizada para solicitar a extração em lote de múltiplos documentos fiscais (NF-e ou CT-e). Devido à natureza potencialmente pesada da operação, o processo é assíncrono; ao invés de devolver o arquivo imediatamente, a chamada retorna um taskId e uma mensagem de status PENDING. Este método é fundamental para sellers com grande volume de vendas, que precisam baixar grandes quantidades de XMLs de forma eficiente. O seller deve posteriormente consultar o status dessa tarefa utilizando o taskId para obter o link de download.

📄️ Buscar status da solicitação

Este endpoint permite que o seller consulte o status da sua solicitação de download em lote iniciada via batch-download. O seller deve usar o task_id fornecido na solicitação inicial para verificar se a extração em lote foi concluída (COMPLETED), se ainda está em processamento (PROCESSING), ou se alhou (FAILED). Quando o status for COMPLETED, a resposta irá conter a URL de download do arquivo compactado (ZIP), permitindo a recuperação do lote de documentos fiscais.