Skip to main content
A API tem dois endpoints para alterar vários registros em uma única requisição: a atualização em lote e a movimentação em lote entre etapas. Esta página mostra o corpo de cada um, como ler o resultado e como tratar os erros. Os dois endpoints se comportam de formas opostas diante de um erro:
Escolher o endpoint errado muda o que acontece com os dados. Leia as duas seções antes de decidir.

Atualização em lote

A atualização em lote aplica os mesmos valores a todos os registros da lista:

Modelos aceitos

O model_name do caminho aceita dois valores: Qualquer outro valor devolve HTTP 422, com message: "validation_errors" e o motivo em validation.model:
  • Modelo ainda não suportado (por exemplo, contact): messages.model_not_supported_yet.
  • Modelo que não existe: Model was not found.
Para resolver, use project ou answer_pool no caminho. Para alterar vários registros de outro tipo, faça uma requisição por registro.

Corpo da requisição

O corpo é um objeto com a lista de ids e, no mesmo nível, os campos a aplicar em todos eles. Este exemplo marca três projetos como em andamento, com impacto 8, e troca uma etiqueta por outra:
array
required
Lista dos identificadores a atualizar. Não pode estar vazia e não aceita valores repetidos. Não há teto de quantidade.
Como não há teto, um lote muito grande pode passar do tempo limite da requisição. Prefira lotes moderados e acompanhe o resultado.

Campos de project

Os campos simples são aplicados diretamente no projeto: As relações abaixo usam o formato { "to_add": [...], "to_rem": [...] }. Envie as duas chaves, mesmo que uma delas vá vazia: As demais relações têm formato próprio:
Campos desconhecidos são ignorados sem aviso. Um erro de digitação (statsu em vez de status) não gera erro: a requisição responde 200 com todos os itens em successCount e nada é alterado. Confira o resultado relendo um dos registros.

Campos de answer_pool

Com answer_pool, o lote grava as mesmas respostas de formulário em todos os registros da lista. Este exemplo responde o campo 30 do formulário do objeto projeto em dois projetos:
array
required
As respostas a gravar, no mesmo formato usado na gravação individual: cada item tem o id do campo e a answer.
object
required
Endereço do formulário, o pivot. Exige pivot_class, form_id e father_class. A API usa cada item de ids como o registro alvo, então você não envia father_id.
O lote também grava formulários de etapa e de funil. Nesses casos, os ids continuam sendo ids de projeto, e o target leva o id da etapa ou do funil:

Resposta

A resposta tem HTTP 200 mesmo quando alguns itens falham. O resultado do lote está em result:
integer
Quantos itens foram atualizados com sucesso.
integer
Quantos itens falharam.
array
Um objeto por falha, com id e error. Quando a falha é de permissão, o objeto também traz permission, com a permissão que faltou.
A resposta não lista os itens que deram certo. Para saber quais passaram, compare: são os de ids que não aparecem em fails.

Falha no meio de um item

A API processa item a item, mas não desfaz as alterações de um item que falhou. Se um projeto falhar depois de receber parte das alterações, a parte já aplicada permanece. Por exemplo, o campo simples é gravado e a relação seguinte falha.
Um id em fails não significa que nada mudou nesse registro, e sim que a operação não terminou. Releia o registro antes de processá-lo de novo.

Concorrência

A API processa um lote por usuário de cada vez. Se outro lote do mesmo usuário estiver em andamento, a requisição responde com HTTP 409:
A trava vale por usuário e por empresa e só se aplica a lotes com mais de um item. Um lote de um item só nunca recebe 409. Ao receber 409, espere o lote anterior terminar e repita a requisição. Com o mesmo token, envie um lote de cada vez.

Movimentação em lote entre etapas

A movimentação em lote move vários projetos para a mesma etapa de funil:

Corpo da requisição

Este exemplo move dois projetos para a etapa 42 e os desvincula das outras etapas do mesmo funil:
array
required
Lista de IDs (UUID) dos projetos.
integer
required
Etapa de destino.
Quando true, desvincula o projeto das outras etapas do mesmo funil.
Quando true, vincula o projeto ao funil da etapa caso ele ainda não esteja vinculado.
Projetos que já estão na etapa de destino são ignorados, sem erro.

Tudo ou nada

Este endpoint para no primeiro erro, e nenhuma movimentação do lote é confirmada, nem a dos projetos processados antes da falha. A resposta de erro segue o formato padrão e informa o motivo, com o detalhe da restrição ou do requisito que barrou a movimentação. As regras por trás desses erros estão em Restrições de etapa e Requisitos de etapa. O erro descreve o motivo, mas não diz qual projeto falhou. Para descobrir qual projeto barrou o lote, mova um projeto de cada vez com POST /api/management/funnel-steps/{funnel_step_id}/projects. O projeto que reproduzir o erro é o responsável.

Concorrência na movimentação

A movimentação em lote usa a mesma trava da atualização em lote: um lote por usuário de cada vez, com HTTP 409 e bulk_operation_in_progress quando já existe outro em andamento. Um lote de atualização em curso também bloqueia um lote de movimentação do mesmo usuário, e vice-versa.

Boas práticas

Estes cuidados evitam as falhas mais comuns nos lotes:
  • Escolha o endpoint pelo comportamento de erro. Se o lote inteiro precisa dar certo ou falhar junto, use a movimentação entre etapas. Se você quer aplicar o que for possível e tratar o resto depois, use a atualização em lote.
  • Confira o nome dos campos. Na atualização em lote, um campo escrito errado é ignorado sem aviso. Valide o corpo antes de rodar sobre muitos registros.
  • Leia sempre o result. Um successCount igual ao total garante só que nenhum item deu erro, e não que os campos certos foram aplicados.
  • Envie um lote de cada vez. Com o mesmo usuário, o segundo lote recebe 409. Organize uma fila do seu lado.