Propostas

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

Propostas são documentos comerciais vinculados a um deal: estrutura de items, totais, status (draft, sent, accepted, declined, expired).

Lista propostas

GET /api/v1/proposals

Scope: proposals:read

Param	Tipo	Descrição
`status`	string	Filtra por status (`draft`, `sent`, `accepted`, etc.)
`search`	string	Busca em número/assunto
`contactId`	string	Propostas de um contato
`clientId`	string	Propostas de uma empresa
`dealId`	string	Proposta de um deal específico
`page` / `limit`	number	Paginação

Busca uma proposta

GET /api/v1/proposals/:id

Scope: proposals:read

Retorna proposta com items[] aninhados, totais calculados, e contato/empresa/deal expandidos.

{
  "id": "ckl4pp01...",
  "number": "PR-2026-0042",
  "subject": "Implantação CRM Enterprise",
  "status": "sent",
  "sentAt": "2026-05-20T10:00:00.000Z",
  "dealId": "ckl4d01...",
  "contactId": "ckl4z01...",
  "clientId": "ckl4c01...",
  "recipientName": "Maria Silva",
  "recipientEmail": "maria@empresa.com.br",
  "subtotal": 24000,
  "discount": 0,
  "adjustment": 0,
  "total": 24000,
  "items": [
    {
      "id": "ckl4i01...",
      "order": 0,
      "name": "Setup inicial + treinamento",
      "qty": 1,
      "unit": "Projeto",
      "rate": 8000,
      "total": 8000
    },
    {
      "id": "ckl4i02...",
      "order": 1,
      "name": "Mensalidade plano Enterprise",
      "qty": 12,
      "unit": "Mês",
      "rate": 1333.33,
      "total": 16000
    }
  ],
  "createdAt": "2026-05-18T14:00:00.000Z"
}

Cria uma proposta

POST /api/v1/proposals

Scope: proposals:write

Campo	Tipo	Obrigatório	Descrição
`subject`	string	✅	Assunto da proposta
`dealId`	string	—	Vincula a um deal (1:1)
`contactId`	string	—	Destinatário (contato)
`clientId`	string	—	Empresa cliente
`recipientName`	string	—	Override do nome no PDF
`recipientEmail`	string	—	Override do email
`items`	array	—	Items da proposta (ver shape abaixo)
`discount`	number	—	Desconto absoluto sobre o subtotal
`adjustment`	number	—	Ajuste extra (pode ser negativo)
`notes`	string	—	Notas/observações
`ownerId`	string	—	User dono (default: caller)
`status`	`draft \| sent \| accepted \| declined \| expired`	—	Default `draft`

Shape de item:

Campo	Tipo	Default
`name`	string	obrigatório
`description`	string	—
`qty`	number	1
`unit`	string	`Unidade`
`rate`	number	0
`discountPct`	number	0
`taxPct`	number	0

curl -X POST https://app.indutivacrm.com.br/api/v1/proposals \
  -H "X-API-Key: crm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Implantação CRM Enterprise — Acme",
    "dealId": "ckl4d01...",
    "items": [
      { "name": "Setup", "qty": 1, "rate": 8000 },
      { "name": "Mensalidade", "qty": 12, "rate": 1333.33 }
    ]
  }'

O número (PR-YYYY-NNNN) é gerado automaticamente.

Atualiza uma proposta

PATCH /api/v1/proposals/:id

Scope: proposals:write

Atualização parcial. Útil pra mudar status:

# Cliente aceitou
curl -X PATCH https://app.indutivacrm.com.br/api/v1/proposals/ckl4pp01... \
  -H "X-API-Key: crm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "accepted"}'

Mudanças de status disparam eventos internos (proposal.sent, proposal.accepted, etc.) que podem alimentar webhooks de saída ou automações no CRM.

Deleta uma proposta

DELETE /api/v1/proposals/:id

Scope: proposals:write

Soft-delete. O deal vinculado fica intacto.

Erros específicos

Status	`error`	Cenário
400	`invalid_status`	`status` fora do enum permitido
400	`duplicate_proposal_for_deal`	Já existe proposta vinculada a esse `dealId`
400	`validation_failed`	`subject` ausente ou items malformados
404	`not_found`	`id` não existe