Passer au contenu principal
Pour encaisser ces commandes par carte sur votre propre site, consultez PapelPay.
La User API (appelée Store API dans votre tableau de bord) donne à vos serveurs le même contrôle que celui dont vous disposez dans le tableau de bord de la boutique : commandes, produits, stock, clients, support, expédition et webhooks. URL de base : https://app.papelship.com/api/v1
Les anciennes intégrations qui appellent https://app.papelship.com/api_user/api/v1 continuent de fonctionner. Utilisez /api/v1 pour tout nouveau code.

S’authentifier

Créez une clé dans Developers › API keys et envoyez-la avec l’identifiant de votre boutique dans chaque requête :
GET /me fonctionne avec n’importe quelle clé valide. Il renvoie la boutique, les autorisations de la clé et vos limites : utilisez-le pour tester votre configuration.
Les clés agissent en tant que propriétaire de la boutique. Conservez-les sur votre serveur, jamais dans du code exécuté dans le navigateur ou dans une application mobile.

Autorisations

Lorsque vous créez une clé, choisissez Full access, Read only ou Custom. Avec Custom, vous choisissez un accès en lecture ou en écriture pour chaque domaine. L’écriture inclut la lecture. Les requêtes GET nécessitent un accès en lecture ; POST, PATCH, PUT et DELETE nécessitent un accès en écriture. Une clé sans l’autorisation requise reçoit 403 INSUFFICIENT_SCOPE, avec l’autorisation manquante dans required_scope. Vous pouvez également limiter une clé à cette boutique, à une liste d’adresses IP ou à une date d’expiration.

Réponses

Chaque réponse est au format JSON et contient un indicateur success.
Succès
Erreur
Basez votre logique sur code, pas sur le message. Chaque réponse comporte un en-tête X-Request-Id ; indiquez-le lorsque vous contactez le support. Consultez Erreurs pour la liste de tous les codes.

Conventions

  • Les montants sont des entiers exprimés en unités mineures : price_cents: 2999 correspond à 29,99.
  • Les dates sont au format ISO 8601 en UTC.
  • Les identifiants sont des identifiants publics : hash ID des produits, identifiants de commande comme c35ffd-19a1b2c3d4e-8c7a20. Les enregistrements d’autres boutiques renvoient 404.
  • Les enregistrements créés renvoient 201.

Pagination

Les listes acceptent limit (de 1 à 100, 25 par défaut) et offset, et renvoient un objet pagination :
Les listes d’affiliés utilisent plutôt un curseur : renvoyez next_cursor dans cursor.

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key lors des appels de création (commandes, remboursements, expéditions, produits, webhooks et autres appels signalés dans la référence). En cas d’échec réseau, réessayez avec la même clé et le même corps : vous récupérez le premier résultat au lieu d’un doublon.
  • Les clés sont conservées pendant 24 heures.
  • Une réponse rejouée comporte l’en-tête Idempotent-Replayed: true.
  • La même clé avec un corps différent renvoie 422 IDEMPOTENCY_KEY_REUSED.

Limites

Au-delà d’une limite, vous recevez 429 avec Retry-After. RATE_LIMITED est levé en moins d’une minute ; STORE_API_MONTHLY_QUOTA_EXCEEDED est réinitialisé le premier jour du mois suivant (UTC). Chaque requête apparaît dans Developers › API requests avec son statut et sa durée.

Étapes suivantes

Créer des commandes

Recevez des commandes depuis votre propre site ou application et redirigez les clients vers le paiement.

Webhooks

Soyez averti lorsque des commandes sont payées, annulées ou remboursées.