Atualização em lote
Modelos aceitos
Apenas dois:
Qualquer outro valor devolve 422, com
message: "validation_errors" e o detalhe dentro de validation.model:
- Nome de modelo que existe mas ainda não é suportado (por exemplo
contact):messages.model_not_supported_yet. - Nome de modelo que não existe:
Model was not found.
Corpo da requisição
O corpo é um objeto com a lista deids e, no mesmo nível, os campos a aplicar em todos eles.
array
required
Lista dos identificadores a atualizar. Não pode estar vazia e não aceita valores repetidos. Não há teto de quantidade.
Campos de project
Campos simples, aplicados diretamente no projeto:
Relações que usam o formato
{ "to_add": [...], "to_rem": [...] } — ambas as chaves devem estar presentes, mesmo que vazias:
Demais relações, com formato próprio:
Campos de answer_pool
array
required
As respostas a gravar, no mesmo formato usado na gravação individual.
object
required
Endereço do formulário. Exige
pivot_class, form_id e father_class. O identificador de cada item de ids é usado como o registro alvo — você não envia father_id.O conceito de
target (pivot) está detalhado em Formulários dinâmicos e o pivot.Resposta
A resposta é sempre 200, mesmo quando itens falham. O que importa está emresult:
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.Falha no meio do item
O processamento é item a item, mas não há desfazer por item. Se um projeto falhar depois de já ter aplicado parte das alterações — por exemplo, o campo simples foi gravado e a relação seguinte estourou — a parte já aplicada permanece.Concorrência
Só um lote por usuário de cada vez. Se outro lote do mesmo usuário estiver em andamento, a requisição responde 409:A trava vale por usuário e por empresa, e só é aplicada quando o lote tem mais de um item. Um lote de um item único passa direto.
Movimentação em lote entre etapas
Corpo da requisição
array
required
Lista de uuids de projetos.
integer
required
Etapa de destino.
boolean
Quando
true, desvincula o projeto das outras etapas do mesmo funil.boolean
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 das movimentações do lote é confirmada — inclusive as 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 que provocam esses erros estão em Restrições de etapa e Requisitos de etapa.
Concorrência
Vale a mesma trava da atualização em lote: um lote por usuário de cada vez, com 409 ebulk_operation_in_progress quando já existe outro em andamento. As duas operações compartilham a mesma trava — um lote de atualização em curso bloqueia um lote de movimentação do mesmo usuário.
Resumo prático
1
Escolha pelo comportamento de erro
Precisa que o lote inteiro seja atômico? Use a movimentação entre etapas. Precisa aplicar o que for possível e tratar o resto depois? Use a atualização em lote.
2
Confira o nome dos campos
Na atualização em lote, um campo escrito errado é ignorado sem aviso. Valide o payload antes de rodar sobre muitos registros.
3
Sempre leia o result
successCount igual ao total não garante que os campos certos foram aplicados — garante apenas que nenhum item lançou erro.4
Não rode lotes em paralelo
Com o mesmo usuário, o segundo lote recebe 409. Enfileire do seu lado.