Saltar al contenido
ESEN

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": "8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b"
  }
}

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 o net7, net15, net30, net45, net60, net90 (N días de crédito). 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": "8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b",
      "empresa": "Stark Industries",
      "contacto": "Tony Stark",
      "email": "tony@stark.com",
      "telefono": "",
      "rfc": "STA120412XYZ",
      "terminos": "Net 30",
      "terminosCode": "net30",
      "limite": 500000,
      "nivel": "oro",
      "descuentoPct": 15,
      "countryCode": "",
      "direccionLine1": "",
      "ciudad": "",
      "region": "",
      "language": "en",
      "createdAt": "2026-08-01T10:00:00.000Z",
      "nCotizaciones": 4,
      "cerrado": 32000
    }
  ],
  "meta": { "limit": 100, "offset": 0, "total": 1, "next_cursor": null }
}

cerrado es lo cerrado con ese cliente (cotizaciones aprobadas, pagadas o facturadas) en la divisa de tu negocio: un documento en otra divisa se convierte con la tasa congelada al cotizar o con la de hoy, y uno sin tipo de cambio disponible no se suma.

Al crear un cliente, POST /api/v1/clientes acepta además los datos del domicilio y fiscales del receptor: country_code (ISO 3166-1 alfa-2), direccion_line1 y direccion_line2 (hasta 200 caracteres), ciudad y region (hasta 100), y para México regimen_fiscal, uso_cfdi y cp_fiscal. En la lectura viajan como countryCode, direccionLine1, direccionLine2, ciudad, region, regimenFiscal, usoCfdi y cpFiscal. Al actualizar con PATCH, solo country_code de ese grupo se puede cambiar; el domicilio y los datos fiscales se editan desde la ficha del cliente en la app.

Al crear también puedes mandar buyer_reference: la referencia del comprador que llevan por defecto sus facturas electrónicas europeas (en Alemania, el Leitweg-ID de una administración pública). Una factura puede llevar la suya propia; ver API de Facturas.

Identificador fiscal validado

Cord valida rfc con el dígito de control del país del cliente o, si no mandas country_code, del país de tu cuenta: RFC en México, NIF/NIE/CIF en España, EIN en Estados Unidos, CNPJ o CPF en Brasil, NIT en Colombia, CUIT en Argentina, RUT en Chile, RUC en Perú, SIREN, SIRET o TVA en Francia, USt-IdNr. o Steuernummer en Alemania, VAT o UTR en Reino Unido y Business Number en Canadá. Uno que no pasa responde 422 con code: "invalid_tax_id" y un motivo que nombra el dato local. Al actualizar, solo se valida si cambias el identificador o el país: un dato antiguo no bloquea que corrijas el teléfono o el correo.

Idioma de los documentos

language es el idioma en que el cliente recibe sus cotizaciones, facturas, PDF, correos y links: es, en, pt, fr o de; null significa el de tu organización. Se manda al crear y al actualizar. En PATCH, omitirlo lo conserva y mandar null o una cadena vacía vuelve al de tu organización. Otro valor responde 400 con code: "invalid_request" y field: "language". Cambiarlo no reescribe lo ya enviado: cada cotización y factura guarda el idioma con que se envió o se emitió.

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, country_code y language. 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/8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b" \
     -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.