Documentação de Nota Fiscal (Pedidos)

Visão Geral

A nota fiscal é o documento que formaliza a venda de um pedido — ela registra informações como produtos, valores, impostos e dados do cliente.

Na API de pedidos, você pode trabalhar com a nota fiscal de duas formas principais:

1. Atualizar dados fiscais de pedidos Permite enviar ou corrigir informações da nota fiscal para um ou mais pedidos de uma vez (em lote). Essa operação usa o endpoint PUT /orders/invoice e requer permissão ORDER_WRITE.

2. Consultar a nota fiscal de um pedido Permite acessar o conteúdo da nota vinculada a um pedido específico, seja: - o XML da nota, ou - a URL para visualização

Essas rotas funcionam como um proxy, ou seja, você consegue acessar a nota sem precisar saber onde ela está armazenada internamente.

Essas operações estão conectadas ao cadastro fiscal da loja e ao fluxo do pedido.

Os detalhes de cada requisição (campos, formatos e possíveis erros) estão descritos nos endpoints abaixo.

Entidades Envolvidas

• Pedido: referência para a qual a NF se relaciona; nos proxies, o pedido é o eixo da URL ({orderId}).
• Dados fiscais / NF: conteúdo ou metadados retornados pelos proxies; payload de atualização em lote conforme validação da API.

Notas e Considerações

• Separe mentalmente atualização fiscal em lote (prefixo /orders/invoice) das rotas de detalhe do pedido que apenas consultam XML ou URL.
• Sempre confira escopos e throttle na página de cada endpoint antes de usar em produção.

Atualização de Dados Fiscais

Descrição

Este endpoint permite a atualização massiva de informações fiscais associadas a pedidos. O acesso a esta funcionalidade exige o escopo de permissão ORDER_WRITE.

É a rota principal para que sistemas externos ou ERPs informem à plataforma os dados das notas fiscais geradas, como número, chave de acesso e série.

O sistema sincroniza os dados para cada pedido enviado na lista. Se os registros já existirem, eles são atualizados; caso contrário, novas informações fiscais são vinculadas ao pedido.

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/orders/invoice \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "orders": [
7      {
8        "orderId": 123,
9        "number": "000123456",
10        "key": "35210112345678000190550010001234561234567890",
11        "serie": "1"
12      }
13    ]
14  }'

✅ Resposta de Sucesso

1[
2  {
3    "orderId": 123,
4    "number": "000123456",
5    "key": "35210112345678000190550010001234561234567890",
6    "serie": "1",
7    "url": null,
8    "xml": null,
9    "error": null
10  }
11]

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Visualização de PDF da Nota Fiscal

Descrição

Este endpoint atua como um facilitador para o acesso direto ao arquivo PDF da nota fiscal vinculada a um pedido. O acesso exige o escopo de permissão ORDER_READ.

O sistema obtém a URL nos registros fiscais, faz a requisição GET a esse endereço e repassa o corpo da resposta ao cliente. O Content-Type da resposta da API segue o informado pelo servidor remoto quando disponível; em geral espera-se PDF, mas isso depende do que a URL externa devolver.

Caso não exista URL de nota fiscal associada, a API responde 204 No Content. Se a URL existir mas a requisição externa falhar, a resposta pode vir vazia ou com código HTTP de erro conforme o tratamento atual do gateway.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/orders/123/invoice-url \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

Corpo binário retornado pela URL da nota (em cenários típicos, PDF).

Headers de Resposta (típico):

• Content-Type: costuma refletir o header da resposta remota; se ausente, pode ser assumido application/pdf pelo servidor.

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Visualização de XML da Nota Fiscal

Descrição

Este endpoint permite a extração e visualização do conteúdo XML bruto da nota fiscal de um pedido. O acesso exige o escopo de permissão ORDER_READ.

O sistema realiza uma tentativa de formatação (pretty-print) do XML para garantir que a estrutura esteja legível, facilitando a auditoria técnica e integrações que dependem desses dados.

Se o pedido não possuir um XML fiscal vinculado, a resposta será um código 204 No Content. É uma ferramenta essencial para verificação detalhada de dados fiscais eletrônicos.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/orders/123/invoice-xml \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

Conteúdo XML formatado.

Headers de Resposta:

• Content-Type: application/xml

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.