Pular para o conteúdo principal

Como criar e acompanhar Entregas em ambiente Sandbox

  • O sandbox da Open API Magalu para o módulo de Entregas tem todas as chamadas/endpoints que temos em produção, sendo assim, você poderá usar o POST de Enviar NFe da Entrega e nas Notas fiscais o GET de Busca NF-es e o GET de NF-e de fulfillment neste ambiente também. Caso precise de mais informações, consulte o link de Entregas.
  • Para simular o envio de notas fiscais do seller, este ambiente conta com a adição do endpoint de criação de envio de notas fiscais.
  • Lembre-se de alterar o canal para o de Sandbox: https://api-sandbox.magalu.com e 5f62650a-0039-4d65-9b96-266d498c03bd
atenção

Verifique, no entanto, se sua aplicação configurada para o ambiente de Sandbox possui já os escopos configurados para Entregas. Veja a seguir quais são.

Escopos de Entregas

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

Chave de Acesso Simples com UUID Numérico e Timestamp

Visão Geral

Este documento descreve um método direto e simplificado para gerar uma chave de acesso de 44 dígitos, composta exclusivamente por números. A metodologia utiliza os dígitos numéricos de um UUID padrão (Identificador Único Universal) e um timestamp para garantir um alto grau de unicidade.

O objetivo é fornecer uma regra de geração simples, resultando em uma chave de 43 dígitos numéricos mais um dígito verificador.

Estrutura da Chave de Acesso

A chave será montada da seguinte forma:

  • [ 32 dígitos do UUID Numérico ] + [ 11 dígitos do Timestamp ] + [ 1 Dígito Verificador ]

  • Total de dígitos: 44

  • Base para o Dígito Verificador: 43 dígitos

Etapas da Geração

Etapa 1: Gerar a Parte Aleatória (32 dígitos)

Esta etapa combina a extração de números de um UUID com a geração de números aleatórios para preencher o espaço restante, evitando o uso de zeros fixos.

  1. Gere um UUID v4 padrão.
  • Exemplo: f47ac10b-58cc-4372-a567-0e02b2c3d479
  1. Extraia apenas os dígitos numéricos do UUID.
  • Do exemplo acima, sobram: 471058437256700223479

  • Anote o tamanho desta sequência. Neste caso, 21 dígitos.

  1. Calcule quantos dígitos faltam para completar 32.
  • Cálculo: 32 (tamanho desejado) - 21 (tamanho atual) = 11 dígitos faltantes.
atenção

Lembre-se que a quantidade de dígitos faltantes pode variar dependendo do UUID gerado.

  1. Gere um número aleatório com a quantidade exata de dígitos faltantes.
  • Precisamos de um número aleatório de 11 dígitos.

  • Exemplo de número aleatório gerado: 98315023817

  1. Combine o preenchimento aleatório com os números do UUID. Você pode concatená-los da forma que preferir. Uma abordagem comum é colocar o número aleatório no início (prefixo).
  • Preenchimento Aleatório: 98315023817

  • Números do UUID: 471058437256700223479

  • Resultado Final (32 dígitos): 98315023817471058437256700223479

Etapa 2: Obter o Timestamp (11 dígitos)

Usaremos um timestamp para adicionar um componente temporal e evitar colisões.

  1. Obtenha o timestamp Unix atual em milissegundos.
  • Exemplo: 1757041509123
  1. Extraia os primeiros 11 dígitos.
  • Resultado Final (Timestamp): 17570415091

Etapa 3: 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

Etapa 4: Digito verificador

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

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

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