Cotizaciones

El corazón transaccional de Cord. Crea propuestas, obtén sus links públicos y adminístralas.

Descripción General

El objeto Cotizacion (quote) representa una propuesta comercial hacia un cliente. Usando la API de Cord, puedes inyectar cotizaciones directamente desde un ERP, CRM o generar flujos automatizados de carritos de compra.

Todas las cotizaciones generadas vía API quedan registradas en el registro de auditoría (audit_log) etiquetadas automáticamente como provenientes de tu Clave de API.

Crear una Cotización

Para crear un borrador de cotización, debes realizar un POST /api/v1/cotizaciones enviando el detalle comercial.

Petición:

curl -X POST "https://cordhq.app/api/v1/cotizaciones" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -d '{
       "cliente_id": "cus_9x8f7",
       "terminos": "net30",
       "vigencia_dias": 15,
       "notas": "Proyecto anual",
       "base_currency": "EUR",
       "items": [
         {
           "descripcion": "Licencia anual — plan Pro",
           "cantidad": 12,
           "precio_unitario": 500
         }
       ]
     }'

Cada línea de items requiere descripcion, cantidad y precio_unitario. producto_id es opcional (referencia un producto de tu catálogo para heredar su nombre y precio de lista) y precio_negociado permite capturar un precio con descuento distinto al de lista. No existe un campo sku: si quieres enlazar la línea a un producto, usa su producto_id.

base_currency es la divisa en la que el cliente ve y paga la cotización (ISO 4217, ej. MXN, USD, EUR, GBP). Es opcional — si la omites, Cord usa la divisa contable de tu organización — pero la API es agnóstica de país: una cuenta en Madrid, Austin o Bogotá cotiza en su propia divisa sin ningún parámetro adicional.

Respuesta Exitosa:

Cord te devuelve no solo el ID interno de la base de datos, sino también el Token Público (link_publico) preconstruido, ya absoluto, para que se lo envíes a tu cliente inmediatamente vía WhatsApp, SMS o un motor de correos externo.

{
  "data": {
    "id": "qte_2a9d8",
    "folio": "COT-00104",
    "token": "tok_x8Yj9Z...",
    "link_publico": "https://cordhq.app/q/tok_x8Yj9Z...",
    "needs_approval": false
  }
}

Si la cotización requiere aprobación interna antes de enviarse (por ejemplo, un descuento fuera de umbral), needs_approval viene en true y motivo describe la razón.

Listar Cotizaciones

Puedes recuperar tu historial paginado de cotizaciones o filtrar por estado (por ejemplo, buscar todas las cotizaciones enviadas o pagadas).

Petición:

curl -X GET "https://cordhq.app/api/v1/cotizaciones?status=paid&limit=10" \
     -H "Authorization: Bearer sk_live_tU..."

El valor de status es el estado interno tal cual (en inglés, no traducido): draft, sent, viewed, approved, rejected, expired, paid o invoiced. Para buscar una cotización por su folio usa folio=COT-00104: compara el folio completo sin distinguir mayúsculas.

{
  "data": [
    {
      "id": "qte_2a9d8",
      "folio": "COT-00104",
      "cliente": "Stark Industries",
      "status": "paid",
      "total": 6000,
      "terminos": "net30",
      "vigencia": "2026-09-10",
      "creada": "2026-08-20T14:32:00.000Z",
      "link_publico": "/q/tok_x8Yj9Z..."
    }
  ],
  "meta": { "limit": 10, "offset": 0, "total": 1 }
}

Nota: en el listado, link_publico es una ruta relativa (/q/<token>); en la respuesta de creación viene absoluta. Para el detalle de una sola cotización (líneas, eventos, aprobación), usa GET /api/v1/cotizaciones/{id}.

Cambiar el estado de una cotización

Con una llave de escritura (write) puedes mover la cotización por su ciclo de vida con POST /api/v1/cotizaciones/{id}:

curl -X POST "https://cordhq.app/api/v1/cotizaciones/qte_2a9d8" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: aprobar-COT-00104" \
     -d '{ "action": "approve" }'

action	Desde el estado	Resultado
send	draft	Envía la cotización al cliente (correo y link). En el plan Gratis consume uno de los envíos del mes.
resend	sent, viewed, expired	La reenvía al cliente.
approve	sent, viewed	La marca como aprobada.
reject	sent, viewed	La marca como rechazada.
mark_paid	approved, invoiced	Registra el pago. Acepta payment_method opcional (por defecto transferencia). Los cobros en línea pendientes de esa cotización se cancelan.

La respuesta es { "data": { "ok": true, "status": "approved" } }. Si la cotización no está en un estado desde el que se pueda aplicar la acción, o si otra petición la cambió al mismo tiempo, recibes 409 con code: "invalid_state" y no se aplica nada. Cada cambio queda en el registro de auditoría con tu llave como actor y dispara su evento de webhook.

Emitir la factura no está disponible por esta ruta: las facturas se crean y emiten con POST /api/v1/facturas y POST /api/v1/facturas/{id}.

Eliminar un borrador

DELETE /api/v1/cotizaciones/{id} elimina una cotización que nunca se envió (draft). Cualquier otro estado responde 409.