Sviluppatorev1

CargaCell API

Lo stesso backend dell'applicazione web è disponibile via HTTP. Crea una chiave API dal tuo profilo e autentica le richieste server-to-server con l'header x-api-key.

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

Ottieni chiave API →

Avvio rapido

Autenticazione con chiave API

Invia la tua chiave nell'header x-api-key ad ogni richiesta. Le sessioni JWT del browser continuano a funzionare in parallelo per i client web.

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

Comportamento whitelist IP

0Qualsiasi IP è consentito — predefinito per le nuove chiavi.
≥1Solo quegli indirizzi esatti sono accettati.
RevocaLa chiave smette di funzionare immediatamente; creane una nuova.

Riferimento endpoint

Tutti i percorsi sono relativi all'URL base indicato sopra.

Gli endpoint con tag Solo web richiedono un token di sessione browser e rifiutano l'autenticazione x-api-key.

Autenticazione

Valida la chiave e leggi o aggiorna il profilo dell'account corrente.

Metodo	Percorso	Descrizione
POST	/auth/login	Accesso con email e password
GET	/auth/me	Ottieni l'utente autenticato corrente
PATCH	/auth/me	Aggiorna profilo e dati di fatturazione

Catalogo e carrello

Sfoglia operatori e prodotti, poi crea ordini prima del pagamento.

Metodo	Percorso	Descrizione
GET	/catalog/countries	Elenca i paesi disponibili
GET	/catalog/operators	Elenca gli operatori disponibili
GET	/catalog/recharge-products	Catalogo ricariche con filtri
GET	/cart	Ottieni il carrello attuale
POST	/cart/items	Aggiungi un articolo al carrello
DELETE	/cart/items/:itemId	Rimuovi un articolo dal carrello

Pagamenti e portafoglio

Calcola prezzi e invia ricariche con il saldo del portafoglio. Il checkout esterno è solo per sessioni web.

Metodo	Percorso	Descrizione	Tag
POST	/payments/quote	Ottieni un preventivo di prezzo
POST	/payments/prepare	Valida gli input del checkout web	Solo web
POST	/payments/checkout	Completa il checkout web esterno	Solo web
GET	/payments/history	Cronologia pagamenti
GET	/wallet/balance	Saldo portafoglio corrente
POST	/wallet/checkout	Invia ricariche finanziate con portafoglio
POST	/api-access/b2b/recharges	Ricarica B2B dedicata tramite portafoglio	B2B

Amministrazione

Gli account admin possono usare lo stesso meccanismo di chiave API per tutti gli endpoint back-office.

Metodo	Percorso	Descrizione	Tag
GET	/admin/summary	Riepilogo dashboard	Admin
GET	/admin/users	Gestione utenti	Admin
GET	/admin/recharges	Operazioni di ricarica	Admin
GET	/admin/payments	Operazioni di pagamento	Admin
GET	/admin/products	Operazioni catalogo	Admin

Esempi di codice

Esempi live che rispecchiano il comportamento attuale del backend. Passa tra Richiesta e Risposta in ogni scheda.

Verifica la tua chiave

Invia una richiesta GET per confermare che l'autenticazione funziona e ispezionare l'account associato alla chiave.

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

Elenca prodotti con dettagli promo

Ottieni il catalogo ricariche. I prodotti con promozioni attive o programmate includono i dettagli completi della promo (nome, descrizione, termini opzionali).

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"

Aggiungi un articolo al carrello

Aggiungi una riga destinatario al carrello. Recupera prima il catalogo prodotti per risolvere un productId valido.

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
  }'

Ricarica B2B tramite portafoglio

Endpoint B2B dedicato — bypassa MONEI completamente e invia immediatamente dal saldo approvato del portafoglio.

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"
  }'

Checkout generico tramite portafoglio

Checkout standard finanziato con portafoglio — funziona con chiavi API e sessioni 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"
  }'

Elenca ricariche (admin)

Le chiavi API admin possono chiamare gli endpoint back-office con lo stesso header 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"

Flussi di ricarica

Esistono tre percorsi di invio. Scegli quello adatto alla tua integrazione.

Checkout con pagamento esterno

Solo web

Il browser avvia un pagamento MONEI via POST /payments/prepare, poi conferma dopo l'autorizzazione via POST /payments/checkout. Richiede una sessione JWT web. Le chiavi API vengono rifiutate.

Checkout tramite portafoglio

Chiama POST /wallet/checkout con i tuoi articoli. Il backend calcola il saldo disponibile dai top-up approvati meno i pagamenti portafoglio acquisiti e rifiuta se insufficiente. Funziona con chiavi API e sessioni web.

Ricarica B2B tramite portafoglio

B2B

Chiama POST /api-access/b2b/recharges. Usa lo stesso motore portafoglio del percorso 2, ma è progettato per client API che non devono mai interagire con il flusso MONEI. Invia immediatamente quando il saldo è sufficiente.

In tutti i percorsi finanziati con portafoglio, un pagamento riuscito crea righe di ricarica in coda. Queste vengono elaborate dal processore di ricarica, o contrassegnate in lista d'attesa quando si applica una finestra promozionale DT One.

Gestione chiavi

Tutte le operazioni sulle chiavi sono disponibili in Dashboard → Profilo.

Crea

Crea una chiave con nome per ogni integrazione o ambiente. Il valore in chiaro viene mostrato solo una volta al momento della creazione — copialo immediatamente.

Limita

Aggiungi voci alla whitelist IP per bloccare una chiave su infrastrutture fisse — gateway d'ufficio, server worker o IP di uscita di funzioni cloud.

Revoca

Revoca immediatamente le chiavi compromesse o inutilizzate. La revoca ha effetto istantaneamente. Non riutilizzare mai le chiavi vecchie — genera invece una nuova.