API: criar orçamentos

O recurso cotizaciones (orçamentos) permite gerar propostas dinâmicas a partir do seu backend, ideal para integrações com o seu CRM ou ERP.

Criar um orçamento

Faça um POST para /api/v1/cotizaciones com pelo menos um item (exige escopo de escrita):

curl -X POST https://cordhq.app/api/v1/cotizaciones \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente_id": "customer-id",
    "terminos": "net30",
    "vigencia_dias": 15,
    "send": true,
    "items": [
      {
        "descripcion": "Annual ERP license",
        "cantidad": 1,
        "precio_unitario": 15000
      }
    ]
  }'

Resposta:

{ "data": { "id": "...", "folio": "COT-0149", "status": "sent", "link_publico": "/q/abc123" } }

Campos do corpo:

• items (obrigatório): array de itens. Cada um com descripcion, cantidad, precio_unitario e, opcionalmente, producto_id, precio_negociado, costo_unitario e tax_rate (fração 0–1, p. ex. 0.16; se omitido, usa-se a alíquota padrão da sua organização — o imposto é um dado do item, não do documento).
• cliente_id (opcional): id de um cliente existente (crie-o com API: gerenciar clientes).
• cliente (opcional, alternativa a cliente_id): objeto { empresa, email?, contacto?, telefono?, rfc? } para um cliente que ainda não existe — o Cord o procura por empresa/e-mail dentro da sua organização e, se não o encontrar, o cria.
• terminos: contado (à vista) ou net<N> para N dias de prazo: net7, net15, net30, net45, net60, net90.
• vigencia_dias: dias em que o orçamento permanece válido.
• notas: texto livre que aparece no final do orçamento.
• send: se for true, o Cord envia o link público para o e-mail do cliente ao criar o orçamento.
• base_currency/fiscal_currency (opcionais): moeda em que o cliente vê o orçamento e moeda contábil em que ele é faturado, se forem diferentes. fx_buffer_pct adiciona uma margem de segurança à taxa de câmbio congelada.
• iva_incluido (opcional): se for true, os precio_unitario dos itens já incluem o imposto.

Importante:

• Todos os valores vão em pesos (15000 = MXN 15.000,00), não em centavos.
• Os totais (impostos, retenções e moeda) são calculados no servidor com o mesmo motor que o app usa — nunca confie em um total calculado no cliente.
• link_publico é o caminho do link que seu cliente vê (/q/{token}); acrescente https://cordhq.app antes dele.

Listar orçamentos

curl "https://cordhq.app/api/v1/cotizaciones?status=sent&limit=50" \
  -H "Authorization: Bearer sk_live_your_key"

Retorna { "data": [ ... ], "meta": { "limit": 50, "offset": 0, "total": 87 } }. O detalhe de um orçamento (com itens e eventos) está em GET /api/v1/cotizaciones/{id}.