Skip to main content
Algumas operações agem sobre muitos itens de uma vez, como aplicar um centro de custo a várias linhas ou sincronizar a base de colaboradores. Elas não terminam durante a requisição: a API aceita o pedido, responde 202 com o ID de uma tarefa e processa os itens em segundo plano.

​
Como funciona

1

Envie a operação em lote

A requisição é validada por inteiro antes de qualquer item ser processado. Se algum item for inválido, a resposta é 422, aponta a posição dele na lista e nada é alterado.
2

Guarde o ID da tarefa

Se a validação passar, a resposta é 202 com o taskId. Repetir a requisição com o mesmo cabeçalho idempotency-key devolve a mesma tarefa, sem processar os itens de novo.
3

Acompanhe a tarefa

Consulte Detalhar tarefa até o status deixar de ser running, ou receba os webhooks Tarefa concluída e Tarefa concluída com falhas.
4

Consulte o resultado de cada item

Use Listar resultados da tarefa, paginado. Filtre por status=failed para ver só os itens que não foram aplicados, com o motivo de cada um.

​
Falhas por item

Depois da validação, cada item é processado de forma independente: um item que falha não desfaz os que já foram aplicados. No resultado, um item com falha traz:
  • reason: o motivo, em português, pronto para mostrar ao seu usuário;
  • retryable: true quando a falha é temporária e vale tentar de novo; false quando o pedido precisa mudar.
Para tentar de novo, envie uma nova operação só com os itens que falharam.

​
Limites

  • Até 1.000 itens por requisição.
  • O corpo da requisição é limitado a 1 MB.

​
Quem pode ler uma tarefa

Uma tarefa pode ser lida por qualquer chave de API da empresa que a iniciou, então trocar a chave não faz você perder o acesso às tarefas em andamento. A leitura exige o escopo task:read.