Clients

Synchronisez votre base d’organisations et de prospects commerciaux.

Vue d’ensemble

L’objet Client contient la fiche commerciale de référence des personnes ou des organisations que vous facturez. Synchroniser les clients via l’API est la base pour que Cord reste parfaitement aligné avec votre ERP ou votre CRM (comme Salesforce ou HubSpot).

Créer un client

Créez un nouveau client en envoyant un POST /api/v1/clientes. Le seul champ strictement obligatoire est le nom de l’entreprise (empresa) ; tout le reste est facultatif et dépend de votre activité et de votre pays. rfc est l’identifiant fiscal mexicain (Registro Federal de Contribuyentes) — il ne s’applique que si votre client est facturé au Mexique. Si votre entreprise ou votre client se trouve dans un autre pays, omettez simplement le champ : Cord n’exige pas de rfc pour créer ou facturer un client hors du Mexique.

Requête :

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

Réponse réussie :

{
  "data": {
    "id": "8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b"
  }
}

Règles métier automatiques

Lorsque vous créez des clients via l’API, Cord applique des contraintes logiques en temps réel :

Les conditions de paiement (terminos) doivent être valides : contado ou net7, net15, net30, net45, net60, net90 (N jours de crédit). Si vous transmettez une valeur non valide, elle revient par défaut à contado.
Le niveau de partenariat (nivel) est limité à estandar, plata, oro ou distribuidor.
Le RFC (si vous l’envoyez) est automatiquement mis en majuscules.
La remise (descuento_pct) est bornée entre 0 et 100.

Lister les clients

Récupérez le catalogue complet à l’aide de la pagination.

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

À la création d’un client, POST /api/v1/clientes accepte en plus l’adresse et les informations fiscales du destinataire : country_code (ISO 3166-1 alpha-2), direccion_line1 et direccion_line2 (jusqu’à 200 caractères), ciudad et region (jusqu’à 100) et, pour le Mexique, regimen_fiscal, uso_cfdi et cp_fiscal. En lecture, ils sont renvoyés sous les noms countryCode, direccionLine1, direccionLine2, ciudad, region, regimenFiscal, usoCfdi et cpFiscal. Lors d’une mise à jour avec PATCH, seul country_code peut être modifié dans ce groupe ; l’adresse et les informations fiscales se modifient depuis la fiche du client dans l’application.

À la création, vous pouvez aussi envoyer buyer_reference : la référence de l’acheteur que portent par défaut ses factures électroniques européennes (en Allemagne, le Leitweg-ID d’une administration publique). Une facture peut porter la sienne ; voir l’API des factures.

Identifiant fiscal validé

Cord valide rfc avec la clé de contrôle du pays du client ou, si vous n’envoyez pas country_code, du pays de votre compte : RFC au Mexique, NIF/NIE/CIF en Espagne, EIN aux États-Unis, CNPJ ou CPF au Brésil, NIT en Colombie, CUIT en Argentine, RUT au Chili, RUC au Pérou, SIREN, SIRET ou numéro de TVA en France, USt-IdNr. ou Steuernummer en Allemagne, VAT ou UTR au Royaume-Uni et Business Number au Canada. Un identifiant qui ne passe pas répond 422 avec code: "invalid_tax_id" et un motif qui nomme l’identifiant local. Lors d’une mise à jour, la validation n’a lieu que si vous changez l’identifiant ou le pays : une ancienne valeur ne vous empêche pas de corriger le téléphone ou l’e-mail.

Langue des documents

language est la langue dans laquelle le client reçoit ses devis, ses factures, ses PDF, ses e-mails et ses liens : es, en, pt, fr ou de ; null signifie celle de votre organisation. Elle s’envoie à la création et à la mise à jour. Dans un PATCH, l’omettre la conserve, et envoyer null ou une chaîne vide revient à celle de votre organisation. Toute autre valeur renvoie 400 avec code: "invalid_request" et field: "language". La modifier ne réécrit pas ce qui a déjà été envoyé : chaque devis et chaque facture garde la langue de son envoi ou de son émission.

Rechercher des clients

q cherche dans l’entreprise, le contact, l’e-mail et le RFC. email recherche l’adresse exacte sans tenir compte de la casse ; c’est le moyen d’éviter les doublons avant de créer un client depuis un autre outil.

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

Récupérer un client

GET /api/v1/clientes/{id} renvoie le même objet que la liste. Un id d’une autre organisation répond 404.

Mettre à jour un client

PATCH /api/v1/clientes/{id} ne modifie que les champs que vous envoyez : empresa, contacto, email, telefono, rfc, terminos, country_code et language. Le reste est conservé. La limite de crédit, le niveau et la remise ne peuvent pas être modifiés par cet endpoint, même si vous les envoyez. Nécessite une clé avec le droit d’écriture.

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": "procurement@stark.com" }'

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

Chaque modification émet l’événement client.updated.