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étodoPathDescrição
GET/proposalsListar propostas
POST/proposalsCriar 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âmetroTipoDescrição
searchstringnúmero, título ou assunto
statusstringdraft, sent, viewed, accepted, rejected, expired
contact_idintegerfiltra por contato
deal_idintegerfiltra por negócio
sort_bystringcreated_at, proposal_date, valid_until, total, number, status
sort_dirstringasc | desc (padrão desc)
per_pageintegerpadrã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).

CampoTipoRegras
contact_idintegerobrigatório
itemsarrayobrigatório, mín 1
deal_idintegernegócio relacionado
assigned_tointegerresponsável
title / subjectstringtítulo / assunto
proposal_date / valid_untildatedatas
currencystringpadrão BRL
discount_amountnumber≥ 0
discount_typestringfixed ou percentage
contentstringcorpo da proposta (HTML)
notes / termsstringmá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.

api propostas proposals vendas integração

Este artigo foi útil?

Artigos Relacionados