De eSIM API integreren

Gebruik de eSIM API om datapakketten aan te schaffen en installatiegegevens vanuit je applicatie te leveren. Je hebt een werkruimte, een API-sleutel en organisatiewalletfondsen nodig voor live-aankopen. Volg authenticatie en gebruik de API-regio die bij je sleutel hoort.

Geef de sleutel esim:read om aanbiedingen en resources te bekijken, en esim:write om te kopen of service te beheren. Installatiecredentials hebben aparte machtigingen: esim_credentials:read om ze op te halen en esim_credentials:write om installatielinks te maken of te versturen. Bewaar de API-sleutel in je serverapplicatie.

1. Kies een aanbod

Lijst aanbiedingen op voor de bestemming en haal de geselecteerde aanbieding op. Controleer zone.countries, de bundel en geldigheid in pricing, snelheidsvoorwaarden en eventuele inbegrepen telefoniedienst. Gebruik voor een bestaande eSIM Lijst compatibele aanbiedingen op; algemene catalogusbeschikbaarheid bepaalt geen top-upcompatibiliteit.

Haal de identificatievereisten van de aanbieding op voordat je abonneegegevens verzamelt. Het antwoord bevat een JSON Schema per dekkingsland, met voornaam, achternaam en e-mailadres als vereiste velden, plus eventuele aanvullende velden. Schakel validatie van e-mail- en datumformaat in. Je verzamelt en valideert deze informatie zelf; de eSIM API ontvangt of verifieert de antwoorden niet, en succesvolle validatie autoriseert geen aankoop.

Haal afrekenmogelijkheden op voor een nieuwe eSIM. Toon de eenmalige prijs of beschikbare terugkerende offerte voordat je de aankoop bevestigt. Afrekenprijzen zijn exclusief belasting. Verlenging heeft een eigen prijs en interval; volg terugkerende pakketten wanneer de klant daarvoor kiest.

Installeer voor het onderstaande eenmalige voorbeeld curl en jq. Stel BIRD_API_URL in op je regionale basis-URL, BIRD_API_KEY op je sleutel en ESIM_OFFER_ID op het geselecteerde aanbiedings-ID:

Codevoorbeeld

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/offers/$ESIM_OFFER_ID/checkout" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  > esim-checkout.json

jq '.one_time' esim-checkout.json

Controleer de prijs en aanbiedingsvoorwaarden voordat je verdergaat. De offerte reserveert geen beschikbaarheid.

2. Maak de aankoop aan

Maak een bestelling aan met offer_id. Laat esim_id weg voor een nieuw profiel; neem het op voor een top-up. Stuur bij een eenmalige aankoop offer_revision en expected_price uit de geaccepteerde offerte mee. Deze velden weigeren gewijzigde voorwaarden met 409 voordat er wordt afgeschreven; haal een nieuwe offerte op en controleer deze voordat je een gewijzigde prijs accepteert.

Stel ESIM_ORDER_KEY in op een unieke waarde voor deze aankoop en sla deze op bij het verzoek. Dit voorbeeld koopt een nieuwe, niet-toegewezen eSIM en kopieert de gepubliceerde prijs zonder het bedrag of de valuta te wijzigen:

Codevoorbeeld

jq '{offer_id, offer_revision: .one_time.offer_revision, expected_price: .one_time.price}' \
  esim-checkout.json > esim-order.json

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/orders" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ESIM_ORDER_KEY" \
  --data-binary @esim-order.json

Neem een werkruimte-subscriber_id op om een nieuw profiel toe te wijzen wanneer de levering is voltooid; volg abonnee-instelling. Een top-up behoudt de bestaande toewijzing, dus laat subscriber_id weg bij het versturen van esim_id. Verstuur installatiegegevens apart na de levering.

Sla het teruggegeven bestel-ID op. Inspecteer status ook na HTTP 201, dat een voltooide of mislukte bestelling kan bevatten. HTTP 202 betekent dat de verwerking verdergaat. Haal de bestelling op totdat deze completed of failed is. Een voltooide bestelling identificeert esim_id en package_id; apparaatinstallatie blijft een aparte stap.

3. Lever installatiegegevens

Lees installatiecredentials na de aankoop, maak een gehoste installatielink aan, of verstuur een link per e-mail of SMS. Houd activeringsgegevens en installatielinks buiten analytics en openbare logs.

Sla bij een verzonden link het bezorg-ID op en controleer de bezorggeschiedenis. Een 202-antwoord bevestigt acceptatie voor verzending; delivered bevestigt aflevering van het bericht, en device-installatie vereist een eigen controle. Volg de installatiegids voor ondersteunde methoden, linkvervaltijd en herstel.

4. Een onderbroken aankoop herstellen

Als het create-antwoord verloren ging of 503 retourneerde, herhaal je het opgeslagen verzoek met de originele Idempotency-Key; zie idempotente verzoeken. Als je het order-ID hebt, lees dan eerst die order. Een nieuwe aankoop aanmaken terwijl de uitkomst onzeker is, kan een extra afschrijving veroorzaken.

Controleer bij een order in charging de waarde van funding en je walletsaldo. funding.required_amount is het totaal benodigde saldo inclusief belasting; vergelijk het met het beschikbare tegoed voordat je geld toevoegt. Eenmalige orders proberen de financiering automatisch opnieuw. Als een eerste terugkerende aankoop wordt geweigerd wegens onvoldoende saldo, voeg je tegoed toe en herhaal je expliciet hetzelfde create-verzoek met de originele sleutel.

Controleer de huidige orderstatus ook na funding.lapses_at: dat tijdstempel garandeert geen annulering. Een order kan alsnog worden voltooid als er tegoed binnenkomt voordat een volgende poging bij onvoldoende saldo de order laat mislukken.

Om een ongewenste, niet-gefinancierde aankoop te stoppen, annuleer je de order. Bij een geslaagde niet-gefinancierde annulering krijg je status: failed en failure_code: canceled terug. Een gefinancierde eenmalige order retourneert 409 en gaat door. Bij een eerste terugkerende aankoop kan betaling die binnenkomt tijdens de annulering ertoe leiden dat de betaalde aankoop doorloopt terwijl toekomstige verlenging stopt. Controleer de geretourneerde order en het abonnement voordat je annulering of terugbetaling rapporteert.

Controleer bij een mislukte aankoop failure_code en failure_reason. Eventuele afschrijvingen worden automatisch gecrediteerd; refund_transaction_id identificeert een uitgegeven credit. Bewaar het order-ID voor ondersteuning als de betaling, levering of het credit onopgelost blijft.

5. Saldi en servicestatus tonen

Haal de eSIM op voor status, installatiestatus, pakketten en available_actions. Toon de tegoed-, verbruiks- en observatietijdgegevens van het pakket met de gebruiksgids. Onbekend verbruik moet onbekend blijven in je applicatie.

Controleer de beschikbaarheid van acties opnieuw wanneer de klant handelt; de operatie controleert rechten en status nogmaals. Gebruik de operatiegids om onvoltooide aankopen, installatieproblemen of connectiviteitsstoringen te onderzoeken.

Volgende stappen

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Ontvang een implementatieoverzicht