Grundregeln

Siehe auch: Authentifizierung · Produkte und Bestellungen · Übersicht

#Anfragen

• Basis-URL: https://b2b.cardv.net/api/v1 (Live) oder https://sandbox.cardv.net/api/v1 (Sandbox).
• Pfade haben keinen Schrägstrich am Ende. Also /api/v1/orders, nicht /api/v1/orders/.
• Senden Sie JSON-Bodys in UTF-8 mit Content-Type: application/json.
• Senden Sie Beträge als Text, zum Beispiel "9.2500". So entstehen keine Rundungsfehler.
• Setzen Sie einen aussagekräftigen User-Agent, zum Beispiel AcmeShop-CardV/1.4.

#Beträge und Zeit

• Beträge sind Text mit 4 Nachkommastellen, zum Beispiel "merchant_price": "9.2500".
• Lesen Sie Beträge mit einem Dezimaltyp ein, nie als Gleitkommazahl.
• Sie bezahlen in der Währung Ihrer Wallet (default_currency in GET/account, derzeit USD).
• face_currency ist die Währung, die auf der Karte steht. Sie kann von Ihrer Wallet-Währung abweichen.
• Rechnen Sie Ihre Kosten immer mit merchant_price. Texte wie price_label dienen nur der Anzeige.
• Alle Zeitangaben sind UTC im Format ISO 8601, zum Beispiel 2026-09-29T08:15:30.123456Z.
• Verwenden Sie einen echten ISO-8601-Parser. Die Zahl der Nachkommastellen bei den Sekunden kann schwanken.
• X-Timestamp für die Signatur ist Unix-Zeit in Sekunden.

#IDs

• Speichern Sie IDs als Text und zerlegen Sie sie nicht. Sie können länger werden.
• Bestellungen haben auch eine numerische id. Verwenden Sie sie nicht, sondern order_id.
• Für Ihre Bestellnummer sind nur diese Zeichen erlaubt: A–Z a–z 0–9 - _ ..

#Seitenweise Abfrage

Nur GET/skus liefert Ergebnisse seitenweise. Senden Sie limit und offset:

GET /api/v1/skus?limit=100&offset=200

{"count": 1234, "limit": 100, "results": ["..."], "filter_options": {}}

• limit ist standardmäßig 100, höchstens 500. Größere Werte werden auf 500 gesenkt.
• count ist die Gesamtzahl der Treffer. Fragen Sie weiter ab, bis offset den Wert count erreicht.
• Ein negativer oder nicht numerischer Wert für limit oder offset führt zu HTTP 400.
• Ein unbekannter Filterwert liefert eine leere Liste, keinen Fehler.

#Anfragelimit

• Standard sind 60 Anfragen pro Minute für Ihr gesamtes Konto. Alle Ihre Keys und Portal-Nutzer teilen sich dieses Limit. Ihre Kontostufe kann einen anderen Wert festlegen.

• Die Minute beginnt jeweils bei :00 auf der Uhr. Abgelehnte Anfragen zählen mit.

• Über dem Limit erhalten Sie HTTP 429 und einen Retry-After-Header (Wartezeit in Sekunden):

  JSONCopy

  {"detail": "Merchant API rate limit exceeded. Expected available in 23 seconds."}

• So bleiben Sie unter dem Limit: Speichern Sie die SKU-Liste zwischen, nutzen Sie Webhooks statt häufiger Abfragen, und warten Sie nach jedem 429 etwas länger.

#Fehler

Prüfen Sie immer zuerst den HTTP-Status. Lesen Sie dann den JSON-Body. Der Schlüssel im Body sagt Ihnen, was schiefging. Verlassen Sie sich nicht auf den Meldungstext.

Fehler bei Authentifizierung, Berechtigung, nicht gefundenen Daten und Anfragelimit stehen unter detail:

{"detail": "Order not found."}

Fehler bei Bestellung und Preisabfrage nennen das betroffene Feld:

{"balance": "Insufficient available balance."}

Eine fehlerhafte Bestellposition wird pro Position gemeldet, an derselben Stelle wie in Ihren items:

{"items": [{}, {"quantity": ["Ensure this value is greater than or equal to 1."]}]}

Einige Fehler kommen nicht als JSON:

• HTTP 403 mit reinem Text wie error code: 1010 stammt vom Netzwerk-Edge vor CardV. Ihre Anfrage ist gar nicht bei CardV angekommen. Schicken Sie CardV Ihre Server-IP und Ihren User-Agent.
• Ein unbekannter Pfad (404) oder ein Proxy-Fehler (5xx) kann HTML zurückgeben.

Protokollieren Sie beim Loggen von Fehlern nie API-Keys, Signaturen oder Codes.

#HTTP-Statuscodes

Senden Sie POST/orders nur mit demselben Body und derselben Bestellnummer erneut. Siehe sicheres erneutes Senden.

#Antworten

• brand_logo_url und image_url sind vollständige URLs zu Bildern, die CardV bereitstellt, oder "". Sie sind öffentlich und dürfen zwischengespeichert werden.
• Die Bestellfelder invoice_url und delivery_file_url sind Pfade wie /orders/O-00001234/invoice oder "", solange es noch nichts gibt. Sie funktionieren nur im Portal: Mit einem API-Key liefern sie HTTP 403. Rechnungen und CSV-Dateien mit Codes öffnen Sie im Portal.

#Kompatibilität

• Ignorieren Sie Felder, die Sie nicht kennen. CardV ergänzt Felder ohne neue API-Version.
• Es können neue Statuswerte hinzukommen. Behandeln Sie einen unbekannten Status als „noch nicht fertig“.
• Verlassen Sie sich nicht auf die Reihenfolge der JSON-Schlüssel oder den Wortlaut von Meldungen.