Ir para o conteúdo

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:

  1. 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.
  2. Polling do Endpoint de Transação: Use o <transaction_id> da resposta inicial para fazer uma requisição GET 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.