Respostas Assíncronas e Acompanhamento de Transações¶
Visão Geral¶
Respostas assíncronas permitem que nosso sistema gerencie operações demoradas sem bloquear o retorno imediato para os usuários. Quando uma solicitação aciona um processo que não pode ser concluído instantaneamente, o sistema retorna um <transaction_id>
em vez de um resultado final. Isso permite que seu sistema continue outras tarefas enquanto monitora o status da operação em segundo plano.
Utilizando o <transaction_id>
, é possível acompanhar o status da solicitação, verificando se a operação foi concluída, ainda está em andamento ou encontrou um erro.
Estrutura da Resposta Assíncrona¶
Quando uma operação é tratada de forma assíncrona, a resposta inicial inclui:
- transaction_id: Um identificador exclusivo para acompanhar o status da transação.
- links: Uma lista com o endpoint para recuperar o status da transação.
Exemplo de Resposta Assíncrona:
{
"transaction_id": "2d97892b-50f2-4e0e-8967-3d962c29ade9",
"links": [
{
"path": "/seller/v0/transactions/2d97892b-50f2-4e0e-8967-3d962c29ade9"
}
]
}
Acompanhamento do Status de uma Transação¶
Há duas maneiras principais de monitorar o progresso de uma operação assíncrona:
- Escuta para Atualizações de Webhook [Recomendado]: Configure um webhook para receber atualizações de transação, evitando a necessidade de polling constante ao verificar a transação apenas quando seu status mudar.
- Polling do Endpoint de Transação: Use o
<transaction_id>
da resposta inicial para fazer uma requisiçãoGET
ao endpoint de transação especificado.
Os detalhes da transação incluem informações sobre seu status atual, eventos associados e identificadores adicionais para a operação.
Entendendo o Status de uma Transação¶
O status da transação indica o progresso da operação. Principais status incluem:
- pending: A operação está em uma fila aguardando processamento.
- processing: A operação está sendo executada ativamente.
- completed: A operação foi concluída com sucesso.
- failed: Um erro impediu a conclusão bem-sucedida.
- cancelled: A operação foi interrompida antes da conclusão.
Uma vez que o campo status
exibe completed
, failed
ou cancelled
, a transação está em um estado terminal, e nenhuma atualização adicional ocorrerá.
Como Obter o Resultado da Solicitação Inicial¶
Cada atualização de status é associada a um evento no array events da transação. Para obter as informações mais recentes sobre sua transação, consulte seu evento mais recente.
Para transações concluídas relacionadas à criação de um recurso, o evento final incluirá o ID do objeto criado em seu payload.
Exemplo de Transação Concluída:¶
{
"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"
}
],
}
Exemplo de Transação com Falha:¶
Se a transação falhar, uma mensagem de erro será incluída em um evento:
{
"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"
}
],
}
Em ambos os casos, o evento mais recente no array events
contém o resultado da operação, detalhando se ela foi bem-sucedida ou falhou e qualquer informação relevante.