API : créer des devis

La ressource cotizaciones (devis) vous permet de générer des propositions dynamiques depuis votre backend, idéal pour les intégrations avec votre CRM ou votre ERP.

Créer un devis

Envoyez un POST à /api/v1/cotizaciones avec au moins une ligne (nécessite une portée en écriture) :

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
      }
    ]
  }'

Réponse :

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

Champs du corps :

• items (obligatoire) : tableau de lignes. Chacune avec descripcion, cantidad, precio_unitario et, en option, producto_id, precio_negociado, costo_unitario et tax_rate (fraction 0–1, p. ex. 0.16 ; s’il est omis, le taux par défaut de votre organisation s’applique — la taxe est une donnée de la ligne, pas du document).
• cliente_id (facultatif) : id d’un client existant (créez-le avec API : gérer les clients).
• cliente (facultatif, alternative à cliente_id) : objet { empresa, email?, contacto?, telefono?, rfc? } pour un client qui n’existe pas encore — Cord le recherche par entreprise ou e-mail dans votre organisation et, s’il ne le trouve pas, le crée.
• terminos : contado (paiement à réception) ou net<N> pour N jours de crédit : net7, net15, net30, net45, net60, net90.
• vigencia_dias : nombre de jours de validité du devis.
• notas : texte libre affiché en bas du devis.
• send : si true, Cord envoie le lien public à l’e-mail du client lors de la création.
• base_currency/fiscal_currency (facultatifs) : devise dans laquelle le client voit le devis et devise comptable dans laquelle il est facturé, si elles diffèrent. fx_buffer_pct ajoute une marge de sécurité au taux de change figé.
• iva_incluido (facultatif) : si true, les precio_unitario des lignes incluent déjà la taxe.

Important :

• Tous les montants sont exprimés en pesos (15000 = 15 000,00 MXN), et non en centimes.
• Les totaux (taxes, retenues à la source et devise) sont calculés côté serveur avec le même moteur que celui de l’application — ne vous fiez jamais à un total calculé côté client.
• link_publico est le chemin du lien que voit votre client (/q/{token}) ; préfixez-le avec https://cordhq.app.

Lister les devis

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

Renvoie { "data": [ ... ], "meta": { "limit": 50, "offset": 0, "total": 87 } }. Le détail d’un devis (avec ses lignes et ses événements) se trouve dans GET /api/v1/cotizaciones/{id}.