Saltar al contenido principal

Callbacks

ANYMARKET posee un robusto sistema de notificaciones que avisa a los sistemas integradores sobre los principales cambios ocurridos en la aplicación. A continuación se presentan los principales detalles que deben comprenderse para el desarrollo de una buena integración.

Flujo​

  • Las callbacks pueden configurarse a través de la pantalla o mediante llamadas a la API.
  • Principales etapas del flujo:
    • Validación de la configuración: siempre que ocurra un cambio relevante en uno de los dominios que tienen notificación, se validará si la cuenta integrada tiene configuración para recibir este tipo de notificación. Si no la tiene, la notificación se descarta de inmediato;
    • Validación de la blocklist: puede ocurrir que URLs sean insertadas en una blocklist, haciendo que cualquier notificación hacia ellas sea descartada de inmediato;
    • Encolado y envío: ANYMARKET trabaja con un sistema de colas, encolando las notificaciones creadas para ser enviadas según la disponibilidad del sistema. En momentos de alto volumen, las notificaciones pueden tardar más en ser enviadas;
    • Recepción y manejo de errores: siempre que se envía una notificación a una callback registrada, el receptor debe responder con un status code acorde a lo ocurrido:
      • En caso de éxito, devolver un status code en el rango 2xx;
      • En caso de errores de autenticación, devolver un status code como 401, 403 o 407;
      • Los demás errores pueden devolverse en los rangos 4xx o 5xx, según corresponda.
    • Reintento de envío: tras un fallo en el envío, ANYMARKET intentará reenviar la notificación hasta 6 (seis) veces, aumentando exponencialmente el intervalo entre los intentos.
    • Error en el envío: si después de todos los intentos ninguno resulta exitoso, ANYMARKET interrumpirá el envío de la notificación;
      • Si el tipo de notificación tiene habilitada la contingencia por feed, se creará un registro en el FEED para que el sistema integrador pueda leer esa notificación;
      • Si no hay configuración de contingencia, la notificación será descartada.

Escenarios alternativos​

Como fuente de conocimiento, a continuación se presentan algunos escenarios que pueden ocurrir en el día a día, principalmente en momentos de pico y alta demanda.

  • Renotificación: ANYMARKET puede enviar dos veces la misma notificación, para el mismo evento, más de una vez en escenarios específicos. Se aplican reglas para intentar minimizar estas ocurrencias; sin embargo, el cliente integrador debe garantizar la unicidad de un pedido a través del ID del pedido. En general, pueden ocurrir los siguientes escenarios:
    • Situaciones de inestabilidad: si ocurren fallos en servicios externos o durante mantenimientos programados en ANYMARKET;
    • Actualización de datos por el marketplace: si el canal de venta nos envía una modificación en los datos del pedido (aunque el estado sea el mismo), le notificaremos;
    • Corrección de errores en la fuente: cuando el propio marketplace nos reenvía una notificación para corregir una información;
    • Acción manual del usuario en la pantalla de pedido: cuando el usuario selecciona el pedido en la pantalla de ANYMARKET y activa la funcionalidad "Sincronizar con: Erp/Plataforma".
  • Ordenamiento: como el sistema de notificación trabaja con colas, es posible que los mensajes se envíen fuera de orden. Es decir, el estado actual de un pedido (por ejemplo) debe considerarse a través del PUT realizado, y no del estado notificado.

Tipos de notificación​

Si la Callback está registrada correctamente y la URL de retorno funciona, se informará a su aplicación cuando ocurran los siguientes eventos en ANYMARKET:

Pedido​

Cuando se incluya un nuevo pedido, cambie de estado o se modifiquen informaciones de la venta.

El campo "event" representa el estado en que se encontraba el pedido en el momento de la notificación.

{
  "type": "ORDER",
  "event": "PAID_WAITING_SHIP",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo de callback (siempre será ORDER en este caso);
  • event – Evento que disparó la callback, puede ser:
    • PENDING - Pedido pendiente de pago;
    • PAID_WAITING_SHIP - Pedido pagado;
    • INVOICED - Pedido facturado;
    • PAID_WAITING_DELIVERY - Pedido enviado;
    • CONCLUDED - Pedido entregado;
    • CANCELED - Pedido cancelado;
  • content.id – ID del Pedido;
  • content.oi – OI del Seller;
  • content.metadata - Información adicional que puede enviarse junto a la notificación.

Si el parámetro "contingencia por feed" está habilitado y no se puede notificar la URL registrada, la notificación también se creará en el sistema de FEEDs.

Pregunta​

Cuando haya una modificación/inclusión de preguntas.

{
  "type": "QUESTION",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo de callback (siempre será QUESTION en este caso);
  • event – Evento que disparó la callback, puede ser:
    • CREATE - Creación de la pregunta;
    • UPDATE - Actualización de la pregunta;
    • DELETE - Eliminación de la pregunta;
  • content.id – ID de la Pregunta;
  • content.oi – OI del Seller;
  • content.metadata - Información adicional que puede enviarse junto a la notificación.

Producto​

Cuando haya una inclusión, modificación o eliminación de producto, independientemente de si existe un anuncio activo.

{
  "type": "PRODUCT",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo de callback (siempre será PRODUCT en este caso);
  • event – Evento que disparó la callback, puede ser:
    • CREATE - Creación de producto;
    • UPDATE - Actualización de producto;
    • DELETE - Eliminación de producto;
  • content.id – ID del Producto;
  • content.oi – OI del Seller;
  • content.metadata - Información adicional que puede enviarse junto a la notificación.

Transmisión​

Cuando haya una inclusión, modificación o eliminación de SKU. Las transmisiones solo se notifican si el SKU tiene una publicación activa.

{
  "type": "TRANSMISSION",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo de callback (siempre será TRANSMISSION en este caso);
  • event – Evento que disparó la callback, puede ser:
    • CREATE - Creación de anuncio;
    • UPDATE - Actualización de anuncio;
    • DELETE - Eliminación de anuncio;
  • content.id – ID del SKU;
  • content.oi – OI del Seller;
  • content.metadata - Información adicional que puede enviarse junto a la notificación.

Si el parámetro "contingencia por feed" está habilitado y no se puede notificar la URL registrada, la notificación también se creará en el sistema de FEEDs.

NFe de Remesa​

Cuando haya una inclusión, modificación o eliminación de nota fiscal de remesa.

{
  "type": "INBOUND_NFE",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo de callback (siempre será INBOUND_NFE en este caso);
  • event – Evento que disparó la callback, puede ser:
    • CREATE - Creación de la NFe;
    • UPDATE - Actualización de la NFe;
    • DELETE - Eliminación de la NFe;
  • content.id – ID de la NFe de Remesa;
  • content.oi – OI del Seller;
  • content.metadata - Información adicional que puede enviarse junto a la notificación.

Documentos fiscales​

Cuando haya una inclusión o modificación de un documento fiscal.

{
  "type": "FISCAL_DOCUMENTS",
  "event": "UPDATE",
  "content": {
    "id": "1",
    "oi": "47.",
    "metadata": {
      "documentTypeValue": "symbolic_inbound_return",
      "marketplace": "MERCADO_LIVRE",
      "type": "NFE"
    }
  }
}
  • type – Tipo de callback (siempre será FISCAL_DOCUMENTS en este caso);
  • event – Evento que disparó la callback, puede ser:
    • CREATE - Creación de documentos fiscales;
    • UPDATE - Actualización de documentos fiscales;
  • content.id – ID del documento fiscal;
  • content.oi – OI del Seller;
  • content.metadata - Información adicional que puede enviarse junto a la notificación. En el ejemplo anterior:
    • subType - Será el tipo de operación para notas fiscales brasileñas
    • marketplace - Canal que emitió el documento fiscal
    • type - Modelo del documento (ej: NFE, CTE)

Reserva de Stock​

Cuando haya una creación/eliminación de reserva de stock.

{
  "type": "STOCK_RESERVATION",
  "event": "CREATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo de callback (siempre será STOCK_RESERVATION en este caso);
  • event – Evento que disparó la callback, puede ser:
    • CREATE - Creación de la reserva;
    • DELETE - Eliminación de la reserva;
  • content.id – ID de la Reserva de Stock;
  • content.oi – OI del Seller;
  • content.metadata - Información adicional que puede enviarse junto a la notificación.

Si el parámetro "contingencia por feed" está habilitado y no se puede notificar la URL registrada, la notificación también se creará en el sistema de FEEDs.

Riesgo de Cancelación​

El recurso Riesgo de Cancelación fue diseñado para ayudar a los vendedores en la identificación de pedidos con riesgo de cancelación por parte del comprador. Estos pedidos se destacan mediante alertas accesibles en el menú Ventas > Riesgo de Cancelación.

{
  "type": "CANCELLATION_RISK_ALERT",
  "event": "TRACK_DELAY",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo de callback (siempre será CANCELLATION_RISK_ALERT en este caso);
  • event – Evento que disparó la callback, puede ser:
    • TRACK_DELAY - Retraso de proceso;
    • DELIVERY_DELAY - Retraso de entrega;
    • DUPLICATE_PURCHASE - Compra duplicada;
    • SKU_BLOCK - Bloqueo por SKU;
    • OPEN_SAC - SAC abierto;
    • ORDER_NOT_DELIVERED - Pedido no entregado;
    • TRACK_BLOCK - Bloqueo de proceso;
  • content.id – ID del Pedido;
  • content.oi – OI del Seller;
  • content.metadata - Información adicional que puede enviarse junto a la notificación.

Devolución de venta​

Cuando se cree una devolución de venta.

{
  "type": "ORDER_RETURN",
  "event": "CREATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Tipo de callback (siempre será ORDER_RETURN en este caso);
  • event – Evento que disparó la callback, puede ser:
    • CREATE - Creación de la Devolución;
  • content.id – ID del Pedido;
  • content.oi – OI del Seller;
  • content.metadata - Información adicional que puede enviarse junto a la notificación.

Si el parámetro "contingencia por feed" está habilitado y no se puede notificar la URL registrada, la notificación también se creará en el sistema de FEEDs.

Monitoreo de Errores​

Cuando se cree un 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 de callback (siempre será MONITORING en este caso);
  • event – Evento que disparó la callback, puede ser:
    • CREATE - Creación del Monitoring;
  • content.id – ID del Monitoring;
  • content.oi – OI del Seller;
  • content.metadata - Información relacionada con el Monitoring, como descripción, estado e información de identificación.