Conventions

Voir aussi : Authentification · Catalogue et commandes · README

#Requêtes

• URL de base : https://b2b.cardv.net/api/v1 (Live) ou https://sandbox.cardv.net/api/v1 (Sandbox).
• Les chemins ne se terminent pas par une barre oblique. Écrivez /api/v1/orders, et non /api/v1/orders/.
• Envoyez les corps JSON en UTF-8, avec Content-Type: application/json.
• Envoyez les montants sous forme de chaînes, par exemple "9.2500". Vous évitez ainsi les erreurs d'arrondi.
• Définissez un User-Agent explicite, par exemple AcmeShop-CardV/1.4.

#Montants et dates

• Un montant est une chaîne à 4 décimales, par exemple "merchant_price": "9.2500".
• Lisez-le avec un type décimal, jamais avec un nombre à virgule flottante.
• Vous payez dans la devise de votre portefeuille (default_currency dans GET/account, actuellement USD).
• face_currency est la devise inscrite sur la carte. Elle peut être différente de celle de votre portefeuille.
• Utilisez toujours merchant_price pour calculer vos coûts. Les libellés comme price_label servent uniquement à l'affichage.
• Toutes les dates sont en UTC au format ISO 8601, par exemple 2026-09-29T08:15:30.123456Z.
• Utilisez un vrai analyseur ISO 8601 : le nombre de décimales des secondes peut varier.
• X-Timestamp, utilisé pour la signature, est l'heure Unix en secondes.

#Identifiants

• Enregistrez les identifiants sous forme de texte, sans chercher à les décomposer. Ils peuvent s'allonger.
• Les commandes ont aussi un id numérique. Ne l'utilisez pas : utilisez order_id.
• Pour votre numéro de commande, n'utilisez que A–Z a–z 0–9 - _ ..

#Pagination

Seul GET/skus est paginé. Envoyez limit et offset :

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

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

• limit vaut 100 par défaut, 500 au maximum. Une valeur plus grande est ramenée à 500.
• count est le nombre total de résultats. Continuez jusqu'à ce que offset atteigne count.
• Un limit ou un offset négatif ou non numérique renvoie HTTP 400.
• Une valeur de filtre inconnue renvoie une liste vide, et non une erreur.

#Limite de requêtes

• Par défaut, la limite est de 60 requêtes par minute pour l'ensemble de votre compte. Toutes vos clés et tous les utilisateurs du Portail la partagent. Votre formule peut prévoir une autre valeur.

• La minute commence à :00 à l'horloge. Les requêtes refusées comptent aussi.

• Au-delà de la limite, vous recevez HTTP 429 et un en-tête Retry-After (nombre de secondes à attendre) :

  JSONCopy

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

• Pour rester sous la limite : mettez la liste des SKU en cache, préférez les webhooks à des interrogations trop fréquentes, et attendez un peu plus longtemps après chaque 429.

#Erreurs

Vérifiez toujours d'abord le code HTTP, puis lisez le corps JSON. C'est la clé du corps qui indique le problème. Ne vous fiez pas au texte du message.

Les erreurs d'authentification, de droits, de ressource introuvable et de limite de requêtes utilisent detail :

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

Les erreurs de commande et de prix indiquent le champ concerné :

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

Une ligne de commande mal formée est signalée ligne par ligne, à la même position que dans votre items :

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

Quelques erreurs ne sont pas au format JSON :

• Un HTTP 403 avec un simple texte comme error code: 1010 vient du service réseau placé devant CardV. Votre requête n'est jamais arrivée jusqu'à CardV. Envoyez à CardV l'IP de votre serveur et votre User-Agent.
• Un chemin inconnu (404) ou une erreur de proxy (5xx) peut renvoyer du HTML.

Quand vous journalisez des erreurs, n'y mettez jamais de clés API, de signatures ni de codes.

#Codes HTTP

Pour POST/orders, ne réessayez qu'avec le même corps et le même numéro de commande. Voir les renvois sans risque.

#Réponses

• brand_logo_url et image_url sont des URL complètes d'images hébergées par CardV, ou "". Elles sont publiques et peuvent être mises en cache.
• Les champs de commande invoice_url et delivery_file_url sont des chemins comme /orders/O-00001234/invoice, ou "" s'il n'y a encore rien. Ils sont réservés au Portail : avec une clé API, ils renvoient HTTP 403. Ouvrez les factures et les fichiers CSV de codes dans le Portail.

#Compatibilité

• Ignorez les champs que vous ne connaissez pas. CardV ajoute des champs sans changer de version d'API.
• De nouveaux statuts peuvent apparaître. Considérez un statut inconnu comme « pas encore terminée ».
• Ne dépendez ni de l'ordre des clés JSON ni du texte des messages.