Negócios

Listar, consultar, criar e atualizar negócios, além das ações de ganhar, perder e mover de etapa.

GET   {BASE_URL}/api-v1-deals               # lista
GET   {BASE_URL}/api-v1-deals/:id            # detalhe (+ contato, empresa, última atividade)
POST  {BASE_URL}/api-v1-deals               # cria
PATCH {BASE_URL}/api-v1-deals/:id            # atualiza
POST  {BASE_URL}/api-v1-deals/:id/move-stage # move de etapa
POST  {BASE_URL}/api-v1-deals/:id/win        # marca como ganho
POST  {BASE_URL}/api-v1-deals/:id/lose       # marca como perdido

Escopos: deals:read para os GET; deals:write para POST, PATCH e as ações.

O recurso Negócio

Campo	Tipo	Notas
`id`	uuid
`workspace_id`	uuid
`name`	string	Nome do negócio.
`status`	enum	`aberto`, `ganho` ou `perdido`.
`value`	number \| null	Valor único.
`recurring_value`	number \| null	Valor recorrente.
`pipeline_id`	uuid
`stage_id`	uuid
`owner_id`	uuid	Responsável (id de membro).
`contact_id`	uuid \| null
`company_id`	uuid \| null
`expected_close_date`	date \| null	`YYYY-MM-DD`.
`lead_source_id`	uuid \| null
`loss_reason_id`	uuid \| null	Preenchido quando perdido (se informado).
`won_at`	datetime \| null
`lost_at`	datetime \| null
`stage_entered_at`	datetime \| null	Entrada na etapa atual.
`external_id`	string \| null	Vindo da entrada de leads.
`source`	string \| null
`notes`	string \| null
`custom_fields`	object \| null
`created_at`	datetime
`updated_at`	datetime

Listar negócios

GET {BASE_URL}/api-v1-deals

Filtro (query)	Tipo	Notas
`status`	enum	`aberto`, `em_andamento` (alias de `aberto`), `ganho`, `perdido`.
`pipeline_id`	uuid
`stage_id`	uuid
`owner_id`	uuid
`since`	ISO 8601	`created_at >= since`.
`limit`	int	Padrão 50, máx 200.
`cursor`	uuid	Próxima página (veja paginação).

curl "{BASE_URL}/api-v1-deals?status=aberto&limit=50" \
  -H "X-API-Key: vnd_sua_chave_aqui"

{
  "data": [ { "id": "8f3c...", "name": "Empresa Exemplo", "status": "aberto", "value": 12000, "...": "..." } ],
  "meta": { "next_cursor": "8f3c...", "has_more": true }
}

Consultar um negócio

GET {BASE_URL}/api-v1-deals/:id

Retorna o negócio com três blocos embutidos: contact, company (objeto ou null) e last_activity (a última atividade do negócio, ou null):

{
  "id": "8f3c...",
  "name": "Empresa Exemplo",
  "status": "aberto",
  "contact": { "id": "1a2b...", "name": "Maria Silva", "email": "maria@...", "...": "..." },
  "company": { "id": "9d8e...", "name": "Empresa Exemplo", "...": "..." },
  "last_activity": {
    "id": "5e6f...",
    "title": "Ligação de qualificação",
    "status": "concluida",
    "scheduled_at": "2026-06-26T14:00:00.000Z",
    "completed_at": "2026-06-26T14:20:00.000Z",
    "created_at": "2026-06-25T09:00:00.000Z"
  }
}

Criar um negócio

POST {BASE_URL}/api-v1-deals — escopo deals:write.

Campo	Tipo	Obrigatório	Notas
`name`	string	Sim	1–255 caracteres.
`pipeline_id`	uuid	Não	Omitido → pipeline padrão.
`stage_id`	uuid	Não	Omitido → primeira etapa do pipeline.
`owner_id`	uuid	Não	Omitido → resolução automática (criador da chave → admin/gestor mais antigo).
`contact_id`	uuid	Não	Deve pertencer ao workspace.
`company_id`	uuid	Não	Deve pertencer ao workspace.
`value`	number	Não	≥ 0.
`recurring_value`	number	Não	≥ 0.
`expected_close_date`	date	Não	`YYYY-MM-DD`.
`lead_source_id`	uuid	Não	Deve pertencer ao workspace.
`notes`	string	Não	Até 10.000 caracteres.
`custom_fields`	object	Não	≤ 50 chaves, ≤ 10 KB.

curl -X POST "{BASE_URL}/api-v1-deals" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Projeto Q3 - Empresa Exemplo", "value": 24000, "recurring_value": 2000 }'

Resposta 201 Created:

{ "id": "8f3c...", "owner_id": "3c2d...", "pipeline_id": "7b6a...", "stage_id": "0f1e...", "status": "aberto" }

Atualizar um negócio

PATCH {BASE_URL}/api-v1-deals/:id — escopo deals:write.

Aceita os mesmos campos do POST, todos opcionais. Não muda etapa nem fecha o negócio: status, stage_id, won_at e lost_at não são editáveis por aqui — use as ações abaixo. Retorna o negócio completo atualizado (200 OK).

curl -X PATCH "{BASE_URL}/api-v1-deals/8f3c..." \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "value": 30000, "notes": "Cliente pediu proposta revisada." }'

Mover de etapa

POST {BASE_URL}/api-v1-deals/:id/move-stage — escopo deals:write.

curl -X POST "{BASE_URL}/api-v1-deals/8f3c.../move-stage" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "0f1e..." }'

stage_id é obrigatório e deve pertencer ao pipeline do negócio (senão 422 invalid_reference). Retorna o negócio atualizado.

Marcar como ganho

POST {BASE_URL}/api-v1-deals/:id/win — escopo deals:write.

curl -X POST "{BASE_URL}/api-v1-deals/8f3c.../win" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{}'

won_at (opcional, ISO 8601) define a data do ganho; omitido → agora.
Idempotente: se o negócio já está ganho, responde 200 OK sem reescrever a data.

Marcar como perdido

POST {BASE_URL}/api-v1-deals/:id/lose — escopo deals:write.

curl -X POST "{BASE_URL}/api-v1-deals/8f3c.../lose" \
  -H "X-API-Key: vnd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "loss_reason_id": "2b3c...", "notes": "Escolheu concorrente." }'

loss_reason_id (opcional, uuid) deve pertencer ao workspace.
Idempotente: se o negócio já está perdido, responde 200 OK sem reprocessar.

Erros possíveis

HTTP	`code`	Quando
`401`	`missing_api_key` / `invalid_api_key` / `revoked_api_key`	Autenticação.
`403`	`insufficient_scope`	Falta `deals:read` (GET) ou `deals:write` (escrita).
`404`	`not_found`	Negócio não existe nesse workspace.
`400`	`bad_request`	Corpo ausente/JSON inválido (escrita).
`422`	`validation_error`	Campo ou parâmetro inválido.
`422`	`invalid_reference`	`contact_id`/`company_id`/`stage_id`/`lead_source_id`/`loss_reason_id`/`owner_id` fora do workspace.
`422`	`invalid_cursor`	`cursor` inválido.
`422`	`no_default_pipeline` / `pipeline_has_no_stage` / `no_owner_available`	Falha ao resolver pipeline/etapa/responsável na criação.
`405`	`method_not_allowed`	Método não suportado.
`500`	`internal_error`	Falha interna.

Negócios

Nesta página