Importação em massa — Prosalab Developers

escopo: bulk:writeEnterprise

Enfileira um lote de importação de contatos. Responde 202 com o job_id para acompanhamento.

Todo lote ganha automaticamente uma etiqueta import_DDMMAAAA_HHhMMmin_api com a data/hora de início da importação.
Limites: até 10.000 contatos por job, corpo máximo de 4MB, no máximo 2 importações ativas por empresa.
custom_fields é keyed pelo ID do campo (UUID de GET /api/v1/custom-fields), valores sempre string; um ID fora das definições ativas da empresa retorna 422 no enfileiramento (crie os campos antes via POST /api/v1/custom-fields).
Campos nativos (cpf, rg, genero, estado_civil, profissao, city, state, postal_code) vão no top-level de cada contato; cnpj cria/associa a empresa-cliente (organization) com deduplicação por CNPJ dentro do lote.

Modelo de envio

Corpo da requisição

{
  "contacts": [
    {
      "phone": "5548999990000",
      "name": "João Silva",
      "email": "joao@exemplo.com.br",
      "birthday": "1990-05-12",
      "observation": "Veio da feira de negócios",
      "cpf": "99001122334",
      "genero": "Masculino",
      "estado_civil": "Casado",
      "city": "Florianópolis",
      "state": "SC",
      "postal_code": "88010000",
      "cnpj": "12345678000190",
      "custom_fields": {
        "<id-do-campo-uuid>": "campanha",
        "<id-de-outro-campo-uuid>": "9"
      }
    }
  ],
  "options": {
    "update_existing_names": true,
    "list_ids": [
      "<uuid>"
    ]
  }
}

Resposta (202)

Corpo da resposta

{
  "success": true,
  "data": {
    "job_id": "<uuid>",
    "status": "pending",
    "total": 10000
  }
}

Erros

Status	Código	Quando ocorre
413	PAYLOAD_TOO_LARGE	Corpo da requisição acima de 4MB
404	NOT_FOUND	Uma ou mais list_ids em "options" não pertencem à empresa
409	QUEUE_FULL	A empresa já tem 2 importações ativas (pending/processing)
429	RATE_LIMITED	Mais de 5 importações enfileiradas no último minuto por esta key
422	VALIDATION_ERROR	custom_fields usa um ID que não é de campo ativo da empresa, ou algum valor não é string (lista dos inválidos em details.custom_fields)

Exemplo

curl

curl -s -X POST -H "Authorization: Bearer <sua-key>" -H "Content-Type: application/json" \
  -d '{"contacts":[{"phone":"5548999990000","name":"João Silva","email":"joao@exemplo.com.br","birthday":"1990-05-12","observation":"Veio da feira de negócios","cpf":"99001122334","genero":"Masculino","estado_civil":"Casado","city":"Florianópolis","state":"SC","postal_code":"88010000","cnpj":"12345678000190","custom_fields":{"<id-do-campo-uuid>":"campanha","<id-de-outro-campo-uuid>":"9"}}],"options":{"update_existing_names":true,"list_ids":["<uuid>"]}}' \
  https://www.prosalab.com/api/v1/contacts/bulk

GET/api/v1/contacts/bulk/{jobId}

escopo: contacts:read ou bulk:writeEnterprise

Progresso do job de importação: contadores, percentual e erros por item.

Resposta (200)

Corpo da resposta

{
  "success": true,
  "data": {
    "status": "processing",
    "total": 10000,
    "processed": 4200,
    "imported": 3800,
    "updated": 350,
    "skipped": 40,
    "failed": 10,
    "progress_pct": 42,
    "errors": [
      {
        "index": 12,
        "phone": "5548999990000",
        "reason": "Telefone inválido"
      }
    ],
    "created_at": "2026-07-16T18:00:00.000Z",
    "completed_at": null
  }
}

Erros

Status	Código	Quando ocorre
404	NOT_FOUND	Job não existe, ID malformado, ou pertence a outra empresa

Exemplo

curl

curl -s -H "Authorization: Bearer <sua-key>" https://www.prosalab.com/api/v1/contacts/bulk/{jobId}