Clientes

Sincroniza tu base de datos de organizaciones y prospectos comerciales.

Descripción General

El objeto Cliente contiene el registro maestro comercial de las personas u organizaciones a las que les facturas. Sincronizar clientes a través de la API es la base para mantener a Cord perfectamente alineado con tu ERP o CRM (como Salesforce o HubSpot).

Crear un Cliente

Crea un nuevo cliente enviando un POST /api/v1/clientes. El único campo estrictamente obligatorio es el nombre de la empresa; el resto es opcional y depende de tu negocio y país. rfc es el identificador fiscal mexicano (Registro Federal de Contribuyentes) — solo aplica si tu cliente factura en México. Si tu negocio o tu cliente está en otro país, simplemente omite el campo; Cord no exige un rfc para crear ni facturar a un cliente fuera de México.

Petición:

curl -X POST "https://cordhq.app/api/v1/clientes" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -d '{
       "empresa": "Stark Industries",
       "contacto": "Tony Stark",
       "email": "tony@stark.com",
       "rfc": "STA120412XYZ",
       "terminos": "net30",
       "limite": 500000,
       "nivel": "oro",
       "descuento_pct": 15
     }'

Respuesta Exitosa:

{
  "data": {
    "id": "cus_8f7b2c..."
  }
}

Reglas de Negocio Automatizadas

Cuando creas clientes vía API, Cord aplica restricciones lógicas en tiempo real:

Los términos de pago (terminos) deben ser válidos (contado, net30, net60). Si pasas algo inválido, recae por defecto a contado.
El nivel de alianza (nivel) está restringido a estandar, plata, oro, o distribuidor.
El RFC (si lo envías) se normaliza a mayúsculas automáticamente.
El descuento (descuento_pct) está limitado matemáticamente entre 0 y 100.

Listar Clientes

Recupera el catálogo completo usando Paginación.

curl -X GET "https://cordhq.app/api/v1/clientes?limit=100" \
     -H "Authorization: Bearer sk_live_tU..."

{
  "data": [
    {
      "id": "cus_8f7b2c...",
      "empresa": "Stark Industries",
      "contacto": "Tony Stark",
      "email": "tony@stark.com",
      "telefono": "",
      "rfc": "STA120412XYZ",
      "terminos": "A 30 días",
      "terminosCode": "net30",
      "limite": 500000,
      "nivel": "oro",
      "descuentoPct": 15,
      "countryCode": "",
      "direccionLine1": "",
      "ciudad": "",
      "region": "",
      "createdAt": "2026-08-01T10:00:00.000Z",
      "nCotizaciones": 4,
      "cerrado": 32000
    }
  ],
  "meta": { "limit": 100, "offset": 0, "total": 1 }
}

direccionLine1/direccionLine2, ciudad y region viajan en la lectura (los completa la app para cumplir el domicilio del receptor en la factura), pero la API todavía no los acepta — hoy solo se capturan desde Ajustes › Clientes. country_code sí se acepta al crear y al actualizar.

Buscar clientes

q busca en empresa, contacto, correo y RFC. email busca el correo exacto sin distinguir mayúsculas; es la forma de evitar duplicados antes de crear un cliente desde otra herramienta.

curl -X GET "https://cordhq.app/api/v1/clientes?email=tony@stark.com" \
     -H "Authorization: Bearer sk_live_tU..."

Obtener un Cliente

GET /api/v1/clientes/{id} devuelve el mismo objeto que el listado. Un id de otra organización responde 404.

Actualizar un Cliente

PATCH /api/v1/clientes/{id} cambia solo los campos que envíes: empresa, contacto, email, telefono, rfc, terminos y country_code. El resto se conserva. El límite de crédito, el nivel y el descuento no se pueden cambiar por este endpoint aunque los envíes. Requiere una llave con permiso de escritura.

curl -X PATCH "https://cordhq.app/api/v1/clientes/8f7b2c..." \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -d '{ "email": "compras@stark.com" }'

{ "data": { "ok": true } }

Cada cambio emite el evento client.updated.