Prenda il traffico. Tenga il suo marchio.
Tutto il nostro catalogo di eSIM da viaggio sta dietro una sola API REST. Acquisti al prezzo di ingrosso, venda al suo prezzo e lasci a noi la consegna, il monitoraggio del consumo e la gestione dei rimborsi. L’integrazione richiede un pomeriggio.
La sandbox è gratuita: provi un ordine dall’inizio alla fine prima di passare in produzione.
curl -X POST https://api.cotaesim.com/partner/v1/orders \
-H "Authorization: Bearer $COTA_TOKEN" \
-H "Idempotency-Key: PO-2026-00931" \
-H "Content-Type: application/json" \
-d '{ "planSlug": "fr-7d-1gb", "quantity": 2 }'
{
"orderId": "por_7f3a…",
"status": "completed",
"unitPriceCents": 499,
"requestedQuantity": 2,
"fulfilledCount": 2,
"esims": [
{ "esimId": "esim_1a2b…",
"lpa": "LPA:1$smdp.example.com$ABC-123-XYZ",
"universalLink": "https://esimsetup.apple.com/…",
"qrUrl": "/partner/v1/esims/esim_1a2b…/qr.png" }
]
}- SandboxStessi endpoint della produzione, saldo separato, eSIM di test
- Una chiamataOrdine, consegna e QR in una sola risposta
- WebhookEventi firmati, otto livelli di ritentativo
- MobileSegua i suoi ordini dal telefono
Quattro passaggi fino alla prima vendita
- 01
Ottenga le sue credenziali
Apriamo per lei un account partner. Scambi
clientIdeclientSecretcon un token di accesso valido 24 ore; i token sono opachi, quindi la revoca è immediata quando le serve. - 02
Provi tutto in sandbox
La sandbox espone gli stessi endpoint, le stesse convalide e gli stessi codici di errore della produzione. Le sole differenze: attinge a un saldo separato e restituisce una eSIM di test. Così completa l’integrazione senza spendere nulla.
- 03
Richieda il passaggio in produzione
Richieda l’accesso in produzione con un solo pulsante nel portale. Abilitiamo l’account e le sue credenziali di produzione passano dallo stesso percorso di codice: l’unica cosa che cambia è una variabile d’ambiente.
- 04
Configuri il conto e venda
Due modi di operare: saldo prepagato oppure un limite di credito concordato. In entrambi i casi ogni ordine viene addebitato nel momento in cui arriva e ogni movimento è scritto in un registro a sola aggiunta: vede quanto ha speso senza attendere l’estratto conto di fine mese.
Quello che il settore offre di solito e quello che facciamo noi
La maggior parte delle righe qui sotto non crea problemi la prima settimana: fa male al sesto mese. Le abbiamo risolte in partenza.
Ambiente di test
Prassi comune nel settoreLa sandbox manca o si comporta diversamente dalla produzione, quindi lei collauda l’integrazione con denaro reale.
COTA Partner APILa sandbox percorre lo stesso codice della produzione: stesse convalide, stessi codici di errore, saldo separato. L’ambiente fa parte della chiave di idempotenza, quindi un ordine di sandbox non può mai ripercuotersi su una richiesta di produzione.
Consegna parziale
Prassi comune nel settoreNe ha ordinati dieci, ne sono arrivati sette. Il denaro degli altri tre resta da qualche parte e lei apre un ticket di assistenza.
COTA Partner APIOgni unità non consegnata viene riaccreditata sul suo saldo nella stessa transazione. La risposta riporta
requestedQuantityefulfilledCountseparatamente: nessuna congettura.Richieste ripetute
Prassi comune nel settoreUn nuovo tentativo dopo un timeout crea un secondo ordine e un secondo addebito.
COTA Partner APIInvii una
Idempotency-Key: la stessa chiave restituisce la risposta originale, mai un secondo addebito. Se due richieste arrivano insieme, una prende il blocco e l’altra lo attende.Guasto di un fornitore
Prassi comune nel settoreQuando un fornitore cade, l’ordine semplicemente fallisce e nessuno le spiega perché.
COTA Partner APIA fronte di un rifiuto certo passiamo automaticamente a un fornitore di riserva. Se invece non abbiamo ricevuto alcuna risposta NON passiamo, deliberatamente, e segniamo la riga come incerta: acquistare due volte la stessa unità costa a lei quanto a noi.
Visibilità del conto
Prassi comune nel settoreUn estratto conto di fine mese. Tutto ciò che sta in mezzo è una scatola nera.
COTA Partner APIUn registro a sola aggiunta: ogni addebito e ogni accredito, con la relativa causa, leggibile subito da
GET /ledger. Può operare in prepagato o con un limite di credito concordato: in entrambi i casi i conti di produzione e sandbox restano separati.Consegna degli eventi
Prassi comune nel settoreIl polling. Continua a chiedere se l’ordine si è mosso.
COTA Partner APIWebhook firmati. Gli eventi vengono scritti dentro la transazione di business, quindi un ordine non può chiudersi perdendo la notifica. Se non riusciamo a raggiungerla riproviamo su otto intervalli crescenti e le inviamo un’e-mail se il suo endpoint viene segnato come non integro.
Rimborsi
Prassi comune nel settoreScambi di e-mail e un’attesa senza scadenza. Non sa mai a che punto sia la richiesta.
COTA Partner APIApra una RICHIESTA di rimborso tramite API e la segua con
GET /refunds. All’approvazione l’accredito viene scritto nella stessa transazione del cambio di stato: «approvato ma non pagato» è strutturalmente impossibile.Controllo quotidiano
Prassi comune nel settoreUna dashboard da scrivania. La visibilità finisce quando esce dall’ufficio.
COTA Partner APIAcceda alla nostra app mobile con lo stesso account, passi al lato partner e segua ordini, eSIM e registro dal telefono.
| Prassi comune nel settore | COTA Partner API | |
|---|---|---|
| Ambiente di test | La sandbox manca o si comporta diversamente dalla produzione, quindi lei collauda l’integrazione con denaro reale. | La sandbox percorre lo stesso codice della produzione: stesse convalide, stessi codici di errore, saldo separato. L’ambiente fa parte della chiave di idempotenza, quindi un ordine di sandbox non può mai ripercuotersi su una richiesta di produzione. |
| Consegna parziale | Ne ha ordinati dieci, ne sono arrivati sette. Il denaro degli altri tre resta da qualche parte e lei apre un ticket di assistenza. | Ogni unità non consegnata viene riaccreditata sul suo saldo nella stessa transazione. La risposta riporta requestedQuantity e fulfilledCount separatamente: nessuna congettura. |
| Richieste ripetute | Un nuovo tentativo dopo un timeout crea un secondo ordine e un secondo addebito. | Invii una Idempotency-Key: la stessa chiave restituisce la risposta originale, mai un secondo addebito. Se due richieste arrivano insieme, una prende il blocco e l’altra lo attende. |
| Guasto di un fornitore | Quando un fornitore cade, l’ordine semplicemente fallisce e nessuno le spiega perché. | A fronte di un rifiuto certo passiamo automaticamente a un fornitore di riserva. Se invece non abbiamo ricevuto alcuna risposta NON passiamo, deliberatamente, e segniamo la riga come incerta: acquistare due volte la stessa unità costa a lei quanto a noi. |
| Visibilità del conto | Un estratto conto di fine mese. Tutto ciò che sta in mezzo è una scatola nera. | Un registro a sola aggiunta: ogni addebito e ogni accredito, con la relativa causa, leggibile subito da GET /ledger. Può operare in prepagato o con un limite di credito concordato: in entrambi i casi i conti di produzione e sandbox restano separati. |
| Consegna degli eventi | Il polling. Continua a chiedere se l’ordine si è mosso. | Webhook firmati. Gli eventi vengono scritti dentro la transazione di business, quindi un ordine non può chiudersi perdendo la notifica. Se non riusciamo a raggiungerla riproviamo su otto intervalli crescenti e le inviamo un’e-mail se il suo endpoint viene segnato come non integro. |
| Rimborsi | Scambi di e-mail e un’attesa senza scadenza. Non sa mai a che punto sia la richiesta. | Apra una RICHIESTA di rimborso tramite API e la segua con GET /refunds. All’approvazione l’accredito viene scritto nella stessa transazione del cambio di stato: «approvato ma non pagato» è strutturalmente impossibile. |
| Controllo quotidiano | Una dashboard da scrivania. La visibilità finisce quando esce dall’ufficio. | Acceda alla nostra app mobile con lo stesso account, passi al lato partner e segua ordini, eSIM e registro dal telefono. |
La sua operatività in tasca
Il lato partner non è solo da scrivania. Acceda all’app COTA E-SIM con la sua e-mail da partner e comparirà l’opzione «passa all’account partner»: la sua vista commerciale vive nella stessa app.
Visibile solo alle persone che invita
Se la sua e-mail non è quella di un utente partner registrato, l’app non mostra alcun pulsante partner né alcun indizio che esista. Per un cliente comune non è cambiato nulla.
Fatto per seguire, non per vendere
Il lato mobile è di sola lettura per scelta: le azioni irreversibili come creare un ordine o rigenerare le credenziali restano nel portale e nell’API. Un tocco sbagliato sul telefono non può spendere denaro.
Identico su iOS e Android
Le stesse schermate nello stesso ordine su entrambe le piattaforme: quale telefono usi il suo team non diventa mai una differenza di formazione.
Accesso aperto su invito
Invita un collega per e-mail e l’account si attiva solo quando quella persona conferma il link nella propria casella. Un indirizzo scritto male non apre alcuna porta.
Le stesse schermate sono nel portale web su partner.cotaesim.com: credenziali, impostazioni dei webhook e richiesta di passaggio in produzione si trovano lì.
Una superficie che impara in un pomeriggio
Meno di venti endpoint in tutto: autenticazione, catalogo, ordini, ciclo di vita delle eSIM, movimenti di conto e webhook. Condividono tutti lo stesso schema di autenticazione, lo stesso contratto di errore e la stessa impaginazione: imparato uno, imparati tutti.
- Gli errori applicativi restituiscono 422 con un
codeleggibile da una macchina; 429 significa limite di frequenza e nulla di più. - Ordine, consegna e QR arrivano in una sola risposta: nessuna seconda chiamata da attendere.
- Ogni endpoint si comporta in modo identico con credenziali sandbox e di produzione.
Ogni endpoint, il suo schema di richiesta e risposta e il catalogo completo degli errori sono nel riferimento OpenAPI: un documento vivo su cui può provare le chiamate.
Apri il riferimento API completoLe domande che ci fanno
Il prezzo al pubblico lo decido io?
Sì. Le vendiamo al prezzo di ingrosso; quanto far pagare al suo cliente è una sua scelta. L’importo che vede nel catalogo è quello che addebiteremo a lei.
Posso vendere con il mio marchio?
Sì: l’API restituisce i dati di consegna grezzi (stringa LPA, link universale iOS, immagine QR). Li presenta nella sua app, nella sua e-mail, con il suo design. Il suo cliente non ci vede mai.
Prepagato o a credito?
Sono disponibili entrambi. In prepagato, quanto ricarica viene addebitato nel momento in cui arriva un ordine, e quando si esaurisce nessun ordine viene creato: nessun debito si accumula alle sue spalle. A credito può scendere sotto zero fino a un limite concordato; quale modalità le si applica è definito sul suo conto e GET /balance glielo comunica. Il credito vale solo per il conto di produzione: la sandbox lavora sempre con il proprio saldo di test. In entrambe le modalità viene avvisato quando si avvicina alla soglia.
I rimborsi sono automatici?
No, per scelta. POST /refunds apre soltanto una RICHIESTA; decide il nostro team. Nel momento in cui viene approvata, l’accredito è scritto nel suo registro nella stessa transazione del cambio di stato, e la motivazione resta allegata alla richiesta.
La sandbox è davvero identica alla produzione?
Stessi endpoint, stesse regole di convalida, stessi codici di errore, stessi eventi webhook. Le differenze: attinge a un saldo separato e restituisce una eSIM di test che punta a un dominio di test. Nessuna linea reale viene attivata.
Possono accedere più persone del mio team?
Sì. Inviti quanti utenti vuole nel portale e sul lato mobile; l’accesso avviene con e-mail e codice monouso, senza password. Ogni invito resta inattivo finché il destinatario non lo conferma dalla propria casella.
E se non ho un team tecnico?
Il portale fa a schermo quasi tutto quello che fa l’API: catalogo, storico ordini, dettagli delle eSIM, registro e richieste di rimborso. Può iniziare a operare senza scrivere una riga contro l’API.
Parliamone e le mostriamo il catalogo
Prepariamo il suo listino e apriamo le sue credenziali sandbox, così può provare l’integrazione con i suoi tempi. Il passaggio in produzione è un pulsante, quando sarà pronto.