Pular para o conteúdo principal

Callbacks

O ANYMARKET possuí um robusto sistema de notificações, avisando aos sistemas integradores das principais alterações ocorridas na aplicação. Abaixo temos os principais detalhes que precisam ser entendidos para o desenvolvimento de uma boa integração.

Fluxo​

  • As callbacks podem ser configuradas via tela ou através de chamadas na API.
  • Principais etapas do fluxo:
    • Validação da configuração: sempre que uma alteração relevante ocorrer em um dos domínios que possuem notificação, validaremos se a conta integrada possui configuração para receber este tipo de notificação. Caso não possua, a notificação é imediatamente descartada;
    • Validação da blocklist: pode ocorrer de URLs serem inseridas em uma blocklist, fazendo com que qualquer notificação para ela seja imadiatamente descartada;
    • Enfileiramento e envio: o ANY trabalha com um sistema de filas, enfileirando as notificações criadas para serem enviadas conforme disponibilidade sistêmica. Em momentos de alto volume, as notificações podem demorar mais para serem enviadas;
    • Recebimento e tratamento de erro: sempre que uma notificação é enviada para uma callback cadastrada, o recebedor precisa responder com um status code condizente com o ocorrido:
      • No caso de sucesso, devolver um status code na faixa 2xx;
      • No caso de erros de autenticação, devolver um status code como 401, 403 ou 407;
      • Demais erros podem ser devolvidos nas faixas 4xx ou 5xx, conforme necessidade.
    • Retentativa de envio: após falha no envio, o ANY tentará fazer o reenvio da notificação por até 6 (seis) vezes, aumentando exponencialmente o intervalo entre as tentativas.
    • Erro no envio: caso após nenhuma das tentativas forem entregues com sucesso, o ANY interromperá o envio da notificação;
      • Caso o tipo de notificação esteja com a contingência por feed habilitada, criaremos um registro no FEED para que o sistema integrador possa fazer a leitura desta notificação;
      • Caso não haja configuração de contingência, a notificação será descartada.

Cenários alternativos​

Como fonte de conhecimento, abaixo estão alguns cenários que podem ocorrer no dia a dia, mas principalmente em momentos de pico e alta demanda.

  • Renotificação: o ANYMARKET pode enviar duas vezes a mesma notificação, para o mesmo vento, mais de um vez em cenários específicos. Aplicamos regras para tentar minimizar estas ocorrências, porém, o cliente integrador precisa garantir a unicidade de um pedido através do ID do pedido. Geralmente, os seguintes cenários podem ocorrer:
    • Situações de Instabilidade: caso ocorram falhas em serviços externos ou durante manutenções programadas no ANYMARKET;
    • Atualização de Dados pelo Marketplace: se o canal de venda nos enviar uma alteração nos dados do pedido (mesmo que o status seja o mesmo), nós avisaremos você;
    • Correção de Erros na Fonte: quando o próprio marketplace nos reenvia uma notificação para corrigir uma informação;
    • Ação manual do usuario na tela de pedido: quando o usuário seleciona o pedido na tela do ANY e aciona a funcionalidade "Sincronizar com: Erp/Plataforma".
  • Orndenação: Como sistema de notificação trabalha com filas, pode ser que as mensagens sejam enviadas fora de ordem. Ou seja, o status atual de um pedido (por exemplo) deve ser considerado através do PUT realizado, e não do status notificado.

Tipos de notificação​

Se a Callback estiver cadastrada corretamente e a URL de retorno funcionar, informaremos a sua aplicação quando ocorrer os seguintes eventos no ANYMARKET:

Pedido​

Quando houver inclusão de um novo pedido, alteração de status ou mudança em informações da venda.

O campo "event" representa o status em que o pedido se encontrava no momento da notificação.

{
  "type": "ORDER",
  "event": "PAID_WAITING_SHIP",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo da callback (será sempre ORDER nesse caso);
  • event – Evento que disparou a callback, pode ser:
    • PENDING - Pedido pendente de pagamento;
    • PAID_WAITING_SHIP - Pedido pago;
    • INVOICED - Pedido faturado;
    • PAID_WAITING_DELIVERY - Pedido enviado;
    • CONCLUDED - Pedido entregue;
    • CANCELED - Pedido cancelado;
  • content.id – ID do Pedido;
  • content.oi – OI do Seller;
  • content.metadata - Informações adicionais que podem ser enviadas junto a notificação.

Caso o parâmetro "contingência por feed" estiver habilitado e não conseguirmos notificar a URL cadastrada, a notificação também será criada no sistema de FEEDs.

Pergunta​

Quando houver uma alteração/inclusão de perguntas.

{
  "type": "QUESTION",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo da callback (será sempre QUESTION nesse caso);
  • event – Evento que disparou a callback, pode ser:
    • CREATE - Criação da pergunta;
    • UPDATE - Atualização da pergunta;
    • DELETE - Exclusão da pergunta;
  • content.id – ID da Pergunta;
  • content.oi – OI do Seller;
  • content.metadata - Informações adicionais que podem ser enviadas junto a notificação.

Produto​

Quando houver uma inclusão, alteração ou remoção de produto, independente de existir um anúncio ativo.

{
  "type": "PRODUCT",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo da callback (será sempre PRODUCT nesse caso);
  • event – Evento que disparou a callback, pode ser:
    • CREATE - Criação de produto;
    • UPDATE - Atualização de produto;
    • DELETE - Exclusão de produto;
  • content.id – ID do Produto;
  • content.oi – OI do Seller;
  • content.metadata - Informações adicionais que podem ser enviadas junto a notificação.

Transmissão​

Quando houver uma inclusão, alteração ou remoção de SKU. As transmissões só são notificadas caso o SKU possua publicação ativa.

{
  "type": "TRANSMISSION",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo da callback (será sempre TRANSMISSION nesse caso);
  • event – Evento que disparou a callback, pode ser:
    • CREATE - Criação de anúncio;
    • UPDATE - Atualização de anúncio;
    • DELETE - Exclusão de anúncio;
  • content.id – ID do SKU;
  • content.oi – OI do Seller;
  • content.metadata - Informações adicionais que podem ser enviadas junto a notificação.

Caso o parâmetro "contingência por feed" estiver habilitado e não conseguirmos notificar a URL cadastrada, a notificação também será criada no sistema de FEEDs.

NFe de Remessa​

Quando houver uma inclusão, alteração ou remoção de nota fiscal de remessa.

{
  "type": "INBOUND_NFE",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo da callback (será sempre INBOUND_NFE nesse caso);
  • event – Evento que disparou a callback, pode ser:
    • CREATE - Criação da NFe;
    • UPDATE - Atualização da NFe;
    • DELETE - Exclusão da NFe;
  • content.id – ID do NFe de Remessa;
  • content.oi – OI do Seller;
  • content.metadata - Informações adicionais que podem ser enviadas junto a notificação.

Documentos fiscais​

Quando houver uma inclusão ou alteração de um documento fiscal.

{
  "type": "FISCAL_DOCUMENTS",
  "event": "UPDATE",
  "content": {
    "id": "1",
    "oi": "47.",
    "metadata": {
      "documentTypeValue": "symbolic_inbound_return",
      "marketplace": "MERCADO_LIVRE",
      "type": "NFE"
    }
  }
}
  • type – Tipo da callback (será sempre FISCAL_DOCUMENTS nesse caso);
  • event – Evento que disparou a callback, pode ser:
    • CREATE - Criação de documentos fiscais;
    • UPDATE - Atualização de documentos fiscais;
  • content.id – ID do documento fiscal;
  • content.oi – OI do Seller;
  • content.metadata - Informações adicionais que podem ser enviadas junto a notificação. No exemplo acima:
    • subType - Será o tipo de operação para notas fiscais brasileiras
    • marketplace - Canal que emitiu o documento fiscal
    • type - Modelo do documento (ex: NFE, CTE)

Reserva de Estoque​

Quando houver uma criação/remoção de reserva de estoque.

{
  "type": "STOCK_RESERVATION",
  "event": "CREATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo da callback (será sempre STOCK_RESERVATION nesse caso);
  • event – Evento que disparou a callback, pode ser:
    • CREATE - Criação da reserva;
    • DELETE - Exclusão de reserva;
  • content.id – ID da Reserva de Estoque;
  • content.oi – OI do Seller;
  • content.metadata - Informações adicionais que podem ser enviadas junto a notificação.

Caso o parâmetro "contingência por feed" estiver habilitado e não conseguirmos notificar a URL cadastrada, a notificação também será criada no sistema de FEEDs.

Risco de Cancelamento​

O recurso Risco de Cancelamento foi projeto para auxiliar os vendedores na identificação de pedidos com risco de cancelamento pelo comprador. Esses pedidos são destacados por meio de alertas acessíveis no menu Vendas > Risco de Cancelamento.

{
  "type": "CANCELLATION_RISK_ALERT",
  "event": "TRACK_DELAY",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo da callback (será sempre CANCELLATION_RISK_ALERT nesse caso);
  • event – Evento que disparou a callback, pode ser:
    • TRACK_DELAY - Atraso de esteira;
    • DELIVERY_DELAY - Atraso de entrega;
    • DUPLICATE_PURCHASE - Compra duplicada;
    • SKU_BLOCK - Bloqueio por SKU;
    • OPEN_SAC - Sac aberto;
    • ORDER_NOT_DELIVERED - Pedido não entregue;
    • TRACK_BLOCK - Bloqueio de esteira;
  • content.id – ID do Pedido;
  • content.oi – OI do Seller;
  • content.metadata - Informações adicionais que podem ser enviadas junto a notificação.

Devolução de venda​

Quando houver uma criação de uma devolução de venda.

{
  "type": "ORDER_RETURN",
  "event": "CREATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo da callback (será sempre ORDER_RETURN nesse caso);
  • event – Evento que disparou a callback, pode ser:
    • CREATE - Criação da Devolução;
  • content.id – ID do Pedido;
  • content.oi – OI do Seller;
  • content.metadata - Informações adicionais que podem ser enviadas junto a notificação.

Caso o parâmetro "contingência por feed" estiver habilitado e não conseguirmos notificar a URL cadastrada, a notificação também será criada no sistema de FEEDs.

Monitoramento de Erros​

Quando ocorrer a criação de um Monitoring.

{
  "type":"MONITORING",
  "event":"CREATION",
  "content":{
    "id":"10",
    "oi":"145893126.",
    "metadata":{
        "id":12345,
        "partner_id":"MKP00000000000000",
        "origin":"Preço",
        "type":"ALERT",
        "status":"PENDING",
        "date":"2000-12-31T23:59:59.000Z",
        "message":"O anúncio MKP00000000000000 não teve seus dados atualizados pois ultrapassou o limite de segurança estabelecido",
        "details":"O Código SKU no Marketplace MKP00000000000000, Código no Marketplace MKP00000000000000, Marketplace MARKETPLACE, Conta 0000, Preço atual 100.00, Preço novo 150.00 não foi atualizado e Limite 50. É necessário rever o novo preço ou o limite de segurança",
        "isRetrying":false
      }
   }
}
  • type – Tipo da callback (será sempre MONITORING nesse caso);
  • event – Evento que disparou a callback, pode ser:
    • CREATE - Criação do Monitoring;
  • content.id – ID do Monitoring;
  • content.oi – OI do Seller;
  • content.metadata - Informações relacionadas ao Monitoring, como descrição, status e informações de identificação.