A proposta traz next_action, rationale, trechos literais da conversa em evidence e um effect: none, schedule_follow_up (at), move_stage (stage_id) ou create_task (title, due_at). A geração usa a finalidade commercial_proposal em Provedores ou, sem vínculo próprio, o padrão do Cliente.
Gerar e decidir exigem o funil do CRM no plano da Conta. Sem ele, POST responde 422 feature_unavailable. As leituras continuam liberadas.
Rotas
GET /ai/commercial-proposals
Escopo agents:read
Query customer_id, status (pending, approved, dismissed, superseded ou decided), opportunity_id, page, per_page.
{
"id": "16161616-1616-4161-8161-161616161616",
"opportunity_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
"opportunity_title": "Cadeiras para o escritório",
"opportunity_status": "open",
"stage_id": null,
"stage_label": null,
"contact_id": "88888888-8888-4888-8888-888888888888",
"contact_name": "Ana",
"seq": 4,
"status": "pending",
"next_action": "Enviar a proposta com 10 cadeiras e prazo de entrega.",
"rationale": "O contato pediu orçamento para 10 unidades.",
"evidence": [
"Preciso de 10 cadeiras até o fim do mês"
],
"effect": {
"kind": "schedule_follow_up",
"at": "2026-09-26T09:00:00-03:00"
},
"effect_stage_label": null,
"provider": "openai",
"model": "MODELO_VALIDADO_NA_CREDENCIAL",
"binding_source": "purpose",
"created_at": "2026-09-25T13:00:00.000Z",
"decided_at": null,
"decided_by": null,
"decided_by_label": null,
"decided_by_api_key": null,
"decision_note": null,
"effect_applied": null,
"effect_result": null
}POST /ai/commercial-proposals
Escopo agents:write · chave criada por um Administrador
| Campo | Tipo e limites | Uso |
|---|---|---|
opportunity_id | UUID | Negócio do CRM. |
request_key | 1–200 de A-Z a-z 0-9 _ . : - | Chave de idempotência do pedido. |
{
"customer_id": "11111111-1111-4111-8111-111111111111",
"opportunity_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
"request_key": "crm-sync:opp-123:2026-09-25"
}Retorna {job_id, status, queued, replayed}: 202 quando o pedido entrou na fila e 200 quando não entrou (repetição da mesma chave ou pedido já em andamento). Acompanhe em jobs.
GET /ai/commercial-proposals/jobs
Escopo agents:read
Query customer_id. Os 50 pedidos mais recentes: reason (manual ou automatic), status, last_error e proposal_id gerado.
POST /ai/commercial-proposals/{id}/decision
Escopo agents:write · chave criada por um Administrador
| Campo | Tipo e limites | Uso |
|---|---|---|
decision | approve | dismiss | Decisão. |
seq | inteiro | seq da proposta lida. Trava otimista. |
note | até 1.000, opcional | Registro da decisão. |
apply_effect | boolean, padrão true | Aplica o efeito ao aprovar. false aprova sem mexer no CRM. |
{
"customer_id": "11111111-1111-4111-8111-111111111111",
"decision": "approve",
"seq": 4,
"note": "Ligar amanhã cedo.",
"apply_effect": true
}Retorna {id, status, seq, effect_applied, effect_result, replayed}. Se outra proposta substituiu a lida, responde 409 proposal_changed: leia de novo. Repetir a mesma decisão devolve replayed: true e não aplica o efeito outra vez.
GET /ai/commercial-proposals/settings
Escopo agents:read
Query customer_id. {enabled, revision, updated_at}; sem gravação, enabled: false e revision: 0.
PATCH /ai/commercial-proposals/settings
Escopo agents:write · chave criada por um Administrador
Corpo {customer_id, enabled, expected_revision} com revisão numérica. Liga a geração automática para os negócios do Cliente; os pedidos manuais funcionam em qualquer caso.
| Status | Código | Quando |
|---|---|---|
| 403 | forbidden | Chave não criada por um Administrador. |
| 404 | not_found | Proposta ou negócio fora do Cliente. |
| 409 | proposal_changed | seq diferente do atual. |
| 409 | already_decided | Proposta já decidida por outra pessoa. |
| 409 | opportunity_closed | Negócio encerrado. |
| 409 | stage_changed · stage_missing · effect_expired · next_step_changed | O efeito não vale mais. Aprove com apply_effect: false ou gere outra proposta. |
| 422 | feature_unavailable | Funil do CRM indisponível no plano. |
| 429 | rate_limited | Muitos pedidos de proposta na última hora. |
Visão geral do Agente de IA · Próxima: Uso e orçamento