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;

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"
status	Status para indicar a situacao para nota fiscal	Sim	Enum	"approved"
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 a chave de acesso pode ser observada no seguinte aqui.

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 digito 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>",
    "status": "approved"
  }'

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.
Unauthorized	401	Utilize um token inválido ou ausente no cabeçalho da requisição.