Développeurv1

CargaCell API

Le même backend que l'application web est disponible via HTTP. Créez une clé API depuis votre profil et authentifiez vos requêtes serveur à serveur avec l'en-tête x-api-key.

URL de basehttps://www.cargacell.com/api/v1

Obtenir une clé API →

Démarrage rapide

Authentification par clé API

Envoyez votre clé dans l'en-tête x-api-key à chaque requête. Les sessions JWT du navigateur fonctionnent toujours en parallèle pour les clients web.

curl -X GET \
  https://www.cargacell.com/api/v1/auth/me \
  -H "x-api-key: cc_live_your_key"

Comportement de la liste blanche IP

0Toutes les IP sont autorisées — valeur par défaut pour les nouvelles clés.
≥1Seules ces adresses exactes sont acceptées.
RévoquerLa clé cesse de fonctionner immédiatement ; créez-en une nouvelle.

Référence des endpoints

Tous les chemins sont relatifs à l'URL de base ci-dessus.

Les endpoints marqués Web uniquement nécessitent un jeton de session navigateur et rejettent l'authentification x-api-key.

Authentification

Validez la clé et lisez ou mettez à jour le profil du compte courant.

Méthode	Chemin	Description
POST	/auth/login	Connexion par e-mail et mot de passe
GET	/auth/me	Obtenir l'utilisateur authentifié actuel
PATCH	/auth/me	Mettre à jour le profil et les données de facturation

Catalogue et panier

Parcourez les opérateurs et les produits, puis constituez des commandes avant le paiement.

Méthode	Chemin	Description
GET	/catalog/countries	Lister les pays disponibles
GET	/catalog/operators	Lister les opérateurs disponibles
GET	/catalog/recharge-products	Catalogue de recharges avec filtres
GET	/cart	Obtenir le panier actuel
POST	/cart/items	Ajouter un article au panier
DELETE	/cart/items/:itemId	Supprimer un article du panier

Paiements et portefeuille

Calculez les prix et envoyez des recharges avec le solde du portefeuille. Le paiement externe est réservé aux sessions web.

Méthode	Chemin	Description	Tags
POST	/payments/quote	Obtenir un devis de prix
POST	/payments/prepare	Valider les données du paiement web	Web uniquement
POST	/payments/checkout	Finaliser le paiement web externe	Web uniquement
GET	/payments/history	Historique des paiements
GET	/wallet/balance	Solde actuel du portefeuille
POST	/wallet/checkout	Envoyer des recharges financées par le portefeuille
POST	/api-access/b2b/recharges	Recharge B2B dédiée par portefeuille	B2B

Administration

Les comptes administrateurs peuvent utiliser le même mécanisme de clé API pour tous les endpoints back-office.

Méthode	Chemin	Description	Tags
GET	/admin/summary	Résumé du tableau de bord	Admin
GET	/admin/users	Gestion des utilisateurs	Admin
GET	/admin/recharges	Opérations de recharge	Admin
GET	/admin/payments	Opérations de paiement	Admin
GET	/admin/products	Opérations catalogue	Admin

Exemples de code

Exemples en direct reflétant le comportement actuel du backend. Basculez entre Requête et Réponse dans chaque carte.

Vérifier votre clé

Envoyez une requête GET pour confirmer que l'authentification fonctionne et inspecter le compte associé à la clé.

curl -X GET \
  https://www.cargacell.com/api/v1/auth/me \
  -H "x-api-key: cc_live_your_generated_key" \
  -H "Accept-Language: en"

Lister les produits avec les détails promo

Récupérez le catalogue de recharges. Les produits avec des promotions actives ou planifiées incluent les détails complets (nom, description, conditions optionnelles).

curl -X GET \
  "https://www.cargacell.com/api/v1/catalog/recharge-products?country=ES&limit=5" \
  -H "x-api-key: cc_live_your_generated_key" \
  -H "Accept-Language: en"

Ajouter un article au panier

Ajoutez une ligne de destinataire au panier. Récupérez d'abord le catalogue pour résoudre un productId valide.

curl -X POST \
  https://www.cargacell.com/api/v1/cart/items \
  -H "Content-Type: application/json" \
  -H "x-api-key: cc_live_your_generated_key" \
  -d '{
    "sessionId": "agent-session-001",
    "productId": "12345",
    "recipientNumber": "+5355512345",
    "quantity": 2
  }'

Recharge B2B par portefeuille

Endpoint B2B dédié — contourne MONEI entièrement et envoie immédiatement depuis le solde approuvé du portefeuille.

curl -X POST \
  https://www.cargacell.com/api/v1/api-access/b2b/recharges \
  -H "Content-Type: application/json" \
  -H "x-api-key: cc_live_your_generated_key" \
  -d '{
    "items": [
      {
        "productId": "12345",
        "recipientNumber": "+5355512345",
        "quantity": 2
      }
    ],
    "baseCurrency": "EUR"
  }'

Paiement générique par portefeuille

Paiement standard financé par le portefeuille — fonctionne avec les clés API et les sessions web.

curl -X POST \
  https://www.cargacell.com/api/v1/wallet/checkout \
  -H "Content-Type: application/json" \
  -H "x-api-key: cc_live_your_generated_key" \
  -d '{
    "items": [
      {
        "productId": "12345",
        "recipientNumber": "+5355512345",
        "quantity": 1
      }
    ],
    "baseCurrency": "EUR"
  }'

Lister les recharges (admin)

Les clés API admin peuvent appeler les endpoints back-office avec le même en-tête x-api-key.

curl -X GET \
  "https://www.cargacell.com/api/v1/admin/recharges?page=1&limit=20" \
  -H "x-api-key: cc_live_admin_key"

Flux de recharge

Trois chemins d'envoi existent. Choisissez celui qui convient à votre intégration.

Paiement externe

Web uniquement

Le navigateur initie un paiement MONEI via POST /payments/prepare, puis confirme après autorisation via POST /payments/checkout. Nécessite une session JWT web. Les clés API sont rejetées.

Paiement par portefeuille

Appelez POST /wallet/checkout avec vos articles. Le backend calcule le solde disponible à partir des recharges approuvées moins les paiements capturés, et rejette si insuffisant. Fonctionne avec clés API et sessions web.

Recharge B2B par portefeuille

B2B

Appelez POST /api-access/b2b/recharges. Utilise le même moteur que le chemin 2, mais est conçu pour les clients API qui ne doivent jamais interagir avec le flux MONEI. Envoie immédiatement si le solde est suffisant.

Dans tous les chemins financés par portefeuille, un paiement réussi crée des lignes de recharge en file d'attente. Celles-ci sont traitées par le processeur de recharge, ou marquées en liste d'attente lors d'une fenêtre de promotion DT One.

Gestion des clés

Toutes les opérations sur les clés sont disponibles dans Tableau de bord → Profil.

Créer

Créez une clé nommée pour chaque intégration ou environnement. La valeur en clair n'est affichée qu'une seule fois à la création — copiez-la immédiatement.

Restreindre

Ajoutez des entrées à la liste blanche IP pour verrouiller une clé à une infrastructure fixe — passerelles de bureau, serveurs workers ou IPs de sortie de fonctions cloud.

Révoquer

Révoquez immédiatement les clés compromises ou inutilisées. La révocation prend effet instantanément. Ne réutilisez jamais les anciennes clés — générez-en une nouvelle.