Introdução

Bem-vindo ao KaBuM!

A partir de agora, iniciaremos sua jornada de integração no maior e-commerce de Tecnologia e Games da América Latina.

Nesse portal, você terá acesso às documentações da Mirakl, instruções sobre o seu primeiro acesso, links úteis incluindo acesso exclusivo a IA da Mirakl e ao roteiro de integração.

Todos os documentos de estudo para conhecer nossas API’s e a documentação da Mirakl estão disponíveis nos links abaixo:

• Documentação geral: developer.mirakl.com/mmp/...
• Documentação produtos: developer.mirakl.com/mcm/...
• IA da Mirakl para auxílio complementar: help.mirakl.com

Acesso

📍 Marco Zero: Autenticação

Antes de qualquer requisição, a sua aplicação precisa ter permissão para falar com o KaBuM!. O primeiro passo é acessar nosso ambiente de homologação, conhecido como Ambiente DEV.

1. Acesse: kabum-dev.mirakl.net/login
2. Entre com o seu e-mail de cadastro e senha.

Nosso ambiente de homologação (ou testes) deve ser acessado através do link: kabum-dev.mirakl.net

GERANDO A CHAVE DE API/TOKEN (Mirakl)

1. No canto superior direito, clique no seu usuário e, em seguida, em Configurações pessoais;
2. Clique na aba Chave de API;
3. Clique no botão Ações e, em seguida, em Gerar uma nova chave de API.

Na tela que será exibida, digite GENERATE para confirmar a criação da chave de API e, em seguida, clique em Gerar.

Em seguida, irá aparecer sua chave API, clique em Copiar chave API e a utilize para iniciar sua integração.

Etapas para Homologação

Etapa 1.1 - H11

1.1 | H11 — Descoberta da Árvore de Categorias (Hierarquias)

Esta API retorna a estrutura completa de categorias (pais e filhos) aceitas pelo KaBuM!. Ela é o primeiro passo obrigatório para que o Seller consiga classificar seus produtos corretamente.

Antes de enviar qualquer produto, sua aplicação deve mapear a árvore de categorias e as exigências (atributos) de cada uma delas. Recomenda-se que esta etapa seja executada periodicamente (ex.: uma vez ao dia) para manter o ERP ou a plataforma de integração devidamente atualizados.

📌 Parâmetros da API

Para otimizar a performance e a relevância dos dados, utilize os seguintes filtros:

• hierarchy (String): Permite filtrar por um código de categoria específico. Útil se o Seller atua apenas em um segmento (ex.: somente Informática). A API retornará apenas os níveis superiores (pais) e inferiores (filhos) desse ramo.
• max_level (Integer): Define a profundidade da árvore que se deseja buscar. Caso queira apenas as categorias principais, utilize max_level=1. Para a árvore completa, deixe o campo vazio ou utilize um valor alto.

🚩 Lista de Falhas e Desafios Comuns na H11

💡 Lógica de Implementação Recomendada

• Identificando Categorias Folhas: Como saber se uma categoria aceita produtos? Ao consumir o JSON da H11, verifique o array children.
  • Se children estiver vazio, essa é uma categoria Folha (Pode receber produtos).
  • Se children contiver dados, essa é uma categoria Pai (Não pode receber produtos).
• Experiência do Usuário (UX): Não mostre milhares de códigos para o Seller. Na interface do seu ERP, mostre o label (nome amigável) e o caminho completo (Breadcrumb), ex: Hardware > Armazenamento > SSD. Isso reduz drasticamente os erros de mapeamento por parte do usuário.
• HTTP RETURN CODES:
  • 200 OK: Sucesso total. A árvore está no corpo da resposta.
  • 404 Not Found: Se você passou um hierarchy_code que não existe.

⏳ Linha do Tempo da Integração

Esta etapa é a base de tudo e deve ser tratada como um processo de Setup e Manutenção.

1. Gatilho (Configuração Inicial): Antes de enviar o primeiro produto, a integradora deve baixar a árvore completa via H11.
2. Interface de Mapeamento (De/Para): No ERP/HUB, o desenvolvedor deve criar uma tela onde o Seller associa:
   "Minha categoria 'Memória RAM' no ERP" → corresponde a → "Categoria 'Hardware > Memórias > Desktop' no KaBuM!".
3. Rotina Periódica: Implementar um job (ex: 1x ao dia ou semanal) para atualizar a árvore local. O KaBuM! pode criar novas categorias ou desativar antigas para otimizar o site.
4. Próximo Passo: Após o mapeamento da categoria na H11, a integradora deve chamar a PM11 para descobrir quais atributos aquela categoria exige.

Etapa 1.2 - PM11

1.2 | PM11 — Atributos e Regras de Validação

Esta API apresenta todos os parâmetros de atributos que um produto deve possuir, desde palavras proibidas até campos obrigatórios, detalhando as regras de cada um.

Ela deve ser mapeada após a H11 e antes da P41. Utilize o parâmetro requirement_level para validar se o atributo é REQUIRED (obrigatório) ou OPTIONAL (opcional) no seu payload de produto.

📌 Parâmetros da API

Para evitar o download de atributos desnecessários, você deve filtrar a chamada utilizando:

• hierarchy_code (String): O código da categoria obtido na H11.
• max (Integer): Define o limite de resultados (recomenda-se 100).
• shop_id (Integer): Identificador da sua loja.

Ao receber o JSON da PM11, seu código deve focar nos seguintes campos para cada atributo:

• code: O ID técnico do atributo (ex.: cor-predominante). Este é o código que será utilizado no CSV/JSON da P41.
• label: O nome amigável para exibição ao Seller (ex.: "Cor Predominante").
• requirement_level:
  • REQUIRED: Se não enviado, o produto será rejeitado.
  • OPTIONAL: Envio recomendado para melhor SEO, mas não bloqueia a criação.
• type: Define o formato do dado:
  • LIST: Permite apenas o envio de valores que estejam dentro da lista predefinida.
  • TEXT / NUMBER: Aceita texto livre ou números.
• values (Array): Se o tipo for LIST, este array conterá o code e o label dos valores permitidos (ex.: AZUL, PRETO).

🚩 Lista de Falhas e Desafios Comuns na PM11

💡 Lógica de Implementação Recomendada

• Cache Estratégico: A lista de atributos de uma categoria não muda a cada minuto. Dica: Armazene o retorno da PM11 em um banco de dados ou em cache de disco por categoria. Isso acelera a renderização do formulário no seu ERP e economiza chamadas de API.
• Tratamento de Unidades de Medida: Alguns atributos vêm com unidades (ex.: weight em gramas ou quilos); a PM11 indica isso. Certifique-se de que seu ERP faça a conversão automática para que o Seller não envie "1" (quilo) quando o marketplace espera "1000" (gramas).
• HTTP RETURN CODES: Será retornado o código 200 quando a requisição for efetuada com sucesso.

⏳ Linha do Tempo da Integração

1. Gatilho: O Seller selecionou a categoria "Teclados" (H11) no seu ERP.
2. Consulta: Sua aplicação chama GET /api/products/attributes?hierarchy_code=teclados-gamer.
3. Montagem Dinâmica: O ERP renderiza um formulário para o Seller contendo apenas os campos que o KaBuM! exige para aquela categoria.
4. Validação Local: Antes de disparar a P41, o seu sistema verifica: "O Seller preencheu todos os campos REQUIRED? Os campos do tipo LIST estão com valores válidos?".
5. Próximo Passo: Com os dados validados pela PM11, o arquivo de importação da P41 está pronto para ser gerado com erro zero.

Guia Prático de Produtos

CARACTERÍSTICAS DO PRODUTO

Os principais recursos e características do produto:

1. Nome do produto (product_shop_title)
2. Imagem(s) (product_image1)
3. Descrição (product_shop_description)
4. Product_ID (SHOP_SKU)
5. Dimensões (product_weight, product_height, product_width, product_depth)
6. Categoria (category_shop)
7. EAN (ean)

DEFINIÇÕES DOS CAMPOS DE MEDIDAS DO PRODUTO

• Altura: deve ser inserido somente os números em centímetros, sem decimal.
  (Exemplo: 38 = 38cm)
• Largura: deve ser inserido somente os números em centímetros, sem decimal.
  (Exemplo: 59,2 = 59cm)
• Profundidade: deve ser inserido somente os números em centímetros, sem decimal.
  (Exemplo: 1m = 100cm)
• Peso: deve ser inserido somente os números em gramas, sem decimal.
  (Exemplo: 2Kg = 2000g)

DEFINIÇÕES DO CAMPO DE “IMAGEM”

As imagens são muito importantes na decisão de compra do cliente, por isso prezamos para que elas tenham uma boa qualidade para a visualização do produto, logo ela precisa cumprir os seguintes requisitos:

• Fundo branco
• Boa qualidade
• Estar de acordo com a realidade
• Tamanho de 800x800 ou 1000x1000 pixels
• Não deve ter logotipos, marca d'águas, selo de brindes e etc.

O QUE É KBM?

KBM é um identificador interno do KaBuM! para ser utilizado em produtos com Kits, Exclusivos e usados a fim de evitar o match indevido com produtos que possua EAN correto.

Exemplo: Um celular novo com um celular usado de sellers diferentes. KBM2112896542

• KBM: KaBuM!
• Id da Loja: compostos por 4 dígitos
• SKU de Oferta: com 6 dígitos

Etapa 2.1 - P41

2.1 | P41 - Importação de Produtos

Essa API é responsável por enviar toda a ficha técnica de um produto para aprovação do operador. Diferente da OF01 ela envia apenas o produto, e não a oferta em conjunto.

A criação de produtos é um processo assíncrono. Pense na P41 como uma "caixa de entrada": você deixa o arquivo lá, recebe um comprovante (import_id) e volta mais tarde para ver se os produtos foram aceitos. Essa arquitetura permite que você envie milhares de itens de uma só vez sem travar a conexão do seu ERP.

📌 Parâmetros da API

Diferente de APIs JSON, a P41 exige um envio do tipo formulário para carregar o arquivo físico.

• file (Binary - Obrigatório): O arquivo contendo os produtos.
  • Padrão KaBuM!: CSV (separado por ponto e vírgula ;).
  • Encoding: Use sempre UTF-8 para evitar quebras em caracteres especiais (acentos, cedilha).
• import_mode (String - Recomendado):
  • NORMAL: (Modo Seguro) Ele atualiza produtos que já existem e cria os novos. É o modo que você deve usar em 99% dos casos.
  • REPLACE: (Modo Destrutivo) Ele apaga todos os produtos do Seller que não estiverem no arquivo.
    Dica: Evite este modo para não causar perda de dados acidental.

🚩 Lista de Falhas e Desafios Comuns na P41

💡 Lógica de Implementação Recomendada

• Gestão de Lotes: Não envie um produto por vez. Agrupe os produtos em lotes (ex: a cada 50 ou 100 itens) para otimizar o uso da API e facilitar a leitura dos relatórios de erro posteriormente.
• URLs de Imagens: O KaBuM! exige imagens de alta qualidade. Na P41, você envia apenas os Links (URLs) das fotos.
  Dica: Verifique se as fotos têm fundo branco e dimensões mínimas de 800x800 antes mesmo de gerar o arquivo da P41. Isso evita que o produto seja reprovado pelo operador lá na frente.
• O que fazer com o import_id? Não trate o import_id como um dado descartável. Exiba-o no log de integração do seu ERP. Se o Seller ligar para o suporte do KaBuM!, esse ID será a primeira informação solicitada para localizar o lote.

⏳ Linha do Tempo da Integração

1. Gatilho (ERP): O Seller terminou de cadastrar os produtos no ERP e solicitou o envio para o KaBuM!.
2. Pré-Validação (Obrigatória): O seu sistema deve validar o arquivo localmente usando as regras da PM11 (verificar se todos os campos REQUIRED estão lá).
3. Execução: Chamada POST /api/products/imports.
4. Resposta de Sucesso (201 Created): A Mirakl devolve um JSON contendo o import_id.
   Ação Crítica: Sua integradora DEVE salvar esse import_id no banco de dados para rastreabilidade.
5. Próximo Passo: Iniciar o monitoramento de status através da P42.

Etapa 2.2 - P42

2.2 | Obtenha o status de importação de um produto (API P42)

Você não deve assumir que o produto foi criado só porque a P41 retornou 201. A P42 é o "GPS" do seu processamento.

Nessa etapa, utilizamos a API como endpoint de consulta (polling) que informa o estágio atual do processamento do lote de produtos enviados. Ela é o "cérebro" que decide se sua aplicação deve baixar um relatório de erro ou um relatório de sucesso.

📌 Parâmetros da API

• Parâmetro de Path (Obrigatório):
  import (Integer): O ID da importação (aquele que você salvou no banco de dados após a P41).
  Exemplo: GET /api/products/imports/5501

Estados do Processamento (import_status)

Sua aplicação deve estar preparada para ler e reagir aos seguintes status:

• QUEUED / WAITING_IMPORTATION: O arquivo está na fila.
  Ação: Aguarde e consulte novamente em 1 minuto.
• IMPORTING: A Mirakl está lendo as linhas e validando os atributos (PM11) e hierarquias (H11).
  Ação: Mantenha o polling.
• COMPLETE: O ciclo de processamento terminou.
  Ação: Pare o polling e verifique as flags de relatório.

🚩 As Flags de Decisão

Dentro do JSON de resposta da P42, existem campos booleanos (true/false) que dizem exatamente o que aconteceu com os produtos:

💡 Lógica de Implementação Recomendada

• Sugerimos que a integração não deixe o processamento da P42 "escondido". No painel do seu ERP, mostre uma barra de progresso ou o status atual (Ex: "Status no KaBuM!: Processando..."). Isso reduz a ansiedade do Seller e evita que ele tente reenviar o mesmo arquivo várias vezes.
• Recomendamos também guardar o resultado final da P42 (quantos produtos foram processados, quantos deram erro) no seu banco de dados. Isso serve como um histórico de saúde da conta do Seller.

🚩 Lista de Falhas e Desafios Comuns na P42

⏳ Linha do Tempo da Integração

1. Gatilho: Recebimento do import_id da P41.
2. Início do Polling: A integradora faz a primeira chamada à P42 após 30-60 segundos.
3. Loop de Espera: Enquanto o status for diferente de COMPLETE, o sistema repete a consulta (sugestão: use Exponential Backoff).
4. Análise Final: O status mudou para COMPLETE.
   • Se houver erros: O sistema baixa o relatório (P44/P47) e exibe os erros para o Seller no ERP.
   • Se houver sucessos: O sistema baixa o relatório (P45) e marca os produtos como "Em Validação" no ERP.
5. Próximo Passo: Com os produtos criados, o Seller deve agora preparar o envio das ofertas (OF24/OF01).

Etapa 2.3 - P44 | P45 | P46 | P47

2.3 | P44 > P45 > P46 > P47 - Baixar relatórios/arquivos gerados pelo import

Depois que o P42 indicar que o processamento terminou, o HUB deve olhar as flags retornadas e baixar os arquivos correspondentes.

P44 — baixar o error report (“Non-integrated products report”)

Use quando has_error_report = true.

Essa é a API mais importante para o suporte técnico do Seller, pois sem ela o Seller fica "cego". A P44 é disparada quando a estrutura do seu arquivo está correta, mas o conteúdo viola as regras do KaBuM!.
Exemplo: você enviou uma "Cor" que não existe na lista da PM11, ou esqueceu o "Peso" que é obrigatório.

O que retorna: Um ficheiro (geralmente CSV) contendo as linhas que falharam e a coluna exata com a mensagem de erro (ex: "Valor 'Azul Marinho' não permitido para o atributo 'Cor'").

📌 Parâmetros da API

• Parâmetro de Path (Obrigatório):
  import (Integer): O ID da importação gerado na P41.

🚩 Lista de Falhas Comuns na P44

⏳ Linha do Tempo da Integração

1. Gatilho (P42): O status da importação é COMPLETE e a flag has_error_report é true.
2. Execução: Sua aplicação faz o GET na P44 e faz o download do arquivo CSV.
3. Processamento: O sistema deve ler o CSV. A Mirakl adiciona colunas extras ao final de cada linha, descrevendo o erro.
4. Exibição: O ERP deve mapear o erro ao SKU correspondente e mostrar ao Seller: "Erro no SKU 123: O atributo 'Voltagem' é obrigatório para a categoria 'Eletro'."
5. Próximo Passo: O Seller corrige o dado no ERP e a integradora reinicia o fluxo na P41.

HTTP RETURN CODES: O código 200 será retornado quando a requisição ocorrer com sucesso.

P45 — baixar o integration report (“Added products report”)

Use quando has_new_product_report = true.

Essa API retorna a confirmação de que os produtos entraram na base com sucesso com a lista de produtos que foram aceitos e integrados no catálogo.

Use essa API para atualizar o status do produto no seu ERP para "Integrado / Em Validação". Lembre-se que, no KaBuM!, o produto pode ser integrado, mas ainda passar por uma curadoria humana antes de ficar visível.

📌 Parâmetros da API

• Parâmetro de Path (Obrigatório):
  import (Integer): O ID da importação gerado na P41.

⏳ Linha do Tempo da Integração

1. Gatilho (P42): O status da importação é COMPLETE e a flag has_new_product_report retornou true.
2. Execução: A integradora realiza o GET na P45 para baixar o arquivo de sucesso.
3. Processamento Local: O ERP lê o arquivo (geralmente mapeando o shop_sku enviado com o product_id gerado pela Mirakl).
4. Atualização de Status Interno: O sistema altera o status do produto no banco de dados do ERP de "Pendente" para "Integrado / Aguardando Oferta".
5. Próximo Passo: Disparar a API de Ofertas (OF24) para os SKUs listados neste relatório.

P46 — baixar o transformed file (“File in operator format”, CSV)

Use quando has_transformed_file = true.

Essa API permite baixar o arquivo de produtos exatamente como ele ficou após passar pelas Regras de Transformação do operador (KaBuM!), sendo muito útil para ver como o dado ficou antes de entrar no banco.

📌 Parâmetros da API

• Parâmetro de Path (Obrigatório):
  import (Integer): O ID da importação gerado na P41.

🚩 Lista de Falhas e Desafios Comuns na P46

⏳ Linha do Tempo da Integração

1. Gatilho (P42): O status da importação é COMPLETE e a flag has_transformed_file é true.
2. Cenário de Uso: O desenvolvedor ou o Seller percebe que um produto foi aceito (P45), mas o nome dele no site está diferente do que foi enviado originalmente no ERP.
3. Execução: Chamada GET na P46 para baixar o arquivo processado.
4. Análise: Comparar o arquivo original enviado na P41 com o arquivo retornado pela P46.
5. Conclusão: Identificar se existe uma regra de transformação no marketplace que está alterando os dados (útil para ajustar o ERP e evitar surpresas).

P47 — baixar o transformation error report (“Source file error report”)

Use quando has_transformation_error_report = true.

Essa API é voltada para o Desenvolvedor. Antes de validar se a "Cor" ou o "Preço" estão certos, a Mirakl tenta abrir e ler o arquivo. Se o delimitador estiver errado ou o arquivo estiver corrompido, ela gera um erro de transformação e nenhum produto foi sequer analisado.

📌 Parâmetros da API

• Parâmetro de Path (Obrigatório):
  import (Integer): O ID da importação.

🚩 Lista de Falhas Comuns na P47 (Erros do Desenvolvedor)

💡 Dicas de Implementação

• Tratamento de Erros Silenciosos: Muitas vezes o status é COMPLETE, mas o has_error_report é true. Se sua integração apenas olha o status, ela dirá ao Seller que "deu tudo certo" enquanto os produtos foram rejeitados. Sempre cheque as flags booleanas.
• Shop ID: Use sempre o parâmetro shop_id nas requisições P44, P45, P46 para garantir que está lendo os dados da loja correta, especialmente se o seu HUB gerar múltiplas contas.
• Histórico de Logs: Guarde o import_id e os ficheiros de erro (P44/P47) por pelo menos 30 dias. Se o Seller reclamar que um produto não subiu, você tem o log técnico para provar o motivo.

Recapitulação do Fluxo de Relatórios (MCM)

# Pseudo-código de Orquestração
status = consultar_P42(import_id)

if status == "COMPLETE":
    if has_transformation_error: 
        baixar_P47() # Erro de código/estrutura - Alerta para a TI
    
    if has_error_report:
        baixar_P44() # Erro de negócio - Alerta para o Seller
    
    if has_new_product_report:
        baixar_P45() # Sucesso - Atualiza banco local

Etapa 3.1 - OF24 vs OF01

3.1 | JSON (OF24) vs Arquivo (OF01)

A Mirakl oferece dois caminhos para gerenciar ofertas, e a escolha vai depender do volume de dados e da frequência de atualização da sua operação. De modo simples, elaboramos um comparativo entre OF24 vs OF01.

🔄 Comparativo Estratégico: Quando usar cada uma?

3.1.1 | OF24 - Atualização de Ofertas via JSON (Recomendado)

Frequência: Recomendado a cada 5 minutos.

A OF24 é uma API de escrita direta. Ela é usada para atualizações pontuais e frequentes, sendo a API ideal para o dia a dia, especialmente para sincronização de estoque e mudanças rápidas de preço.

Diferente da P41, a OF24 é processada quase em tempo real. Ela é projetada para que o ERP envie alterações assim que elas ocorrem (ex: uma venda na loja física que baixou o estoque).

📌 Parâmetros da API

• shop_sku (String/Obrigatório): Seu código identificador único no ERP.
• product_id (String/Obrigatório): O ID do produto (EAN ou ID Mirakl) ao qual a oferta se vincula.
• price (Decimal/Obrigatório): Preço final de venda (Preço "Por").
• p_list_price (Decimal/Opcional): Preço de tabela (Preço "De"). Deve ser >= price.
• quantity (Integer/Obrigatório): Saldo físico disponível para o KaBuM!.
• leadtime_to_ship (Integer/Obrigatório): Dias úteis para postagem.
  Atenção: Erros aqui impactam o cálculo do frete e o SLA de entrega.
• update_delete (String): Use update para criar/atualizar ou delete para remover a oferta da vitrine.

Resposta Imediata: A API retorna 201 Created ou 200 OK indicando que o pedido de atualização foi recebido.

🚩 Lista de Falhas Comuns na OF24

⏳ Linha do Tempo da Integração

1. Gatilho (ERP): Ocorre uma venda em outro canal ou entra uma nota no estoque do Seller.
2. Preparação: O ERP monta o objeto JSON.
   Dica: Busque os dados atuais da oferta para garantir que o envio seja completo (evitando o efeito do full-replacement).
3. Execução: Chamada POST /api/offers.
4. Resposta Imediata: A API retorna 201 ou 200. O processamento é concluído em segundos.
5. Próximo Passo: Auditoria via OF21 para validar se a oferta está active: true.

3.1.2 | OF01 - Importação de Ofertas via Arquivo

A OF01 é a "irmã" da P41. Porém, além de ser assíncrona, ela envia o produto + oferta na mesma API. Você envia um arquivo (CSV ou XLSX) e recebe um import_id para acompanhar o processamento. Ideal para cargas massivas (milhares de SKUs de uma vez) ou para a carga inicial.

Use a OF01 quando precisar atualizar centenas ou milhares de itens de uma só vez (ex: uma Black Friday em que 5.000 itens mudam de preço simultaneamente). Enviar 5.000 JSONs individuais via OF24 causaria um Rate Limit (bloqueio por excesso de chamadas), enquanto a OF01 resolve isso em um único upload.

📌 Parâmetros da API

• file (Binary/Obrigatório): O arquivo físico. No KaBuM!, utilize CSV separado por ponto e vírgula (;).
• import_mode (String/Obrigatório):
  • NORMAL: (Padrão) Atualiza o que existe e cria o que é novo.
  • REPLACE: CUIDADO EXTREMO. Deleta todas as ofertas do Seller que NÃO estiverem no arquivo enviado.

🧠 A Lógica por trás das Ofertas

Quando chegam no módulo de ofertas, existe um ponto que confunde muitos desenvolvedores: "Mandei a oferta, mas ela não aparece no site do KaBuM!. Por quê?"

A resposta está no status de validação. Para uma oferta ser pública, ela precisa passar por 3 filtros:

• Filtro Técnico: O JSON ou Arquivo está formatado corretamente? (Erro 400 ou OF03).
• Filtro de Vínculo: O product_id informado existe no catálogo aprovado? Se o produto ainda estiver "Em Validação" (P41), a oferta ficará oculta com o motivo PRODUCT_STATUS_PENDING, pois, para uma oferta ser ativa no front, precisa majoritariamente de um produto com status aprovado.
• Filtro Comercial: O preço está dentro das regras de negócio? O estoque é maior que zero?

Esse checklist simples é fundamental para entender o motivo de uma oferta não ter se tornado pública ainda, mas para conferir possíveis erros é possível fazer polling na API OF02, assim como na P42 para saber quando o processamento do arquivo terminou e obter um relatório através da OF03 que dirá a linha exata da falha.

🚩 Lista de Falhas Comuns na OF01

⏳ Linha do Tempo da Integração

1. Gatilho (Operacional): O Seller decide atualizar os preços de toda a loja para uma campanha.
2. Geração: O ERP gera o arquivo (CSV/XLSX) contendo todos os campos exigidos.
3. Execução: Chamada POST /api/offers/imports.
4. Recuperação de Ticket: O sistema captura o import_id retornado (201 Created).
5. Monitoramento: O sistema inicia o polling na OF02 até o status COMPLETE.

Etapa 3.2 - OF02

3.2.1 | OF02 - Monitoramento de Importação

Assim como a P42 serve para produtos, a OF02 é um endpoint de consulta (polling) que retorna o progresso e o resultado final de um lote de ofertas enviado anteriormente via OF01. Ela diz em que estágio o lote de preço/estoque se encontra.

Como o processamento de arquivos pode levar de alguns segundos a alguns minutos (dependendo da fila global da Mirakl), a OF02 serve para que sua integração não precise manter uma conexão aberta esperando o arquivo terminar. Você "pergunta" periodicamente como as coisas estão indo.

📌 Parâmetros Principais

• import_id (Integer/Obrigatório): O identificador único retornado na resposta da OF01.

Estados do Processamento (import_status)

Diferente de um simples "Sucesso" ou "Erro", a OF02 possui estados intermediários que sua aplicação deve tratar:

• QUEUED (Na Fila): O arquivo foi recebido com sucesso, mas ainda está na fila de espera dos servidores da Mirakl.
  Ação: Aguarde e tente novamente em 1 minuto.
• IMPORTING (Processando): A Mirakl está lendo as linhas do seu arquivo e validando os SKUs e preços.
  Ação: Mantenha o polling.
• COMPLETE (Finalizado): O processamento terminou.
  Ação: Pare o polling. Agora é hora de olhar as flags de resultados (sucesso ou erro).

🚩 Campos Importantes na Resposta

⏳ Passo a Passo da Integração

1. Gatilho: Você recebe o import_id da OF01.
2. Início do Loop (Polling):
   • Sua aplicação faz o primeiro GET na OF02 após 30 segundos.
   • Se status == QUEUED ou IMPORTING, agende a próxima chamada para daqui a 60 segundos.
3. Saída do Loop: O status retornou COMPLETE.
4. Análise de Desvio:
   • Cenário A: has_transformation_error_report: true → Logar erro de sistema e alertar seu time técnico interno.
   • Cenário B: has_error_report: true → Chamar OF03, processar os erros e mostrar para o Seller no dashboard.
   • Cenário C: has_error_report: false → Marcar o lote como "Sincronizado com Sucesso".
5. Próximo Passo: Auditoria via OF21 para garantir que o site refletiu a mudança (opcional, para amostragem).

💡 Lógica de Implementação Recomendada

• Evite o Loop Infinito: Implemente um contador de tentativas ou um tempo máximo (ex: 15 minutos). Se após 15 minutos o status ainda for QUEUED, cancele a operação e alerte sobre uma possível instabilidade na fila da Mirakl. Isso evita que sua aplicação fique gastando recursos infinitamente.
• Feedback Visual: Se o seu ERP tem uma tela de "Histórico de Sincronização", use os dados da OF02 para mostrar uma barra de progresso ou os contadores (offer_updated_count, offer_inserted_count) para o Seller. Isso dá segurança ao usuário.

Etapa 3.3 - OF21

3.3.1 | OF21 - Listagem e Auditoria de Ofertas

Essa API realiza uma consulta síncrona ao banco de dados de ofertas da Mirakl. Ela permite recuperar o estado atualizado de um SKU, incluindo preços, estoque, prazos e, principalmente, o status de visibilidade no KaBuM!.

Diferente das APIs de importação, a OF21 não serve para enviar dados, mas para auditar. Ela é o espelho do que o cliente vê no site. Se um produto está "sem estoque" mesmo que a importação tenha dado "Sucesso", a oferta pode estar inativa por motivos externos (ex: o produto foi desativado pelo operador). A OF21 revela a "saúde" da oferta.

📌 Parâmetros da API

• offer_state_codes: Para filtrar apenas ofertas ativas ou inativas.
• sku: Para buscar um item específico do Seller.
• product_id (String): Se você quiser ver todas as ofertas vinculadas a um EAN ou ID de produto específico.

⏳ Passo a passo da Auditoria

1. Gatilho: O sistema detecta uma discrepância (ex: o Seller afirma que o produto deveria estar à venda, mas não há pedidos).
2. Ação: O ERP executa um GET /api/offers?sku={sku_do_seller}.
3. Análise de Dados:
   • Passo A: Checar active. Se true, a oferta está ok na Mirakl.
   • Passo B: Se false, iterar sobre o array inactivity_reasons.
4. Alerta ao Usuario: O sistema traduz o código técnico (ex: ZERO_QUANTITY) para uma mensagem amigável no painel do ERP: "Seu produto está inativo no KaBuM! porque o estoque informado é zero."
5. Próximo Passo: Se o erro for de dado, disparar nova OF24. Se for de aprovação, orientar o Seller a aguardar o fluxo do marketplace.

API's adicionais — Ofertas

4.3.2 | OF03 - Relatório de Erros de Oferta

Essa API extrai o detalhamento cirúrgico do que deu errado no lote de ofertas. Diferente dos erros de produto (que são técnicos), os erros de oferta costumam ser comerciais. A OF03 gera um CSV que aponta o erro por linha.

📌 Parâmetros da API

• Parâmetro de Path (Obrigatório):
  import_id (Integer): Este é o ID que você recebeu no Response da OF01. Ele deve ser injetado diretamente na URL.
  Exemplo: /api/offers/imports/12345/error_report

⚙️ Funcionalidade e Lógica de Negócio

A lógica da OF03 é baseada em segmentação de erro. Ao contrário de erros de sistema (como um JSON mal formado), os erros aqui são de integridade comercial.

⏳ Passo a Passo do Tratamento de Erros

1. Gatilho: A API OF02 retornou status COMPLETE e a flag has_error_report: true.
2. Chamada: Sua aplicação monta a URL com o import_id e executa o GET.
3. Processamento: O sistema deve ler o CSV programaticamente, identificar as linhas com falha e marcar esses SKUs no banco de dados local como "Erro de Sincronia".
4. Alerta ao Usuário: O ERP exibe uma mensagem amigável: "O item X não teve o preço atualizado porque o valor está abaixo do mínimo permitido pelo marketplace."
5. Próximo Passo: Após a correção, reinicie o fluxo com uma OF24 (correção rápida) ou nova OF01.

Etapa 4.1 - OR11

4.1 | OR11 - Consumo de Pedidos (Order Retrieval)

Essa API permite listar todos os pedidos do marketplace. Ela é utilizada pela integradora para "puxar" as vendas do KaBuM! para dentro do ERP do Seller, assim como para a validação e atualização de documentos e campos nos pedidos.

Diferente de sistemas que enviam um "push" (Webhook), a prática mais segura e comum na Mirakl é o Polling Incremental. Sua aplicação pergunta à API: "O que aconteceu de novo desde a minha última consulta?". Isso garante que nenhum pedido seja perdido por instabilidades momentâneas de rede.

📌 Parâmetros da API

A OR11 possui muitos filtros, mas para uma integração de alta performance, você deve focar nestes quatro:

• order_state_codes (String): Filtra os pedidos pelo status.
  Uso Recomendado: No fluxo de importação, use WAITING_ACCEPTANCE (Pedidos pagos e prontos para serem aceitos pelo Seller).
• start_update_date (Datetime - ISO 8601): Filtra pedidos atualizados após esta data.
  Uso Recomendado: É a base do polling incremental.
• paginate (Boolean) & max (Integer): Controla o tamanho da resposta.
  Dica: Use max=100 para evitar payloads gigantescos que podem causar timeout.
• order_ids: Permite uma consulta mais rápida por pedido ao invés de uma lista extensa.

🚩 Lista de Falhas e Desafios Comuns na OR11

⏳ Linha do Tempo da Integração

1. Gatilho (Timer): O serviço de agendamento do seu ERP dispara a cada 5 minutos.
2. Consulta:
   
   GET /api/orders?order_state_codes=WAITING_ACCEPTANCE&start_update_date={data_ultimo_sucesso}
3. Processamento Interno: Para cada pedido no JSON:
   • Checar se order_id já existe localmente.
   • Se não existir, criar o pedido no ERP.
   • Baixar todas as informações do pedido.
4. Confirmação Técnica: Armazenar o ID do pedido Mirakl vinculado ao ID do pedido interno do ERP.
5. Próximo Passo: Com o pedido salvo no ERP, o sistema deve armazenar todas as informações de pagamento essenciais para a geração de Notas Fiscais Eletrônicas (NFe) em conformidade com a Nota Técnica 2025.001 da SEFAZ.

Etapa 4.2 - NT 2025.001

4.2 | OR11 - Mapeamento Campos de Pagamento (NT 2025.001)

Esta documentação explica a estrutura e o conteúdo dos novos campos de pagamento que estarão disponíveis na API de consulta de pedidos do KaBuM!. Esses dados são essenciais para que nossos parceiros possam gerar Notas Fiscais Eletrônicas (NFe) em conformidade com a Nota Técnica 2025.001 da SEFAZ.

Todos os dados de pagamento eletrônico estarão agrupados dentro do objeto payment_details e todos os códigos foram padronizados de acordo com as tabelas oficiais da SEFAZ: Tabela de bandeiras das Operadoras de Cartão de Crédito e/ou Débito e Tabela de Meios de Pagamento.

Descrição dos Campos

A seguir, apresentamos a descrição detalhada de cada campo que pode ser retornado em nossos payloads de resposta, organizados para facilitar a compreensão e integração com nossos sistemas.

• payment_method_code: O código padronizado pela SEFAZ que indica a forma de pagamento.
• payment_amount: O valor total do pagamento da compra.
• payment_indicator: Um indicador de pagamento. O valor 0 indica pagamento à vista e 1 indica pagamento a prazo (parcelado).
• card_details: Objeto que contém os detalhes de uma transação eletrônica, como cartão de crédito, PIX ou NuPay. Ele só estará presente em pagamentos que exigem essas informações.
• integration_type: Indica se o pagamento foi processado de forma integrada (1) ou não integrada (2).
• acquirer_cnpj: O CNPJ da credenciadora ou da instituição de pagamento que processa a transação.
• card_brand_code: O código da bandeira do cartão, conforme a tabela da SEFAZ. Para transações que não se enquadram em uma bandeira, o valor será 99 (Outros).
• authorization_code: O código de autorização da transação, também conhecido como NSU ou, no caso do PIX, o E2EID.

Descrição dos Campos do Payload x Tag da NFe

Esta seção detalha como cada campo do payload da API OR11 do KaBuM! se correlaciona diretamente com as tags específicas da Nota Fiscal eletrônica (NFe), conforme exigido pela SEFAZ.

Descrição das categorias x Tpag mapeadas no KaBuM!

Esta seção apresenta as categorias de pagamento que o KaBuM! mapeia para o campo tPag da NFe.

Cenários de Pagamento e Payloads

1. PIX

Para transações via PIX, o grupo card_details é usado para fornecer os dados obrigatórios da instituição de pagamento e da autorização.

{
    "payment_details": [
        {
            "payment_method_code": "17",
            "payment_amount": 99.50,
            "payment_indicator": "0",
            "card_details": {
                "integration_type": "1",
                "acquirer_cnpj": "13121415161718",
                "authorization_code": "E119219398127391827"
            }
        }
    ]
}

• payment_method_code: "17" indica que o pagamento foi feito via PIX – Código tabela oficial SEFAZ.
• payment_indicator: "0" indica que foi à vista – Código tabela oficial SEFAZ.
• O objeto card_details contém os dados para validação da transação:
  • integration_type: "1" (integrado)
  • acquirer_cnpj: CNPJ da instituição que processou o PIX.
  • authorization_code: ID de transação do PIX.

2. NuPay

Neste caso, o NuPay é tratado como um tipo de pagamento "Outros" que exige validação.

{
    "payment_details": [
        {
            "payment_method_code": "99",
            "payment_amount": 99.50,
            "payment_indicator": "0"
        }
    ]
}

• payment_method_code: "99" indica que a forma de pagamento não se encaixa nas categorias padronizadas.
• payment_indicator: "0" indica que o pagamento foi à vista.
• O objeto card_details não é enviado, pois a forma como a transação NuPay é processada não exige essas informações adicionais para o XML da NFe.

3. Boleto

Para o boleto, o card_details não é necessário, pois a transação não é considerada um pagamento eletrônico imediato sob a ótica da NT 2025.001.

{
    "payment_details": [
        {
            "payment_method_code": "15",
            "payment_amount": 1076.40,
            "payment_indicator": "0"
        }
    ]
}

• payment_method_code: "15" indica que o pagamento foi via boleto.
• payment_indicator: "0" indica pagamento à vista.
• Não há informações adicionais, pois a legislação não exige dados de transação eletrônica para boletos.

4. Cartão

Para pagamentos com cartão, todos os detalhes da transação são fornecidos para que o mapeamento para a NFe seja completo.

{
    "payment_details": [
        {
            "payment_method_code": "03",
            "payment_amount": 1076.40,
            "payment_indicator": "1",
            "card_details": {
                "integration_type": "1",
                "acquirer_cnpj": "01234567000189",
                "card_brand_code": "02",
                "authorization_code": "987654321"
            }
        }
    ]
}

• payment_method_code: "03" indica que o pagamento foi com cartão de crédito.
• payment_indicator: "1" indica que o pagamento foi a prazo (parcelado).
• O objeto card_details fornece todos os dados necessários: o integration_type (1), o acquirer_cnpj, o card_brand_code (02 para Mastercard) e o authorization_code.

Etapa 4.3 - OR31 (Parte I)

4.3 | OR31 - Atualizar campos personalizados dos pedidos

Essa API permite atualizar valores em campos que foram criados sob medida pelo KaBuM! dentro da plataforma Mirakl. Esses campos são chamados de Custom Fields e servem para armazenar informações que o padrão global da Mirakl não prevê, facilitando a leitura pelas nossas automações.

No KaBuM!, mesmo enviando o XML via OR74, os dados de nota fiscal e recebimento são campos adicionais. A OR31 escreve esses dados no "corpo" do pedido para permitir buscas rápidas, automações logísticas e validações de segurança.

📌 Parâmetros da API

• Parâmetro de Path (Obrigatório):
  order_id (String): O ID do pedido (ex: 123-A).
• Parâmetro de Body (Obrigatório - JSON):
  order_custom_fields (Array): Lista de objetos contendo code (ID do campo) e value (conteúdo).

Corpo de requisição

Para atualizar os campos de nota fiscal, utilize os seguintes Additional Fields no payload:

• emission-date-nfe (Texto): Data de emissão (Ex: 15/11/2020).
• number-nfe (Texto): Número da nota.
• serial-number-nfe (Texto): Série da nota.
• nfe-key (Texto): Chave de acesso da NFe.

{
  "order_custom_fields": [
    {
      "code": "chave-nfe",
      "value": "35231000123456000188550010000001231234567890"
    },
    {
      "code": "serie-nfe",
      "value": "001"
    }
  ]
}

⏳ Linha do Tempo da Integração

1. Gatilho (ERP): Nota Fiscal autorizada pela SEFAZ seguindo a NT2025.001. O ERP já possui Chave, Série e Número.
2. Preparação: O sistema mapeia os códigos de campos exigidos pelo KaBuM!.
3. Execução: Chamada PUT /api/orders/{order_id}/custom_fields.
   Nota: Utilize o método PUT, pois estamos alterando um recurso existente.
4. Resposta: 204 No Content indica sucesso.
5. Próximo passo: Prosseguir para o upload do arquivo físico na OR74.

🚩 Lista de Falhas e Desafios Comuns na OR31

Etapa 4.4 - OR74

4.4 | OR74 - Upload de Documentos do Pedido (Anexo de NF-e)

Esta API permite o upload de arquivos binários vinculados a um pedido específico. No cenário brasileiro, ela é utilizada quase exclusivamente para o envio do XML da NF-e (item obrigatório para a saúde da integração).

📌 Parâmetros da API

• Parâmetro de Path (Obrigatório):
  order_id (String): O ID do pedido Mirakl (ex: 123-A).
• Parâmetros de Query (Obrigatórios):
  type (String): Define a natureza do arquivo. Para faturamento, utilize obrigatoriamente INVOICE.
  shop_id (Integer): O identificador da sua loja.
• Parâmetro de Body (Obrigatório - Multipart):
  files (Binary): O arquivo propriamente dito.
  Formatos aceitos: csv, doc, xls, xlsx, ppt, pdf, odt, ods, odp, txt, rtf, png, jpg, gif, zpl, mov, mp4.

🚩 Lista de Falhas e Desafios Comuns na OR74

⏳ Linha do Tempo da Integração

1. Gatilho (Sucesso na OR31): A integração confirmou o envio dos dados de texto (chave/série) via OR31.
2. Preparação do Buffer: O sistema lê o arquivo XML/PDF e o prepara em um stream de dados (evite carregar arquivos gigantes inteiros na memória RAM).
3. Execução: Chamada POST /api/orders/{order_id}/documents?type=INVOICE.
4. Resposta: 204 No Content. A Mirakl associou o documento ao pedido com sucesso.
5. Próximo Passo: Com a NF-e vinculada, o status do pedido permite informar o rastreio (OR23) e o despacho (OR24).

💡 Lógica de Implementação Recomendada

• Content-Type específico: No header do multipart, informe o tipo correto:
  • Para XML: application/xml
  • Para PDF: application/pdf
• Resiliência (Gargalo): Uploads consomem mais recursos. Implemente uma Queue (Fila). Se o upload falhar por oscilação de rede, o robô deve tentar novamente até receber o status 204.
• UX do Cliente: Se você enviar ambos (XML e PDF) com type=INVOICE, a Mirakl agrupa-os. Isso é ideal para o KaBuM!, pois o cliente baixa o DANFE para conferir e o XML para fins fiscais.

Etapa 5.1 - SH21

5.1 | SH21 - Listagem de Transportadoras (Carriers)

Antes do envio das informações de rastreio e da alteração do status para "Enviado", é necessário mapear as transportadoras cadastradas na Mirakl. Esta API retorna a lista completa de todas as operadoras logísticas homologadas pelo KaBuM!, fornecendo o code (ID técnico) e o label (nome amigável).

Exemplo de Resposta (JSON):

{
  "carriers": [
    {
      "code": "CORREIOS_SEDEX",
      "label": "Correios - SEDEX"
    },
    {
      "code": "LOGGI",
      "label": "Loggi Tecnologia"
    }
  ]
}

O valor do campo code deve ser utilizado obrigatoriamente no campo carrier_code da API OR23.

🚩 Lista de Falhas e Desafios Comuns na SH21

⏳ Linha do Tempo: O Mapeamento (De/Para)

Esta API faz parte do Setup e da Manutenção Periódica; não deve ser chamada a cada pedido.

1. Gatilho (Setup): O desenvolvedor cria uma tabela no banco de dados chamada Mapeamento_Transportadoras.
2. Ação: O sistema consome a SH21 e popula essa tabela com os códigos da Mirakl.
3. Intervenção do Seller: No painel do ERP, o Seller associa: "Meu 'SEDEX' interno corresponde ao 'CORREIOS_SEDEX' na Mirakl".
4. Uso Operacional: No despacho, o ERP consulta essa tabela para enviar o código correto na OR23.
5. Manutenção: Recomenda-se rodar a SH21 uma vez por semana para capturar novas homologações.

💡 Mapeamento Inteligente

Transportadora de Contingência (Fallback):

Se o Seller usar frete próprio ou uma transportadora local que não consta na lista, é permitido o envio do campo vazio. Entretanto, o ideal é solicitar a homologação dessa nova transportadora ao marketplace para garantir a melhor experiência ao cliente.

Etapa 5.2 - OR23

5.2 | OR23 - Informar Dados de Rastreio (Tracking) para um Pedido

Nesta etapa, utilizaremos a API OR23 para vincular as informações logísticas (transportadora, número de rastreio e URL) ao pedido. Diferente de outras plataformas, na Mirakl a OR23 não altera o status do pedido para "Enviado"; ela apenas anexa os dados necessários para que a OR24 possa ser executada com sucesso.

📌 Parâmetros da API (JSON)

• Parâmetro de Path (Obrigatório):
  order_id (String): O ID do pedido Mirakl (ex: 123-A).
• Parâmetros de Body (Obrigatórios):
  carrier_code (String): O código técnico da transportadora obtido na SH21.
  tracking_number (String): O código de rastreio fornecido pela transportadora.
• Parâmetro de Body (Opcional / Recomendado):
  tracking_url (String): Link direto para a página de rastreio.
  Nota: No KaBuM!, este campo só é obrigatório se o carrier_code for enviado vazio. Se informar o código, a Mirakl tenta gerar a URL automaticamente.

Exemplo de Payload:

{
  "carrier_code": "CORREIOS_SEDEX",
  "tracking_number": "OI123456789BR",
  "tracking_url": "https://rastreamento.correios.com.br/app/index.php?codigo=OI123456789BR"
}

🚩 Lista de Falhas e Desafios Comuns na OR23

💡 Lógica de Implementação para o Desenvolvedor

• Validação de Duplicidade: Implemente um alerta no ERP para que, caso a OR23 retorne erro de duplicidade, o expedidor seja notificado imediatamente para trocar a etiqueta.
• Montagem de URL Dinâmica: Se a transportadora não fornece a URL, mas tem um padrão fixo, seu código deve concatenar a string automaticamente (ex: site.com/rastreio?id=[NUMERO]).
• Sequência de Segurança: Nunca dispare a OR24 sem confirmar o status 204 da OR23. Ignorar esse erro deixará o pedido "preso" no status de pendente no Marketplace.

⏳ Linha do Tempo: O Vínculo Logístico

1. Gatilho (ERP): Nota Fiscal enviada (OR74) e pacote etiquetado com código de rastreio gerado.
2. Consulta ao Mapeamento: O ERP busca o carrier_code correspondente à transportadora (ex: "Loggi" → LOGGI).
3. Execução: Chamada PUT /api/orders/{order_id}/tracking.
4. Resposta: 204 No Content. Dados validados e anexados.
5. Próximo Passo: Chamar imediatamente a OR24 para mudar o status para SHIPPED.

Etapa 5.3 - OR24

5.3 | OR24 - Validar/Atualizar o Status do Envio de um Pedido

A requisição deste endpoint altera o status do pedido de SHIPPING (Aguardando Envio) para SHIPPED (Enviado). Este é o gatilho oficial que dispara o e-mail de confirmação para o cliente final e atualiza o dashboard do KaBuM!.

Diferentemente da OR23, que apenas anexa dados, a OR24 é uma API de mudança de estado. A plataforma Mirakl valida se todos os pré-requisitos — como o rastreio informado na OR23 e a nota fiscal enviada na OR74 — foram cumpridos. Caso algum dado esteja ausente, o pedido não altera seu status e continua contabilizando atraso no SLA do Seller.

📌 Parâmetros da API

• Parâmetro de Path (Obrigatório):
  order_id (String): O ID do pedido Mirakl (ex: 123-A).
• Observação Técnica: Geralmente, esta API não exige um corpo (body) em formato JSON, pois atua estritamente como um gatilho de status. O método utilizado é o PUT.

🚩 Lista de Falhas e Desafios Comuns na OR24

⏳ Linha do Tempo: O Ponto de Não Retorno

1. Gatilho (Sucesso na OR23): O sistema confirmou que o código de rastreio foi aceito sem erros de duplicidade.
2. Verificação Final: O ERP checa se o pacote já foi fisicamente bipado/coletado pela transportadora.
3. Execução: Chamada PUT /api/orders/{order_id}/ship.
4. Resposta: 204 No Content.
5. O que isso significa? O pedido agora é oficialmente considerado "Em Trânsito".
6. Próximo Passo: O fluxo de expedição termina aqui. O sistema deve agora monitorar mensagens de pós-venda (M11) ou possíveis incidentes.

Etapa 5.4 - OR31 (Parte II)

5.4 | OR31 - Confirmação de Recebimento (Received = true)

Esta é uma das etapas mais importantes para o fechamento do fluxo de produtos e pedidos. No KaBuM!, o status de "Recebido" via OR31 funciona como o gatilho final que confirma ao sistema que o consumidor está com o produto em mãos, impactando diretamente no repasse financeiro e na reputação do Seller.

Ao alterar o valor de false para true, a integradora comunica oficialmente ao marketplace que a transportadora concluiu a entrega. Embora o pedido já esteja como SHIPPED, o marketplace depende desse input para encerrar o ciclo operacional.

📌 Parâmetros da API

• Parâmetro de Path (Obrigatório):
  order_id (String): O ID do pedido Mirakl (ex: 123-A).
• Parâmetro de Body (JSON):
  order_additional_fields (Array): Lista contendo os campos de recebimento e a data de entrega.

Exemplo de Payload de Recebimento:

{
  "order_additional_fields": [
    {
      "code": "received",
      "type": "BOOLEAN",
      "value": "true"
    },
    {
      "code": "dt-ent",
      "type": "DATE",
      "value": "2023-10-27T10:00:00Z"
    }
  ]
}

⏳ Linha do Tempo: A Entrega Final

1. Gatilho (Transportadora): O sistema de rastreio (webhook ou leitura de arquivos NOTFIS) confirma a entrega ao destinatário.
2. Preparação: O ERP identifica o pedido e monta o payload definindo received: true e a data em dt-ent.
3. Execução: Chamada PUT /api/orders/{order_id}/custom_fields.
4. Resposta: 204 No Content.
5. Próximo Passo: O pedido move-se automaticamente para RECEIVED ou CLOSED no ecossistema Mirakl.

🚩 Lista de Falhas e Desafios Comuns