API v1

Վաճառեք eSIM ձեր բրենդով

Կատալոգ՝ 200+ երկիր և տարածաշրջան։ Ձեզանից միայն թողարկման հարցումն է․ պատասխանում անմիջապես գալիս է ձեր հաճախորդի eSIM-ի էջի հղումը և գինը, որով այն պետք է վաճառել։ Տեղադրումը, աջակցությունը և լիցքավորումը մեզ վրա են։ Ոչ մի պայմանագիր օպերատորների հետ և ոչ մի սեփական բիլինգ։

200+

ուղղություն կատալոգում

1

թողարկման հարցում՝ այն ամենը, ինչ պետք է ձեզանից

$0

արժե ավազարկղը

1. Ինչպես է այն աշխատում

  1. Ձեր հաճախորդը eSIM-ը գնում է ձեզանից՝ կայքում, հավելվածում կամ գրասենյակում, վաճառքի այն գնով, որը մենք տալիս ենք կատալոգում (sale_price)։

  2. Ձեր ծրագիրն ուղարկում է մեկ հարցում՝ POST /orders։ Մենք ձեր դրամապանակից գանձում ենք ձեր գինը (price) և անմիջապես պատասխանում ենք link հղումով։

  3. Դուք հղումը տալիս եք հաճախորդին՝ նամակով, մեսենջերով, էկրանին։ Քանի դեռ պրոֆիլը թողարկվում է, էջը գրում է «պատրաստվում է», հետո ցույց է տալիս QR կոդը և հրահանգը։

  4. Մնացածը մեր կողմում է՝ տեղադրում, աջակցություն նույն էջի չատում, տրաֆիկի լիցքավորում։ Իր eSIM-ի վերաբերյալ ցանկացած հարցով հաճախորդը գրում է մեզ։

sale_price-ի և price-ի տարբերությունը ձեր եկամուտն է։ Երկու գներն էլ սահմանում ենք մենք՝ ձեզ հետ համաձայնությամբ․ ձեր կողմում ոչինչ հաշվել պետք չէ։

2. Ինչից սկսել

Թողեք հայտ, և մենք ձեզ մուտք կտանք կոնսոլ։ Բանալիները թողարկում եք ինքներդ՝ «Բանալիներ» էջում․ սկսեք ավազարկղից, աշխատանքայինը թողարկեք, երբ ինտեգրացիան պատրաստ է։ Բանալին ցուցադրվում է միայն մեկ անգամ՝ մենք պահում ենք միայն դրա հեշը․ կորցրե՞լ եք՝ հետ կանչեք և թողարկեք նորը։ Կոնսոլում են փոխվում նաև մուտքի էլ․ փոստը և գաղտնաբառը, երևում են պատվերները, պրոֆիլները և հաշիվը։

API-ում բոլոր գումարները ԱՄՆ դոլարով են (USD)։ Գները գալիս են արդեն հաշվարկված․ price-ը այն է, ինչ կգանձենք ձեր դրամապանակից, sale_price-ը՝ որքանով վաճառել հաճախորդին։ Դրամապանակը լիցքավորվում է նախապես՝ կոնսոլի «Հաշիվ» էջում՝ բանկային քարտով, Apple Pay-ով կամ Google Pay-ով․ գումարը մուտքագրվում է անմիջապես։

Սկսեք ավազարկղից։ Այն թողարկում է իրական ձևաչափի պրոֆիլներ և հղումներ, բայց չի դիմում մատակարարին և գումար չի գանձում, ուստի կարող եք փորձել որքան ուզեք։

Բազային հասցե: https://aloesim.am/api/v1

3. Նույնականացում

Բանալին փոխանցվում է Authorization: Bearer վերնագրով։ Հարցման տողում այն փոխանցել չի կարելի․ հասցեները մնում են պրոքսիների մատյաններում և սխալների հաշվետվություններում։

curl https://aloesim.am/api/v1/ping \ -H "Authorization: Bearer alo_test_…"

Ռեժիմը երևում է հենց բանալու մեջ՝ alo_live_՝ աշխատանքային, alo_test_՝ ավազարկղ։ Սա զարդ չէ․ ինտեգրացիայի ամենահաճախ վթարը թեստային միջավայրում պատահաբար մնացած աշխատանքային բանալին է։ GET /ping-ը ցույց է տալիս, թե որ բանալիով եք եկել․

{ "data": { "status": "ok", "mode": "sandbox", "partner": { "id": 42, "company": "Travel Co" }, "key": { "name": "հիմնական սերվեր", "prefix": "alo_test_9f2c1ab4" }, "server_time": "2026-10-20T10:15:00+00:00" } }

4. Ինչ կարելի է կանչել

GET /ping Բանալու և ռեժիմի ստուգում
GET /balance Հաշվի մնացորդ
GET /countries Ուղղություններ, որոնց համար կան սակագներ
GET /packages Կատալոգ՝ ձեր գնով (price) և վաճառքի գնով (sale_price)
GET /packages/{slug} Մեկ սակագին
POST /orders Թողարկել eSIM՝ պատասխանում հղում հաճախորդի համար
GET /orders Ձեր պատվերները
GET /orders/{id} Պատվերի կարգավիճակը և պրոֆիլը, երբ այն պատրաստ է
GET /esims Թողարկված պրոֆիլներ
GET /esims/{iccid} Պրոֆիլ՝ հղում, տեղադրման տվյալներ, ծախս
GET /esims/{iccid}/usage Տրաֆիկի թարմ ծախս
POST /esims/{iccid}/cancel Չեղարկել չտեղադրված պրոֆիլը
GET /webhook Ծանուցումների ընթացիկ հասցեն
PUT /webhook Նշել ծանուցումների հասցեն՝ պատասխանում ստորագրության գաղտնիքը
POST /webhook/test Փորձնական ծանուցում
DELETE /webhook Անջատել ծանուցումները

Ցուցակները (/packages, /orders, /esims) տրվում են էջերով՝ page և per_page պարամետրեր (լռելյայն 25, առավելագույնը 100), էջերի տվյալները՝ meta-ում։ Ավազարկղի բանալին տեսնում է միայն թեստային պատվերներն ու պրոֆիլները, աշխատանքայինը՝ միայն աշխատանքայինները։

{ "data": [ … ], "meta": { "page": 1, "per_page": 25, "total": 140, "last_page": 6 } }

5. Կատալոգ և գներ

GET /countries՝ ուղղություններ (iso2, name, flag)։ GET /packages՝ սակագներ․ ֆիլտրեր՝ country (ISO2), region, type (local, regional, global)։ Սակագինը պատվիրվում է իր slug-ով։

curl "https://aloesim.am/api/v1/packages?country=GE&per_page=50" \ -H "Authorization: Bearer alo_test_…"
{ "data": [{ "slug": "esimaccess-ge-1-7", "title": "Վրաստան · 1 GB 7 օրով", "type": "local", "country": { "iso2": "GE", "name": "Վրաստան" }, "data_bytes": 1073741824, "data_label": "1 GB", "is_unlimited": false, "is_daily": false, "validity_days": 7, "price": { "currency": "USD", "amount_cents": 673, "amount": 6.73, "per": "package" }, "sale_price": { "currency": "USD", "amount_cents": 990, "amount": 9.9, "per": "package" }, "network": { "speed": "4G/5G", "apn": "internet", "supports_topup": true, "operators": [ … ] } }], "meta": { "page": 1, "per_page": 50, "total": 12, "last_page": 1 } }

price-ը ձեր գինն է՝ այնքան, որքան կգանձենք դրամապանակից։ sale_price-ը՝ որքանով վաճառել eSIM-ը հաճախորդին։ Մեր ցուցափեղկի զեղչերը այս գներում չկան․ դրանք մերն են՝ մեր գնորդների համար։

Առայժմ API-ում միայն տրաֆիկի սահմանաչափով սակագներ են․ անսահմանափակ և օրական սակագները կհայտնվեն ավելի ուշ։ Կատալոգի գները ամբողջ փաթեթի համար են (per: "package"), իսկ ճշգրիտ գումարները գալիս են նաև պատվերի պատասխանում։

6. eSIM-ի թողարկում

Մեկ հարցում։ Գումարը գանձվում է անմիջապես, պատասխանը գալիս է վայրկյանի մի մասում՝ հաճախորդի հղումով․ պրոֆիլն ինքը մատակարարի մոտ թողարկվում է մի քանի վայրկյանում։

curl -X POST https://aloesim.am/api/v1/orders \ -H "Authorization: Bearer alo_test_…" \ -H "Idempotency-Key: 7f3a9c02-order-1183" \ -H "Content-Type: application/json" \ -d '{"package":"esimaccess-ge-1-7","reference":"my-order-1183"}'
Դաշտ Ինչ է
package Պարտադիր։ Սակագնի slug-ը կատալոգից։
days Միայն օրական սակագների համար՝ քանի օրով։ Այժմ API-ում այդպիսիք չկան․ դաշտը ապագայի համար է։
reference Ոչ պարտադիր։ Ձեր պատվերի համարը՝ մինչև 64 նիշ․ վերադառնում է պատասխաններում և ծանուցումներում, հարմար է մեր պատվերները ձերոնց հետ համադրելու համար։
Idempotency-Key Պարտադիր վերնագիր՝ մինչև 191 նիշ։ Նույն բանալիով կրկնությունը կվերադարձնի նույն պատվերը և երկրորդ eSIM չի թողարկի։

Idempotency-Key վերնագիրը ձևականություն չէ․ հարցումը գումար է շարժում, իսկ կապը կտրվում է հենց այսպիսի հարցումների ժամանակ։ Ստեղծեք բանալին ձեր պատվերի համար մեկ անգամ և կրկնեք հարցումը դրանով այնքան, որքան պետք է։ Պատասխանը՝ 201 նոր պատվերի, 200՝ կրկնության դեպքում․

{ "data": { "id": "01a0bbc2-1341-7298-a018-b1d28cfa1e0e", "status": "paid", "is_ready": false, "mode": "sandbox", "link": "https://aloesim.am/Ab3dE7…", "package": { "slug": "esimaccess-ge-1-7", "title": "Վրաստան · 1 GB 7 օրով", "data_bytes": 1073741824, "validity_days": 7 }, "period_days": null, "quantity": 1, "price": { "currency": "USD", "amount_cents": 673, "amount": 6.73, "charged": false }, "sale_price": { "currency": "USD", "amount_cents": 990, "amount": 9.9 }, "reference": "my-order-1183", "esim": null, "failure_reason": null, "created_at": "2026-10-20T10:15:02+00:00", "completed_at": null } }

link-ը ձեր հաճախորդի eSIM-ի էջն է։ Այն գալիս է անմիջապես և չի փոխվում․ նույն հասցեն կլինի GET /orders/{id}-ում, պրոֆիլում և esim.ready ծանուցման մեջ։ price-ը դրամապանակից գանձված գումարն է (ավազարկղում՝ charged: false), sale_price-ը՝ որքանով վաճառել eSIM-ը․ երկու գներն էլ ամրագրված են պատվերի պահին։

Պատվերի կարգավիճակը՝ paid, provisioning, awaiting_provider՝ թողարկվում է․ completed՝ պրոֆիլը պատրաստ է․ failed՝ թողարկել չհաջողվեց, գումարը վերադարձել է դրամապանակ, պատճառը՝ failure_reason-ում։ Հարցում անել պարտադիր չէ․ հղումն աշխատում է ինքնուրույն, իսկ պատրաստության և ձախողման մասին կարելի է ծանուցումներ ստանալ։

Երբ պրոֆիլը պատրաստ է, is_ready-ը դառնում է true, իսկ esim-ում գալիս են տեղադրման տվյալները։ Դրանք պետք են միայն, եթե ուզում եք QR կոդը ցույց տալ նաև ձեր կողմում․ սովորաբար հղումը բավական է։ Պրոֆիլի կարգավիճակը՝ issued՝ թողարկված, active՝ տեղադրված և աշխատում է, depleted՝ տրաֆիկն ավարտվել է, expired՝ ժամկետն անցել է, cancelled, suspended, revoked։

"esim": { "iccid": "8944084435147973198", "status": "issued", "mode": "sandbox", "link": "https://aloesim.am/Ab3dE7…", "activation": { "lpa": "LPA:1$rsp.example.com$K2-9F3A-71BC", "smdp_address": "rsp.example.com", "matching_id": "K2-9F3A-71BC", "confirmation_code": null, "apn": "internet" }, "usage": { "total_bytes": 1073741824, "used_bytes": 0, "remaining_bytes": 1073741824, "synced_at": null }, "activated_at": null, "expires_at": "2026-10-27T10:15:20+00:00" }

7. eSIM-ի էջը հղումով

Հղումը բացվում է առանց մուտքի և առանց հավելվածի․ մուտքը տալիս է հենց երկար պատահական հասցեն։ Էջը փակ է որոնողական համակարգերից։ Ինչ է այնտեղ տեսնում ձեր հաճախորդը․

  • Քանի դեռ պրոֆիլը թողարկվում է՝ «eSIM-ը պատրաստվում է»․ էջը կթարմացվի ինքնուրույն, երբ այն պատրաստ լինի։
  • Պատրաստ պրոֆիլ՝ QR կոդ, iPhone-ում մեկ հպումով տեղադրման կոճակ, ձեռքով տեղադրման տվյալներ, տեսահրահանգներ iPhone-ի և Android-ի համար, տրաֆիկի մնացորդ և գործողության ժամկետ։
  • Եթե թողարկումը չհաջողվեց՝ հաղորդագրություն, որ խնդիրը մեր կողմում է, և չատ մեր աջակցության հետ։
  • Աջակցության չատ՝ հաճախորդը գրում է մեզ հենց էջից․ տեղադրման, կապի և տրաֆիկի հարցերում օգնում ենք մենք։
  • Լիցքավորում՝ հաճախորդն ինքն է նույն eSIM-ին ավելացնում տրաֆիկ կամ օրեր և վճարում էջում․ ոչինչ վերատեղադրել պետք չէ։
  • Ձեր ձևավորումը՝ ձեր ընկերության լոգոն, գույները և տառատեսակները․ կարգավորում ենք ձեր խնդրանքով։ Ձեր կոնտակտները էջում չկան․ eSIM-ի հարցերով հաճախորդը դիմում է մեզ։
  • Լեզու՝ հայերեն, ռուսերեն կամ անգլերեն․ հաճախորդն ինքն է փոխում։

Էջում գներ չկան՝ ոչ ձերը, ոչ վաճառքի գինը։ Ավազարկղում էջում կա «Թեստային eSIM» նշումը, իսկ լիցքավորումն անջատված է։

8. Պրոֆիլներ

GET /esims և GET /esims/{iccid}՝ թողարկված պրոֆիլներ, դիմումը՝ ICCID-ով։ Պրոֆիլում նույն link-ն է, տեղադրման տվյալները և ծախսը։

GET /esims/{iccid}/usage՝ թարմ ծախս․ հարցնում ենք մատակարարին հենց հիմա։ Եթե նա չպատասխանի, կգան վերջին հայտնի թվերը՝ synced_at նշումով։

POST /esims/{iccid}/cancel՝ դեռ հեռախոսում չտեղադրված պրոֆիլի չեղարկում։ Տեղադրվածը չեղարկել չի կարելի (esim_activated)․ մատակարարի մոտ այն արդեն սպառված է։ Չեղարկված պրոֆիլի գումարը չի վերադարձվում։

9. Ծանուցումներ

Պարտադիր չէ․ հաճախորդի հղումն աշխատում է նաև առանց ծանուցումների։ Նշեք հասցեն, եթե ուզում եք անմիջապես իմանալ, որ թողարկումը չի հաջողվել (order.failed)՝ գումարը վերադարձել է ձեր դրամապանակ, վերադարձրեք այն հաճախորդին, և որ պրոֆիլը պատրաստ է (esim.ready)։

curl -X PUT https://aloesim.am/api/v1/webhook \ -H "Authorization: Bearer alo_live_…" \ -H "Content-Type: application/json" \ -d '{"url":"https://partner.example/hooks/alo"}'

Պատասխանում կգա secret-ը՝ այն ցուցադրվում է մեկ անգամ․ նոր PUT /webhook-ը տալիս է նորը։ Մեր յուրաքանչյուր հաղորդագրություն JSON-ով POST է՝ ստորագրված X-Alo-Signature վերնագրում․ HMAC-SHA256 հարցման մարմնից, hex տեսքով։ Իրադարձության անունը կրկնվում է X-Alo-Event-ում։ Ստուգեք ստորագրությունը պարտադիր, այլապես այդ հասցեին կարող է գրել ցանկացած մեկը․

// PHP $ok = hash_equals( hash_hmac('sha256', file_get_contents('php://input'), $secret), $_SERVER['HTTP_X_ALO_SIGNATURE'] ?? '' ); // Node.js (rawBody: the request body as received, before JSON parsing) const expected = Buffer.from(crypto.createHmac('sha256', secret).update(rawBody).digest('hex')); const got = Buffer.from(req.get('X-Alo-Signature') || ''); const ok = got.length === expected.length && crypto.timingSafeEqual(expected, got);

Իրադարձություններ՝ esim.ready՝ պրոֆիլը թողարկված է, հղումով արդեն QR կոդ է․ order.failed՝ թողարկումը վերջնականապես չի հաջողվել, գումարը վերադարձել է դրամապանակ։

{ "event": "esim.ready", "sent_at": "2026-10-20T10:15:31+00:00", "data": { "order_id": "01a0bbc2-…", "reference": "my-order-1183", "mode": "live", "iccid": "8944084435147973198", "lpa": "LPA:1$rsp.example.com$K2-9F3A-71BC", "link": "https://aloesim.am/Ab3dE7…", "status": "issued" } }
{ "event": "order.failed", "sent_at": "2026-10-20T10:16:05+00:00", "data": { "order_id": "01a0bbc2-…", "reference": "my-order-1183", "mode": "live", "reason": "…" } }

POST /webhook/test-ն ուղարկում է փորձնական ping իրադարձություն՝ ընդունումը և ստորագրությունը ստուգելու համար։ GET /webhook-ը ցույց է տալիս ընթացիկ հասցեն, DELETE /webhook-ն անջատում է ծանուցումները։

Պատասխանեք 2xx կոդով․ մնացած ամեն ինչը համարում ենք չառաքված և կրկնում ենք հինգ անգամ՝ աճող ընդմիջումով։ Հասցեն պետք է լինի https և տանի դեպի արտաքին ցանց․ ներքին հասցեներին մենք չենք դիմում։

10. Սխալներ և սահմանաչափեր

Սխալը միշտ գալիս է նույն ձևով՝ մեքենայական կոդ error.code-ում և մարդկային բացատրություն կողքին։ Վերլուծեք կոդը, ոչ թե տեքստը․ տեքստը կարող ենք վերաշարադրել, և այն գալիս է Accept-Language վերնագրի լեզվով։

{ "error": { "code": "insufficient_funds", "message": "Հաշվում բավարար միջոցներ չկան։" } }
Կոդ HTTP Երբ
missing_key / invalid_key / revoked_key 401 Բանալին փոխանցված չէ, չի գտնվել կամ հետ է կանչվել
partner_blocked 403 Մուտքը փակ է․ կապվեք մենեջերի հետ
validation_failed 422 Հարցման դաշտերը ստուգումը չեն անցել՝ մանրամասները details-ում
idempotency_key_required 400 Պատվեր ստեղծելիս Idempotency-Key փոխանցված չէ
idempotency_key_conflict 409 Նույն Idempotency-Key-ն այլ տվյալներով
idempotency_key_in_progress 409 Այս բանալիով պատվերը դեռ ստեղծվում է՝ կրկնեք մեկ վայրկյանից
insufficient_funds 402 Հաշվում գումարը բավարար չէ
package_not_found 404 Սակագինը չի գտնվել կամ հանված է վաճառքից
days_required 422 Օրական սակագնի համար days փոխանցված չէ
package_unavailable 409 Սակագինը հենց հիմա մատակարարի մոտ չկա
not_found 404 Պատվերը, պրոֆիլը կամ սակագինը (/packages/{slug}) չի գտնվել
esim_activated 409 Պրոֆիլն արդեն տեղադրված է՝ չեղարկումն անհնար է
cancel_refused 409 Մատակարարը մերժել է չեղարկումը
provider_error 502 Մատակարարը չի պատասխանել՝ կրկնեք ավելի ուշ
invalid_webhook_url 422 Ծանուցումների հասցեն https չէ կամ տանում է ներքին ցանց
webhook_not_set 422 Փորձնական ծանուցում՝ առանց նշված հասցեի
rate_limited 429 Հարցումների սահմանաչափը գերազանցված է
server_error 5xx Սխալ մեր կողմում՝ կրկնեք ավելի ուշ

Դաշտերի ստուգման սխալը թվարկում է, թե ինչն է սխալ յուրաքանչյուր դաշտում․

{ "error": { "code": "validation_failed", "message": "…", "details": { "package": ["…"] } } }

Սահմանաչափը՝ 120 հարցում րոպեում մեկ բանալու համար։ Գերազանցման դեպքում պատասխանը 429 կոդ է և Retry-After վերնագիր։ Ավելին է պետք՝ ասեք, կբարձրացնենք։

11. Ավազարկղ

alo_test_ բանալին աշխատում է նույն կատալոգով և նույն գներով, բայց դրանով պատվերը չի գնում մատակարարին և գումար չի գանձում։ Պրոֆիլը գալիս է իրական ձևաչափով՝ ICCID-ով և LPA տողով, իսկ հղումը բացում է իրական eSIM էջ, այնպես որ կարող եք կարգաբերել ամբողջ ճանապարհը, ներառյալ այն, ինչ կտեսնի հաճախորդը։

Ավազարկղը և աշխատանքային ռեժիմը չեն հատվում․ թեստային բանալիով չեն երևում աշխատանքային պատվերները, աշխատանքայինով՝ թեստայինները։ Թեստային eSIM-ը ճանապարհորդության համար պիտանի չէ․ դրա էջում այդ մասին գրված է։

Մուտք է պե՞տք

Թողեք հայտ, և նույն օրը մենք ձեզ կգրանցենք որպես API գործընկեր։ Բանալիները կթողարկեք ինքներդ կոնսոլում՝ նախ ավազարկղը, հետո աշխատանքայինը։

API գործընկերոջ կաբինետ Թողնել հայտ
ALO eSIM