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.
- 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
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.
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. |