Negócios (Deals)

Base path: /api/v1/deals Scopes: deals:read | deals:write

Deals (negócios) são oportunidades de venda dentro de um pipeline. Cada deal pertence a um pipeline, está em uma etapa (stage), e pode estar vinculado a um contato e/ou empresa.

Lista deals

GET /api/v1/deals

Scope: deals:read

Param	Tipo	Descrição
`page` / `pageSize`	number	Paginação (default 50, máx 100)
`pipelineId`	string	Filtra por pipeline
`stageId`	string	Filtra por etapa
`ownerId`	string	Filtra por owner
`contactId`	string	Deals associados a um contato
`companyId`	string	Deals associados a uma empresa
`isWon` / `isLost`	boolean	Status de fechamento
`valueMin` / `valueMax`	number	Range de valor
`search`	string	Busca em título
`sortKey`	string	Default `updatedAt`
`sortOrder`	`asc \| desc`	Default `desc`

curl "https://app.indutivacrm.com.br/api/v1/deals?pipelineId=ckl4p01...&isWon=false&isLost=false" \
  -H "X-API-Key: crm_live_..."

Busca um deal

GET /api/v1/deals/:id

Scope: deals:read

Retorna o deal com contato e empresa associados (objetos expandidos), além de customProperties.

Cria um deal

POST /api/v1/deals

Scope: deals:write

Campo	Tipo	Obrigatório	Descrição
`title`	string	✅	Título do negócio
`pipelineId`	string	✅	Pipeline ao qual o deal pertence
`stageId`	string	✅	Etapa inicial (precisa pertencer ao pipeline)
`value`	number	—	Valor monetário
`currency`	string	—	ISO 4217, default `BRL`
`contactId`	string	—	Contato principal vinculado
`companyId`	string	—	Empresa vinculada
`ownerId`	string	—	User responsável
`expectedCloseDate`	string (ISO)	—	Data prevista de fechamento
`customProperties`	object	—	`{ propertyId: value }`

curl -X POST https://app.indutivacrm.com.br/api/v1/deals \
  -H "X-API-Key: crm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Proposta Acme — CRM Enterprise",
    "pipelineId": "ckl4p01...",
    "stageId": "ckl4s01...",
    "value": 24000,
    "currency": "BRL",
    "contactId": "ckl4z9w8v0001abcdef123456",
    "companyId": "ckl4c01...",
    "expectedCloseDate": "2026-06-30T00:00:00Z"
  }'

Atualiza um deal

PATCH /api/v1/deals/:id

Scope: deals:write

Atualização parcial. Útil pra mover entre etapas:

curl -X PATCH https://app.indutivacrm.com.br/api/v1/deals/ckl4d01... \
  -H "X-API-Key: crm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"stageId": "ckl4s02..."}'

Ou fechar como ganho:

curl -X PATCH https://app.indutivacrm.com.br/api/v1/deals/ckl4d01... \
  -H "X-API-Key: crm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"isWon": true, "closedAt": "2026-05-22T18:00:00Z"}'

Ou perda (com motivo):

curl -X PATCH https://app.indutivacrm.com.br/api/v1/deals/ckl4d01... \
  -H "X-API-Key: crm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "isLost": true,
    "lossReasonId": "ckl4lr01...",
    "lossNotes": "Cliente foi com concorrente por preço"
  }'

Deleta um deal

DELETE /api/v1/deals/:id

Scope: deals:write

Soft-delete. Atividades vinculadas ficam.

Resposta 204 No Content.

Erros específicos

Status	`error`	Cenário
409	`stage_invalid`	`stageId` não pertence ao `pipelineId` informado
400	`validation_failed`	`title`, `pipelineId` ou `stageId` ausentes
422	`business_rule_violation`	Tentou marcar `isWon` E `isLost` simultaneamente, ou mover deal pra stage de outro pipeline
404	`not_found`	`id` não existe