> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salvy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução a tarefas

> Como funcionam as operações em lote da API: a tarefa que acompanha a operação, os resultados de cada item e os webhooks de conclusão

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Acompanhe a tarefa">
    Consulte [Detalhar tarefa](/api-reference/v3/tasks/get) até o `status` deixar de ser `running`, ou receba os webhooks [Tarefa concluída](/api-reference/v3/webhooks/task-succeeded) e [Tarefa concluída com falhas](/api-reference/v3/webhooks/task-failed).
  </Step>

  <Step title="Consulte o resultado de cada item">
    Use [Listar resultados da tarefa](/api-reference/v3/tasks/results), paginado. Filtre por `status=failed` para ver só os itens que não foram aplicados, com o motivo de cada um.
  </Step>
</Steps>

## 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.