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/batch

Escopo: 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" }
    ]
  }
}

200 não significa "os 100 foram criados". Confira o ok de cada posição. Um item que falha não derruba os outros nem desfaz os já gravados. resultados[i] sempre corresponde a items[i] pelo índice.

ok: true com avisos. Quando o registro foi gravado mas algum valor de custom_fields não foi, a posição volta { "indice": 0, "ok": true, "id": "…", "avisos": ["custom_fields_write_failed"] } — o mesmo sinal que o POST/PATCH unitário dá pelo cabeçalho x-salos-custom-fields-write-failed (seção 28). Reenvie só o PATCH { "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.