API — Propostas (/proposals)
Criar e gerenciar propostas comerciais com itens (inclusive opcionais), vincular a contato e negócio, controlar status e acompanhar datas de envio, visualização, aceite e assinatura.
API — Propostas
Propostas comerciais. Base: /api/v1/proposals.
Endpoints
| Método | Path | Descrição |
|---|---|---|
| GET | /proposals | Listar propostas |
| POST | /proposals | Criar proposta (com itens) |
| GET | /proposals/{id} | Detalhes (itens, deal, URL pública, datas) |
| PUT | /proposals/{id} | Atualizar proposta |
| DELETE | /proposals/{id} | Excluir |
GET /proposals — filtros
| Parâmetro | Tipo | Descrição |
|---|---|---|
| search | string | número, título ou assunto |
| status | string | draft, sent, viewed, accepted, rejected, expired |
| contact_id | integer | filtra por contato |
| deal_id | integer | filtra por negócio |
| sort_by | string | created_at, proposal_date, valid_until, total, number, status |
| sort_dir | string | asc | desc (padrão desc) |
| per_page | integer | padrão 50, máx 100 |
POST /proposals — criar
Obrigatórios: contact_id e items (mín 1). Padrões: status=draft, proposal_date=hoje, valid_until=hoje+30 dias, assigned_to= usuário do token. Totais calculados automaticamente.
Atenção: em propostas o desconto percentual usa discount_type: "percentage" (em faturas é percent).
| Campo | Tipo | Regras |
|---|---|---|
| contact_id | integer | obrigatório |
| items | array | obrigatório, mín 1 |
| deal_id | integer | negócio relacionado |
| assigned_to | integer | responsável |
| title / subject | string | título / assunto |
| proposal_date / valid_until | date | datas |
| currency | string | padrão BRL |
| discount_amount | number | ≥ 0 |
| discount_type | string | fixed ou percentage |
| content | string | corpo da proposta (HTML) |
| notes / terms | string | máx 5000 |
Cada item: name (obrigatório), quantity (obrigatório, ≥0.01), unit_price (obrigatório, ≥0), e opcionais description, unit, product_id, tax_rate (0–100), discount_amount, discount_type (fixed|percentage), is_optional (boolean).
POST /api/v1/proposals
{
"contact_id": 5,
"title": "Proposta de Desenvolvimento",
"valid_until": "2026-05-31",
"items": [
{ "name": "Sistema Web", "quantity": 1, "unit_price": 8000 },
{ "name": "Suporte 12 meses", "quantity": 1, "unit_price": 2400, "is_optional": true }
]
}
PUT /proposals/{id}
Atualiza cabeçalho: contact_id, deal_id, assigned_to, title, subject, proposal_date, valid_until, status (draft|sent|accepted|rejected|expired), currency, discount_amount, discount_type, content, notes, terms. Não altera itens.
Formato (detalhe)
Além dos campos básicos (number, status, totais, contact, assigned_to, created_by), o detalhe traz: deal, content, notes, terms, public_url e o ciclo de vida — sent_at, viewed_at, accepted_at, rejected_at, signed_at, signer_name — além de items[] com is_optional.