Lote — criar, editar e apagar em massa
Cria até 100 registros numa chamada só. Pensado para importação de planilha ou migração de outro CRM.
Cria até 100 registros numa chamada só. Pensado para importação de planilha ou migração de outro CRM.
POST /api/contacts/batch
POST /api/companies/batch
POST /api/deals/batch
POST /api/tasks/batchEscopo: o :write do próprio recurso. Corpo: até 512 KB.
Produtos também têm lote de criação (POST/api/products/batch), com regras próprias — ver a
referência de Produtos. Edição e exclusão em massa (abaixo) valem só para os quatro recursos
acima.
{
"items": [
{ "name": "Ana Lima", "email": "ana@exemplo.com.br" },
{ "name": "", "email": "invalido" },
{ "name": "Bruno Reis", "phone": "+55 11 91234-5678" }
]
}Cada item aceita exatamente os mesmos campos do POST unitário daquele recurso (o mesmo
schema, sem uma segunda cópia que possa divergir) e passa pelas mesmas validações — inclusive
source, contact_ids, tag_ids, custom_fields, loss_reason_id/lost_reason e
external_id no lote de negócios.
A resposta é sempre 200, mesmo com item inválido no meio:
{
"data": {
"resultados": [
{ "indice": 0, "ok": true, "id": "9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73" },
{ "indice": 1, "ok": false, "erro": "Nome obrigatório" },
{ "indice": 2, "ok": true, "id": "1b7c9d2e-5f3a-4e8b-9c1d-2a6f4b8e3d57" }
]
}
}
200não significa "os 100 foram criados". Confira ookde cada posição. Um item que falha não derruba os outros nem desfaz os já gravados.resultados[i]sempre corresponde aitems[i]pelo índice.
ok: truecomavisos. Quando o registro foi gravado mas algum valor decustom_fieldsnão foi, a posição volta{ "indice": 0, "ok": true, "id": "…", "avisos": ["custom_fields_write_failed"] }— o mesmo sinal que oPOST/PATCHunitário dá pelo cabeçalhox-salos-custom-fields-write-failed(seção 28). Reenvie só oPATCH { "custom_fields": … }daquele registro.
Idempotência: a Idempotency-Key vale para o lote inteiro. Reenviar a mesma chave devolve
o mesmo resultado, mesmo que parte tenha falhado — nunca reprocessa. Para tentar de novo só os
itens que falharam, mande um lote novo com chave nova, contendo apenas eles.
| Erro | Código |
|---|---|
| Mais de 100 itens | 400 — "O lote aceita no máximo 100 itens." |
items vazio ou ausente |
400 |
| Corpo acima de 512 KB | 400 |
POST/api/leads/batch tem o mesmo formato — { "items": [...] }, até 100, Idempotency-Key
vale para o lote inteiro — mas cada item é um lead (mesmo corpo do POST/api/leads unitário,
seção 11) e o resultado por posição não é {id}: é {external_ref, created, contact_id, deal_id}, o mesmo shape do unitário, porque um lead pode reaproveitar contato existente
(created: false) em vez de criar um novo.
Editar em massa (PATCH .../batch)
PATCH /api/contacts/batch
PATCH /api/companies/batch
PATCH /api/deals/batch
PATCH /api/tasks/batch{
"items": [
{ "id": "9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73", "title": "Comprador sênior" },
{ "id": "1b7c9d2e-5f3a-4e8b-9c1d-2a6f4b8e3d57", "phone": "+55 11 90000-0000" }
]
}Cada item precisa de id (uuid) mais os campos a mudar — o resto do item é exatamente o
corpo do PATCH unitário daquele recurso (mesmo schema, mesma validação, inclusive external_id
e 409 external_id_immutable). Item sem id, ou com id que não existe nesta conta, falha só
aquela posição — igual ao lote de criação. Aceita até 100 itens e ?dry_run=true.
Apagar em massa (.../batch-delete)
POST /api/contacts/batch-delete
POST /api/companies/batch-delete
POST /api/deals/batch-delete
POST /api/tasks/batch-delete{ "ids": ["9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73", "1b7c9d2e-5f3a-4e8b-9c1d-2a6f4b8e3d57"] }Até 100 ids por chamada, mesma resposta por posição ({indice, ok, id} ou {indice, ok: false, erro}), mesmo ?dry_run=true. Empresa com negócio vinculado (aberto ou fechado) devolve o mesmo
409 do DELETE unitário naquela posição — as outras do lote seguem normalmente.