Skip to main content

Callbacks

ANYMARKET has a robust notification system that informs integrating systems of the main changes occurring in the application. Below are the key details that need to be understood for developing a good integration.

Flow​

  • Callbacks can be configured via the interface or through API calls.
  • Main flow steps:
    • Configuration validation: whenever a relevant change occurs in one of the domains that have notifications, we will check whether the integrated account has a configuration to receive this type of notification. If it does not, the notification is immediately discarded;
    • Blocklist validation: URLs may be added to a blocklist, causing any notification sent to them to be immediately discarded;
    • Queuing and delivery: ANYMARKET works with a queue system, queuing the created notifications to be sent according to system availability. During high-volume periods, notifications may take longer to be delivered;
    • Receipt and error handling: whenever a notification is sent to a registered callback, the receiver must respond with a status code consistent with what occurred:
      • In case of success, return a status code in the 2xx range;
      • In case of authentication errors, return a status code such as 401, 403, or 407;
      • Other errors may be returned in the 4xx or 5xx ranges, as needed.
    • Retry: after a delivery failure, ANYMARKET will attempt to resend the notification up to 6 (six) times, with an exponentially increasing interval between attempts.
    • Delivery failure: if none of the attempts succeed, ANYMARKET will stop sending the notification;
      • If the notification type has feed-based contingency enabled, a record will be created in the FEED so that the integrating system can read this notification;
      • If there is no contingency configuration, the notification will be discarded.

Alternative scenarios​

As a reference, below are some scenarios that may occur on a day-to-day basis, especially during peak and high-demand periods.

  • Re-notification: ANYMARKET may send the same notification for the same event more than once in specific scenarios. We apply rules to try to minimize these occurrences; however, the integrating client must ensure order uniqueness through the order ID. Generally, the following scenarios may occur:
    • Instability situations: if failures occur in external services or during scheduled maintenance in ANYMARKET;
    • Data update by the marketplace: if the sales channel sends us a change in the order data (even if the status is the same), we will notify you;
    • Error correction at the source: when the marketplace itself resends a notification to correct some information;
    • Manual user action on the order screen: when the user selects the order on the ANYMARKET screen and triggers the "Sync with: ERP/Platform" feature.
  • Ordering: Since the notification system works with queues, messages may be sent out of order. That is, the current status of an order (for example) should be determined through the PUT that was made, not from the notified status.

Notification types​

If the callback is correctly registered and the return URL is working, we will inform your application when the following events occur in ANYMARKET:

Order​

When a new order is added, its status changes, or sale information is updated.

The "event" field represents the status the order was in at the time of the notification.

{
  "type": "ORDER",
  "event": "PAID_WAITING_SHIP",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Callback type (will always be ORDER in this case);
  • event – Event that triggered the callback, can be:
    • PENDING - Order pending payment;
    • PAID_WAITING_SHIP - Order paid;
    • INVOICED - Order invoiced;
    • PAID_WAITING_DELIVERY - Order shipped;
    • CONCLUDED - Order delivered;
    • CANCELED - Order canceled;
  • content.id – Order ID;
  • content.oi – Seller OI;
  • content.metadata - Additional information that may be sent along with the notification.

If the "feed contingency" parameter is enabled and we are unable to notify the registered URL, the notification will also be created in the FEED system.

Question​

When there is a change or addition of questions.

{
  "type": "QUESTION",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Callback type (will always be QUESTION in this case);
  • event – Event that triggered the callback, can be:
    • CREATE - Question created;
    • UPDATE - Question updated;
    • DELETE - Question deleted;
  • content.id – Question ID;
  • content.oi – Seller OI;
  • content.metadata - Additional information that may be sent along with the notification.

Product​

When there is an addition, update, or removal of a product, regardless of whether there is an active listing.

{
  "type": "PRODUCT",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Callback type (will always be PRODUCT in this case);
  • event – Event that triggered the callback, can be:
    • CREATE - Product created;
    • UPDATE - Product updated;
    • DELETE - Product deleted;
  • content.id – Product ID;
  • content.oi – Seller OI;
  • content.metadata - Additional information that may be sent along with the notification.

Transmission​

When there is an addition, update, or removal of a SKU. Transmissions are only notified if the SKU has an active listing.

{
  "type": "TRANSMISSION",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Callback type (will always be TRANSMISSION in this case);
  • event – Event that triggered the callback, can be:
    • CREATE - Listing created;
    • UPDATE - Listing updated;
    • DELETE - Listing deleted;
  • content.id – SKU ID;
  • content.oi – Seller OI;
  • content.metadata - Additional information that may be sent along with the notification.

If the "feed contingency" parameter is enabled and we are unable to notify the registered URL, the notification will also be created in the FEED system.

Inbound NFe​

When there is an addition, update, or removal of an inbound invoice.

{
  "type": "INBOUND_NFE",
  "event": "UPDATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Callback type (will always be INBOUND_NFE in this case);
  • event – Event that triggered the callback, can be:
    • CREATE - NFe created;
    • UPDATE - NFe updated;
    • DELETE - NFe deleted;
  • content.id – Inbound NFe ID;
  • content.oi – Seller OI;
  • content.metadata - Additional information that may be sent along with the notification.

Fiscal documents​

When there is an addition or update of a fiscal document.

{
  "type": "FISCAL_DOCUMENTS",
  "event": "UPDATE",
  "content": {
    "id": "1",
    "oi": "47.",
    "metadata": {
      "documentTypeValue": "symbolic_inbound_return",
      "marketplace": "MERCADO_LIVRE",
      "type": "NFE"
    }
  }
}
  • type – Callback type (will always be FISCAL_DOCUMENTS in this case);
  • event – Event that triggered the callback, can be:
    • CREATE - Fiscal document created;
    • UPDATE - Fiscal document updated;
  • content.id – Fiscal document ID;
  • content.oi – Seller OI;
  • content.metadata - Additional information that may be sent along with the notification. In the example above:
    • subType - Will be the operation type for Brazilian fiscal invoices
    • marketplace - Channel that issued the fiscal document
    • type - Document model (e.g.: NFE, CTE)

Stock Reservation​

When there is a creation or removal of a stock reservation.

{
  "type": "STOCK_RESERVATION",
  "event": "CREATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Callback type (will always be STOCK_RESERVATION in this case);
  • event – Event that triggered the callback, can be:
    • CREATE - Reservation created;
    • DELETE - Reservation deleted;
  • content.id – Stock Reservation ID;
  • content.oi – Seller OI;
  • content.metadata - Additional information that may be sent along with the notification.

If the "feed contingency" parameter is enabled and we are unable to notify the registered URL, the notification will also be created in the FEED system.

Cancellation Risk​

The Cancellation Risk feature was designed to help sellers identify orders at risk of cancellation by the buyer. These orders are highlighted through alerts accessible in the Sales > Cancellation Risk menu.

{
  "type": "CANCELLATION_RISK_ALERT",
  "event": "TRACK_DELAY",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Callback type (will always be CANCELLATION_RISK_ALERT in this case);
  • event – Event that triggered the callback, can be:
    • TRACK_DELAY - Pipeline delay;
    • DELIVERY_DELAY - Delivery delay;
    • DUPLICATE_PURCHASE - Duplicate purchase;
    • SKU_BLOCK - SKU block;
    • OPEN_SAC - Open support ticket;
    • ORDER_NOT_DELIVERED - Order not delivered;
    • TRACK_BLOCK - Pipeline block;
  • content.id – Order ID;
  • content.oi – Seller OI;
  • content.metadata - Additional information that may be sent along with the notification.

Sale return​

When a sale return is created.

{
  "type": "ORDER_RETURN",
  "event": "CREATE",
  "content": {
    "id": "10",
    "oi": "9999.",
    "metadata": ""
  }
}
  • type – Callback type (will always be ORDER_RETURN in this case);
  • event – Event that triggered the callback, can be:
    • CREATE - Return created;
  • content.id – Order ID;
  • content.oi – Seller OI;
  • content.metadata - Additional information that may be sent along with the notification.

If the "feed contingency" parameter is enabled and we are unable to notify the registered URL, the notification will also be created in the FEED system.

Error Monitoring​

When a Monitoring record is created.

{
  "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 – Callback type (will always be MONITORING in this case);
  • event – Event that triggered the callback, can be:
    • CREATE - Monitoring created;
  • content.id – Monitoring ID;
  • content.oi – Seller OI;
  • content.metadata - Information related to the Monitoring, such as description, status, and identification details.