Angebote

Das transaktionale Herzstück von Cord. Erstellen Sie Angebote, erhalten Sie ihre öffentlichen Links und verwalten Sie sie.

Überblick

Das Objekt Quote (cotizacion) stellt ein kaufmännisches Angebot an einen Kunden dar. Mit der Cord-API können Sie Angebote direkt aus einem ERP oder CRM einspielen oder automatisierte Abläufe für Warenkörbe erstellen.

Alle über die API erzeugten Angebote werden im Audit-Log (audit_log) erfasst und automatisch als von Ihrem API-Schlüssel stammend gekennzeichnet.

Ein Angebot erstellen

Um einen Angebotsentwurf zu erstellen, senden Sie POST /api/v1/cotizaciones mit den kaufmännischen Details.

Anfrage:

curl -X POST "https://cordhq.app/api/v1/cotizaciones" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -d '{
       "cliente_id": "8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b",
       "terminos": "net30",
       "vigencia_dias": 15,
       "notas": "Annual project",
       "base_currency": "EUR",
       "items": [
         {
           "descripcion": "Annual license — Pro plan",
           "cantidad": 12,
           "precio_unitario": 500
         }
       ]
     }'

Jede Position in items erfordert descripcion, cantidad und precio_unitario – die Feldnamen bleiben unabhängig von der Sprache der Anfrage spanisch, da sie das kanonische Schema der API bilden. producto_id ist optional (es verweist auf ein Produkt aus Ihrem Katalog, um dessen Namen und Listenpreis zu übernehmen), und mit precio_negociado erfassen Sie einen rabattierten Preis, der vom Listenpreis abweicht. Ein Feld sku gibt es nicht: Um eine Position mit einem Produkt zu verknüpfen, verwenden Sie dessen producto_id.

Felder des Angebots

Feld	Details
`items`	Pflichtfeld. Die Positionen (siehe nächste Tabelle).
`cliente_id` oder `cliente`	Ein Kunde aus Ihrem Verzeichnis oder die Daten, um ihn anzulegen (`empresa` sowie optional `email`, `contacto`, `telefono`, `rfc` und `fiscal`).
`terminos`	`contado`, `net7`, `net15`, `net30`, `net45`, `net60` oder `net90` (N Kalendertage). Ohne Angabe gelten die Bedingungen des Kunden oder die Ihres Kontos.
`vigencia_dias`	Tage, die das Angebot ab dem Versand gültig ist.
`notas`	Hinweise für den Kunden.
`base_currency`	Verkaufswährung (ISO 4217).
`fiscal_currency`	Buchungswährung; weicht sie von der Verkaufswährung ab, weist die Rechnung den Wechselkurs aus.
`iva_incluido`	`true`, wenn die Preise die Steuer bereits enthalten.
`descuento`	Dokumentrabatt vor Steuern: `{ "tipo": "porcentaje", "valor": 10 }` oder `{ "tipo": "monto", "valor": 2500 }`. Cord berechnet den Betrag und verteilt ihn auf die Positionen; ein Festbetrag wird auf die Zwischensumme begrenzt. `null` entfernt ihn. Siehe Rabatte und Gutscheine.
`cupon`	Der Code eines Gutscheins Ihres Kontos (zum Beispiel `"WELCOME10"`). Cord prüft Gültigkeit, Währung und Nutzungen; ist er angegeben, hat er Vorrang vor `descuento`.
`send`	`true`, um das Angebot beim Erstellen zu senden. Nur mit geheimem Schlüssel.

Feld der Position	Details
`descripcion`, `cantidad`, `precio_unitario`	Pflichtfelder.
`producto_id`	Produkt aus dem Katalog.
`precio_negociado`	Endpreis der Position, falls er vom Listenpreis abweicht.
`costo_unitario`	Interne Kosten zur Berechnung der Marge. Der Kunde sieht sie nie.
`tax_rate`	Bruchzahl von 0 bis 1 (`0.16`, nicht `16`), geprüft gegen Ihren Steuerkatalog. `0` bedeutet bewusst steuerfrei.
`exemption_reason`	Nur bei `tax_rate` 0. Spanien: der Befreiungs- oder Nichtsteuerbarkeitsgrund von Verifactu (E1–E6, N1, N2, S2). Übrige EU: der VATEX-Code der E-Rechnung.
`clave_sat`, `clave_unidad_sat`	Nur Mexiko: der Produkt- oder Dienstleistungsschlüssel des SAT (8 Ziffern) und der Einheitenschlüssel dieser Position. Sie haben Vorrang vor denen des Produkts; ein Schlüssel mit ungültigem Format antwortet mit `400`. Außerhalb Mexikos werden sie ignoriert.

curl -X POST "https://cordhq.app/api/v1/cotizaciones" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: quote-order-4471" \
     -d '{
       "cliente_id": "8f7b2c1e-4d3a-4b9f-a6e2-1c5d7e9f0a3b",
       "terminos": "net45",
       "base_currency": "MXN",
       "cupon": "WELCOME10",
       "items": [
         { "descripcion": "Gray cement CPC 30R", "cantidad": 400, "precio_unitario": 245,
           "tax_rate": 0.16, "clave_sat": "30111601", "clave_unidad_sat": "H87" }
       ]
     }'

Mit einem öffentlichen Schlüssel (dem Ihrer Website) ignoriert Cord descuento, precio_negociado und costo_unitario: Der einzige akzeptierte Rabatt ist ein cupon. Ein Gutschein, der nicht existiert, antwortet mit 404 und code: "coupon_no_existe"; ein inaktiver, abgelaufener, aufgebrauchter Gutschein, einer in anderer Währung oder ein kundengebundener ohne Kunde antwortet mit 409 und coupon_inactivo, coupon_vencido, coupon_aun_no_vigente, coupon_agotado, coupon_agotado_cliente, coupon_moneda oder coupon_requiere_cliente.

base_currency ist die Währung, in der der Kunde das Angebot sieht und bezahlt (ISO 4217, z. B. MXN, USD, EUR, GBP). Sie ist optional – lassen Sie sie weg, verwendet Cord die Buchungswährung Ihrer Organisation –, aber die API ist länderunabhängig: Ein Konto in Madrid, Austin oder Bogotá erstellt Angebote in seiner eigenen Währung, ohne zusätzlichen Parameter.

Erfolgreiche Antwort:

Cord gibt die id (UUID) des Angebots, sein öffentliches token und den öffentlichen Link (link_publico) bereits als absolute URL zurück, damit Sie ihn Ihrem Kunden sofort per WhatsApp, SMS oder über einen externen E-Mail-Dienst senden können. Hat Ihre Organisation eine aktive eigene Domain, verwendet der Link diese Domain statt cordhq.app.

{
  "data": {
    "id": "2a9d8e4f-6b1c-4d7a-9e3f-5c8b1a2d4e6f",
    "folio": "COT-00104",
    "token": "9f3b6c2a7e1d4f8b0a5c3e7d1b9f2a46",
    "link_publico": "https://cordhq.app/q/9f3b6c2a7e1d4f8b0a5c3e7d1b9f2a46",
    "needs_approval": false
  }
}

Erfordert das Angebot vor dem Versand eine interne Freigabe (zum Beispiel wegen eines Rabatts über der Schwelle), kommt needs_approval als true zurück, und motivo beschreibt den Grund.

Angebote auflisten

Sie können Ihren Angebotsverlauf paginiert abrufen oder nach Status filtern (zum Beispiel alle gesendeten (sent) oder bezahlten (paid) Angebote).

Anfrage:

curl -X GET "https://cordhq.app/api/v1/cotizaciones?status=paid&limit=10" \
     -H "Authorization: Bearer sk_live_tU..."

Der Wert von status ist der interne Status im Original (Englisch, nie übersetzt): draft, sent, viewed, approved, rejected, expired, paid oder invoiced. Um ein Angebot anhand seiner Nummer zu finden, verwenden Sie folio=COT-00104: Verglichen wird die vollständige Nummer ohne Unterscheidung von Groß- und Kleinschreibung. Um nur die Angebote eines Kunden zu sehen, verwenden Sie cliente_id=<uuid>.

{
  "data": [
    {
      "id": "2a9d8e4f-6b1c-4d7a-9e3f-5c8b1a2d4e6f",
      "folio": "COT-00104",
      "cliente": "Stark Industries",
      "status": "paid",
      "total": 6000,
      "moneda": "MXN",
      "terminos": "Net 30",
      "terminos_codigo": "net30",
      "vigencia": "10 sep 2026",
      "creada": "20 ago 2026",
      "link_publico": "https://cordhq.app/q/9f3b6c2a7e1d4f8b0a5c3e7d1b9f2a46",
      "language": "es"
    }
  ],
  "meta": { "limit": 10, "offset": 0, "total": 1, "next_cursor": null }
}

Datumsangaben und Bedingungen im Anzeigeformat

In der Liste und im Detail kommt terminos als Bezeichnung in der Sprache Ihres Kontos (Sofort fällig oder Contado, Net 45), und vigencia und creada kommen als Anzeigedaten (10. Sept. 2026), nicht als ISO-Datum. Parsen Sie sie nicht: Um das Zahlungsziel zu vergleichen, verwenden Sie terminos_codigo (contado, net7, net15, net30, net45, net60 oder net90), das sich mit der Sprache nicht ändert; für den genauen Zeitpunkt jeder Änderung verwenden Sie created_at aus dem Ereignisverlauf mit object_id.

In der Liste ist link_publico ebenfalls eine absolute URL, genau wie in der Antwort beim Erstellen. Für das Detail eines einzelnen Angebots (Positionen, Ereignisse, Freigabe) verwenden Sie GET /api/v1/cotizaciones/{id}.

language ist die Sprache, in der der Kunde das Angebot erhält: es, en, pt, fr oder de. Das Feld ist schreibgeschützt: Das Angebot übernimmt die Sprache beim Senden vom Kunden oder, wenn er keine hat, von Ihrer Organisation, und eine neue Version behält sie. Solange das Angebot ein Entwurf ist, ist es null. Um es in einer anderen Sprache zu senden, ändern Sie vor dem Senden das language des Kunden.

Das Detail enthält außerdem descuento: null, wenn es keinen gibt, oder den Dokumentrabatt mit seiner Definition, dem Gutschein, aus dem er stammt, und dem berechneten Betrag vor Steuern:

"descuento": { "tipo": "porcentaje", "valor": 10, "cupon": "WELCOME10", "monto": 9800, "moneda": "MXN" }

total enthält den Rabatt bereits.

Positionen mit KI vorschlagen

POST /api/v1/cotizaciones/ia nimmt { "texto": "..." } entgegen (die Bestellung des Kunden, bis zu 6000 Zeichen) und gibt die mit Ihrem Katalog abgeglichenen Positionen zurück, ohne etwas anzulegen:

{ "data": { "moneda": "MXN", "items": [{ "id": "7e3c9a1f-2b4d-4c6e-8f0a-b1d3e5f7a9c2", "nombre": "Gray Cement 50kg", "unidad": "sack", "lista": 185, "negociado": null, "cantidad": 5 }] } }

id ist null, wenn die Position nicht in Ihrem Katalog steht. Die Preise sind in moneda angegeben. Um das Angebot zu erstellen, senden Sie diese Positionen an POST /api/v1/cotizaciones. Erfordert einen Schlüssel mit Schreibzugriff und verbraucht eine KI-Einheit Ihres Tarifs: Sind keine mehr übrig, erhalten Sie 429 mit code: "ai_quota_exceeded"; enthält der Text keine Produkte, 422 mit code: "no_items".

Den Status eines Angebots ändern

Mit einem Schlüssel mit Schreibzugriff (write) können Sie ein Angebot mit POST /api/v1/cotizaciones/{id} durch seinen Lebenszyklus bewegen:

curl -X POST "https://cordhq.app/api/v1/cotizaciones/2a9d8e4f-6b1c-4d7a-9e3f-5c8b1a2d4e6f" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: approve-COT-00104" \
     -d '{ "action": "approve" }'

`action`	Ausgangsstatus	Ergebnis
`send`	`draft`	Sendet das Angebot an den Kunden (E-Mail und Link) in seiner Dokumentsprache, die das Angebot in `language` speichert. Im kostenlosen Tarif verbraucht das einen der monatlichen Versände.
`resend`	`sent`, `viewed`, `expired`	Sendet es erneut an den Kunden.
`approve`	`sent`, `viewed`	Markiert es als bestätigt.
`reject`	`sent`, `viewed`	Markiert es als abgelehnt.
`mark_paid`	`approved`, `invoiced`	Erfasst die Zahlung. Akzeptiert optional `payment_method` (Standard: `transferencia`). Ausstehende Online-Zahlungen für dieses Angebot werden storniert.

Die Antwort lautet { "data": { "ok": true, "status": "approved" } }. Befindet sich das Angebot nicht in einem Status, von dem aus die Aktion möglich ist, oder hat eine andere Anfrage es gleichzeitig geändert, erhalten Sie 409 mit code: "invalid_state", und es wird nichts angewendet. Jede Änderung wird im Audit-Log mit Ihrem Schlüssel als Akteur festgehalten und löst ihr Webhook-Ereignis aus.

Das Ausstellen der Rechnung ist über diese Route nicht möglich: Rechnungen werden mit POST /api/v1/facturas und POST /api/v1/facturas/{id} angelegt und ausgestellt.

Einen Entwurf löschen

DELETE /api/v1/cotizaciones/{id} löscht ein Angebot, das nie gesendet wurde (draft). Jeder andere Status antwortet mit 409.