Produkte

Befüllen Sie Ihren Leistungskatalog und stellen Sie Bestände sicher in Ihren Frontends bereit.

Überblick

Das Objekt Product enthält die Einträge Ihrer Preisliste (SKU, Name, Grundpreis und Einheit). Die Produkte-API von Cord ist so sicher, dass Sie sie nicht nur von Ihren internen Servern aus nutzen können, sondern auch direkt im Browser Ihrer Kunden.

Ein Produkt anlegen

Verwenden Sie Ihren geheimen API-Schlüssel (sk_), um den Katalog in großem Umfang zu befüllen. Ideal für nächtliche Integrationen oder Webhooks aus Warenwirtschaftssystemen.

Anfrage:

curl -X POST "https://cordhq.app/api/v1/productos" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -d '{
       "sku": "LIC-PRO-24",
       "nombre": "Professional Annual License",
       "unidad": "license",
       "precio": 12000,
       "activo": true
     }'

Erfolgreiche Antwort:

{
  "data": {
    "id": "7e3c9a1f-2b4d-4c6e-8f0a-b1d3e5f7a9c2"
  }
}

Optionale Felder für Steuer und Rechnungsstellung

Feld	Bedeutung	Validierung
`tax_rate`	Die Steuer, die das Produkt beim Hinzufügen zu einem Angebot oder einer Rechnung vorschlägt, als Bruchzahl (`0.08` = 8 %). Ohne Angabe verwendet die Position Ihren Standardsatz.	Muss ein Satz aus Ihrem Steuerkatalog sein (oder `0`); sonst `400`.
`clave_sat`	Produkt- oder Dienstleistungsschlüssel des SAT (c_ClaveProdServ) für den CFDI in Mexiko.	8 Ziffern (`81111500`); sonst `400`.
`clave_unidad_sat`	Einheitenschlüssel des SAT (c_ClaveUnidad). Ohne Angabe wird er beim Stempeln aus `unidad` abgeleitet (`hora` → `HUR`).	1 bis 3 Buchstaben oder Ziffern (`E48`), wird in Großbuchstaben gespeichert; sonst `400`.

In der Liste kommen sie als taxRate, claveSat und claveUnidadSat zurück (null, wenn nicht zugewiesen).

Produkte auflisten und Datensicherheit

Die Listen-API (GET /api/v1/productos) verfügt über eine dynamische Maskierung (Dynamic Masking), die sich nach der Vertrauensstufe des API-Schlüssels richtet, mit dem Sie sich authentifizieren.

Wenn Sie einen geheimen Schlüssel (sk_) verwenden: Cord geht davon aus, dass Sie ein vertrauenswürdiges internes System sind, und gibt das vollständige Objekt zurück, einschließlich der internen Kosten und Gewinnmargen (costo).

Wenn Sie einen öffentlichen Schlüssel (pk_) verwenden: Öffentliche Schlüssel sind im Browser sichtbar (zum Beispiel, um eine Preisliste auf einer öffentlichen React-Website darzustellen). Cord geht von einem Risiko aus und entfernt das Feld costo automatisch aus allen Ergebnissen im Speicher, bevor das JSON serialisiert wird. So gelangen Ihre Margen nie ins öffentliche Frontend.

curl -X GET "https://cordhq.app/api/v1/productos?limit=50" \
     -H "Authorization: Bearer pk_live_yX..."

Mit sk_live_... enthält dasselbe Produkt costo:

{ "data": [ { "id": "7e3c9a1f-2b4d-4c6e-8f0a-b1d3e5f7a9c2", "sku": "LIC-PRO-24", "nombre": "Professional Annual License", "unidad": "license", "precio": 12000, "costo": 4000, "activo": true, "taxRate": null, "claveSat": "43231500", "claveUnidadSat": null } ] }

Mit pk_live_... erscheint costo im Objekt schlicht nicht (es kommt weder als null noch als 0 – der Schlüssel existiert nicht):

{ "data": [ { "id": "7e3c9a1f-2b4d-4c6e-8f0a-b1d3e5f7a9c2", "sku": "LIC-PRO-24", "nombre": "Professional Annual License", "unidad": "license", "precio": 12000, "activo": true, "taxRate": null, "claveSat": "43231500", "claveUnidadSat": null } ] }

Hinweis: Ein öffentlicher Schlüssel kann nur auf vier Routen verwendet werden: GET /api/v1/productos, POST /api/v1/cotizaciones, GET /api/v1/elements/config und POST /api/v1/elements/ai-draft. Jede andere Route (Produkte anlegen, Kunden lesen, Forderungsmanagement) antwortet mit 403 insufficient_scope. Außerdem ist ein Header Origin oder Referer erforderlich, der zu den erlaubten Domains Ihrer Organisation passt; diese konfigurieren Sie unter Einstellungen › Einbettbarer Angebotsrechner. Ein pk_live_-Schlüssel ohne konfigurierte Domains antwortet mit 403 origin_allowlist_required; ein pk_test_-Schlüssel funktioniert von jedem Ursprung aus.