Asynchronous Responses and Transaction Tracking¶

Overview¶

Asynchronous responses are used in our system to handle time-consuming operations without blocking immediate feedback for the user. When a request triggers a process that cannot be completed instantly, the system returns a transaction_id instead of a final result. This approach allows your system to continue other tasks while the requested operation is being processed in the background.

Using the transaction ID, you can track the status of the request, allowing you to check whether the operation has completed, is still in progress, or encountered an error.

Asynchronous Response Payload¶

When an operation is processed asynchronously, the initial response includes:

transaction_id: A unique identifier for tracking the transaction status.
links: A list containing the endpoint to retrieve the transaction status.

Example of an Async Response:

{
  "transaction_id": "2d97892b-50f2-4e0e-8967-3d962c29ade9",
  "links": [
    {
      "path": "/seller/v0/transactions/2d97892b-50f2-4e0e-8967-3d962c29ade9"
    }
  ]
}

Tracking a Transaction’s Status¶

To monitor the progress of an asynchronous operation, there are two primary methods: 1. Listening for Webhook Updates [Recommended]: Configure a webhook to receive transaction updates, so you are checking a transaction only when it changes. 2. Polling the Transaction Endpoint: Use the transaction_id from the initial response to make a GET request to the specified transaction endpoint.

The transaction’s details include information on its current status, associated events, and additional identifiers for the operation.

When is a Transaction Finished?¶

The transaction status provides insight into the operation’s progress. The status field in the transaction payload will indicate whether the transaction is in progress, completed, or failed. Key statuses include: - pending: The operation is in a queue awaiting processing.
- processing: The operation is actively being executed.
- completed: The operation has finished successfully. This signals that the requested action was completed as expected.
- failed: An error occurred, and the operation could not complete successfully.
- cancelled: The operation was intentionally stopped before completion.

Once the status field shows completed or failed, the transaction has concluded, and no further status updates will occur.

How can I get the result of my initial requisition?¶

Alongside every status update in a transaction there always is a equivalent event created in the transaction. So in order to get details about the status of your transaction the only thing you need to do is to get it's latest event.

Completed transaction that relate to the creation of objects will return the created object id in their payload

Example of a Completed Transaction:

{
  "created_at": "2024-11-08T11:49:35.938000",
  "updated_at": "2024-11-08T11:49:35.938000",
  "id": "5d3ca96b-cdab-4770-8f8a-1afc66a24274",
  "code": "5D3CA96B",
  "operation": "create",
  "trigger_endpoint": "channel/v0/tickets",
  "status": "completed",
  "events": [
    {
      "event": "transition",
      "message": "Criação de ticket bem sucedida",
      "data": {
        "ticket_id": "8f6a64a6-0b9e-5c1c-8242-34828585f0dc"
      },
      "status": "completed",
      "created_at": "2024-11-08T11:49:52.489000"
    }
  ],
}

Failed transaction will also carry their error message in an event. Example of a Failed Transaction:

{
  "created_at": "2024-11-08T11:49:35.938000",
  "updated_at": "2024-11-08T11:49:35.938000",
  "id": "5d3ca96b-cdab-4770-8f8a-1afc66a24274",
  "code": "5D3CA96B",
  "operation": "create",
  "trigger_endpoint": "channel/v0/tickets",
  "status": "failed",
  "events": [
    {
      "event": "failure",
      "message": "Falha na criação de ticket",
      "data": {
        "error_message": "[{\"error_code\": \"UNPROCESSABLE_ENTITY\", \"message\": \"The request is semantically incorrect or fails business validation\", \"details\": [{\"issue\": \"INVALID_PARAMETER_VALUE\", \"description\": \"Field value is invalid\", \"location\": \"body\", \"field\": \"type_code\", \"value\": \"mktplace-entrega\"}]}]"
      },
      "status": "failed",
      "created_at": "2024-11-07T19:42:25.898000"
    }
  ],
}