Enviar NF-e de entrega

Introdução

Adiciona uma nota fiscal ao pacote. Este endpoint permite que o vendedor (seller) adicione uma nota fiscal a uma entrega utilizando o id como referência no ambiente de sandbox da Open API Magalu.

Pré-requisitos

Antes de criar uma nota fiscal, certifique-se de atender aos seguintes requisitos:

• Utilizar um channel_id válido para o ambiente de sandbox;
• Garantir que o pedido associado à entrega esteja em com o status approved. Observe o endpoint para alteração de status do pedido, para ser feito corretamente;

Escopos Necessários

Para realizar a consulta de notas fiscais, os seguintes escopos de autenticação devem estar habilitados para o token de acesso:

• open:order-order-seller:write
• open:order-delivery-seller:write
• open:order-logistics-seller:write

Exemplo de Requisição

Campo	Descrição	Obrigatório	Tipo	Exemplo
amount	Valor da nota fiscal	Sim	Decimal	100.0
key	Chave de acesso da nota fiscal	Sim	String	"35230968422419000175550040000490061048949750"
xml	Documento xml da nota fiscal	Sim	String	<nfeProc versao="4.00" xmlns="http://www.portalfiscal.inf.br/nfe">...</nfeProc>
issued_at	Momento que foi gerada a nota fiscal	Sim	Datetime	"2025-03-14T15:12:20.311179"
issuer	Identificador pessoal: CPF	Não	String	"00000000000"

Sugestão para geração do campo key

A chave de acesso da nota fiscal eletrônica (NF-e) é composta por 44 caracteres numéricos que seguem uma estrutura específica. A sugestão para gerar e utilizar a chave de acesso pode ser observada abaixo:

1: Montar a Chave Base (43 dígitos)

Junte os resultados das etapas anteriores.

1. Concatene a parte aleatória de 32 dígitos com o timestamp de 11 dígitos.

• Parte Aleatória: 98315023817471058437256700223479

• Timestamp: 17570415091

• Chave Base Resultante: 9831502381747105843725670022347917570415091

2: Dígito verificador

O dígito verificador valida o status da nota fiscal e deve estar dentro dos intervalos mencionados abaixo:

• Para awaiting_validation o dígito deve estar entre o intervalo de 0 e 3.
• Para approved o dígito deve estar entre o intervalo de 4 e 6.
• Para invalid o dígito deve estar entre o intervalo de 7 e 9.
• Caso o dígito não esteja dentro desses intervalos, a requisição retornará um erro de validação.

ex.: 35230968422419000175550040000490061048949750 ✅ (válido, pois o dígito é 0, que está entre 0 e 3) - awaiting_validation
ex.: 35230968422419000175550040000490061048949755 ✅ (válido, pois o dígito é 5, que está entre 4 e 6) - approved
ex.: 35230968422419000175550040000490061048949758 ✅ (válido, pois o dígito é 8, que está entre 7 e 9) - invalid
ex.: 3523096842241900017555004000049006104894975A ❌ (Erro, pois o dígito não é numérico e não está entre 0 e 9) - Error

atenção

Importante ressaltar que para a criação de uma nota fiscal, o campo key deve ser único por pedido. Caso uma nota fiscal com a mesma chave já tenha sido criada anteriormente, a requisição retornará um erro.

info

Observe as regras para gerar a chave de acesso, é importante verificar o contexto em função da validação do dígito verificador.

Abaixo, um exemplo de chamada utilizando cURL para envio de uma nota fiscal:

curl --request POST \
  --url https://api-sandbox.magalu.com/seller/v1/deliveries/:id/invoices \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
    "amount": 100,
    "channel": {
      "extras": {},
      "id": "e83ed3c7-7bae-47c4-9dcd-d12f6329fe1a"
    },
    "issued_at": "2025-03-14T15:12:20.311179",
    "issuer": "00000000000",
    "key": "35230968422419000175550040000490061048949750",
    "xml": "<nfeProc versao=\"4.00\" xmlns=\"http://www.portalfiscal.inf.br/nfe\">...</nfeProc>"
  }'

Cenários de Sucesso

{
  "202": {
    "description": "Successful Response",
    "content": {
      "application/json": {
        "schema": {
          "title": "InvoiceResponse",
          "type": "object",
          "required": ["key", "issued_at", "status"],
          "properties": {
            "issued_at": {
              "title": "Data de emissão da nota fiscal",
              "type": "string",
              "format": "date-time",
              "example": "2021-07-22T13:06:28.000Z"
            },
            "key": {
              "title": "Chave da nota fiscal",
              "type": "string",
              "example": "55080701212344000127550010000000981364117781"
            },
            "status": {
              "title": "Status da nota fiscal",
              "type": "string",
              "example": "approved|validating|invalid"
            }
          }
        }
      }
    },
    "headers": {}
  }
}

Cenários de Erro

Estes são exemplos de respostas de erro que podem ser retornadas durante a execução de requisições no ambiente de sandbox.

Cenário de Erro	Código HTTP	Como simular o cenário
Channel id '{channel_id}' is unknown for the Sandbox environment.	422	Envie uma requisição com um channel_id inválido ou inexistente no ambiente de sandbox.
Forbidden	403	Ausência dos escopos necessários no Token gerado para estar utilizando o endpoint.
Invalid or missing parameters.	400	Envie a requisição com dados malformados ou omita campos obrigatórios, como amount, key, xml, status, issue_at ou channel.id. Este erro também pode ocorrer se o dígito verificador do campo key não estiver dentro dos intervalos válidos (0-9), o que é uma validação específica do contexto da NF-e.
Unauthorized	401	Utilize um token inválido ou ausente no cabeçalho da requisição.