Zum Inhalt springen
DEEN

Kunden

Synchronisieren Sie Ihre Datenbank mit Organisationen und Interessenten.

Überblick

Das Objekt Client enthält den kaufmännischen Stammdatensatz der Personen oder Organisationen, denen Sie Rechnungen stellen. Die Synchronisierung von Kunden über die API ist die Grundlage dafür, Cord exakt auf Ihr ERP oder CRM (etwa Salesforce oder HubSpot) abzustimmen.

Einen Kunden anlegen

Legen Sie einen neuen Kunden an, indem Sie POST /api/v1/clientes senden. Das einzige zwingend erforderliche Feld ist der Firmenname (empresa); alles andere ist optional und hängt von Ihrem Unternehmen und Land ab. rfc ist die mexikanische Steuernummer (Registro Federal de Contribuyentes) – sie gilt nur, wenn Ihr Kunde in Mexiko abgerechnet wird. Befindet sich Ihr Unternehmen oder Ihr Kunde in einem anderen Land, lassen Sie das Feld einfach weg; Cord verlangt kein rfc, um einen Kunden außerhalb Mexikos anzulegen oder ihm eine Rechnung auszustellen.

Anfrage:

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

Erfolgreiche Antwort:

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

Automatische Geschäftsregeln

Wenn Sie Kunden über die API anlegen, wendet Cord in Echtzeit logische Einschränkungen an:

  • Die Zahlungsbedingungen (terminos) müssen gültig sein: contado oder net7, net15, net30, net45, net60, net90 (Zahlungsziel von N Tagen). Bei einem ungültigen Wert wird standardmäßig contado verwendet.
  • Die Partnerstufe (nivel) ist auf estandar, plata, oro oder distribuidor beschränkt.
  • Der RFC (falls Sie ihn senden) wird automatisch in Großbuchstaben umgewandelt.
  • Der Rabatt (descuento_pct) ist mathematisch auf 0 bis 100 begrenzt.

Kunden auflisten

Rufen Sie den vollständigen Katalog mit Paginierung ab.

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

Beim Anlegen eines Kunden akzeptiert POST /api/v1/clientes außerdem Adresse und Steuerdaten des Empfängers: country_code (ISO 3166-1 Alpha-2), direccion_line1 und direccion_line2 (bis zu 200 Zeichen), ciudad und region (bis zu 100) sowie für Mexiko regimen_fiscal, uso_cfdi und cp_fiscal. Beim Lesen kommen sie als countryCode, direccionLine1, direccionLine2, ciudad, region, regimenFiscal, usoCfdi und cpFiscal zurück. Beim Aktualisieren mit PATCH lässt sich aus dieser Gruppe nur country_code ändern; Adresse und Steuerdaten bearbeiten Sie im Kundenprofil in der App.

Beim Anlegen können Sie außerdem buyer_reference senden: die Käuferreferenz, die seine europäischen E-Rechnungen standardmäßig tragen (in Deutschland die Leitweg-ID einer öffentlichen Verwaltung). Eine Rechnung kann ihre eigene Referenz tragen; siehe Rechnungs-API.

Geprüfte Steuernummer

Cord prüft rfc anhand der Prüfziffer des Landes des Kunden oder, wenn Sie kein country_code senden, des Landes Ihres Kontos: RFC in Mexiko, NIF/NIE/CIF in Spanien, EIN in den Vereinigten Staaten, CNPJ oder CPF in Brasilien, NIT in Kolumbien, CUIT in Argentinien, RUT in Chile, RUC in Peru, SIREN, SIRET oder TVA in Frankreich, USt-IdNr. oder Steuernummer in Deutschland, VAT oder UTR im Vereinigten Königreich und Business Number in Kanada. Eine Nummer, die die Prüfung nicht besteht, antwortet mit 422, code: "invalid_tax_id" und einem Grund, der die lokale Nummer benennt. Beim Aktualisieren wird nur geprüft, wenn Sie die Nummer oder das Land ändern: Ein alter Wert hindert Sie nicht daran, Telefon oder E-Mail zu korrigieren.

Dokumentsprache

language ist die Sprache, in der der Kunde seine Angebote, Rechnungen, PDFs, E-Mails und Links erhält: es, en, pt, fr oder de; null bedeutet die Ihrer Organisation. Sie wird beim Anlegen und beim Aktualisieren gesendet. Bei PATCH bleibt sie erhalten, wenn Sie sie weglassen, und null oder eine leere Zeichenkette setzt sie auf die Ihrer Organisation zurück. Jeder andere Wert antwortet mit 400, code: "invalid_request" und field: "language". Eine Änderung schreibt bereits Gesendetes nicht um: Jedes Angebot und jede Rechnung behält die Sprache, in der es gesendet oder ausgestellt wurde.

Kunden suchen

q sucht in Firma, Kontakt, E-Mail und RFC. email sucht die exakte E-Mail-Adresse ohne Unterscheidung von Groß- und Kleinschreibung; so vermeiden Sie Duplikate, bevor Sie einen Kunden aus einem anderen Tool anlegen.

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

Einen Kunden abrufen

GET /api/v1/clientes/{id} gibt dasselbe Objekt zurück wie die Liste. Eine ID einer anderen Organisation antwortet mit 404.

Einen Kunden aktualisieren

PATCH /api/v1/clientes/{id} ändert nur die Felder, die Sie senden: empresa, contacto, email, telefono, rfc, terminos, country_code und language. Alles andere bleibt erhalten. Kreditlimit, Stufe und Rabatt lassen sich über diesen Endpoint nicht ändern, auch wenn Sie sie senden. Erfordert einen Schlüssel mit Schreibberechtigung.

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

Jede Änderung löst das Ereignis client.updated aus.