1sim API Documentation

Общее

Базовый URL: https://1esim.tech/v1
Авторизация: Authorization: Bearer YOUR_API_KEY
Для поиска по createdAt используется формат RFC 3339 в UTC, например 2023-02-15T03:15:22Z
Для фильтра даты поддерживаются префиксы: lt, lte, gt, gte

GET

/balance

получить текущий баланс кошелька.

Параметры запроса

Нет.

Пример запроса

bash

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://1esim.tech/v1/balance"

Пример ответа 200

json

{
  "availableBalance": 0,
  "currency": "string",
  "currencyDivisor": 0
}

Поля ответа

availableBalance — доступный баланс
currency — валюта
currencyDivisor — делитель для корректного отображения суммы

GET

/brands

список доступных брендов.

Query-параметры

_limit *(required, number)* — сколько элементов вернуть, минимум 1, максимум 1024
_offset *(required, number)* — сколько элементов пропустить для пагинации
country *(string)* — 2-буквенный ISO-код страны назначения

Пример запроса

bash

curl -X GET \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://1esim.tech/v1/brands?_limit=100&_offset=0&country=US"

Пример ответа 200

json

{
  "limit": 0,
  "list": [
    {
      "brand": "string",
      "brandName": "string"
    }
  ],
  "offset": 0,
  "total": 0
}

GET

/brands/{brand}

детали конкретного бренда.

Path-параметры

brand *(required, string)* — имя бренда для запроса

Пример ответа 200

json

{
  "brand": "string",
  "brandName": "string",
  "brandBigImage": "string",
  "brandColor": "string",
  "brandGiftImage": "string",
  "brandInfoPdf": "string",
  "brandLogo": "string",
  "brandLogoExtension": "string",
  "description": "string",
  "inputMasks": [
    {
      "requiredField": "string",
      "inputMask": "string"
    }
  ],
  "redemptionInstructions": [
    {
      "country": "string",
      "deliveryType": "string",
      "language": "string",
      "link": "string"
    }
  ],
  "requiredFieldsLabels": [
    {
      "label": "string",
      "requiredField": "string"
    }
  ]
}

GET

/brands/{brand}/redemptionInstructions

redemption instructions и terms & conditions.

Path-параметры

brand *(required, string)* — имя бренда

Query-параметры

country *(required, string)* — 2-буквенный ISO-код страны назначения
deliveryType *(required, string)* — тип доставки продукта
language *(string)* — 2-буквенный ISO-код языка; по умолчанию обычно en

Пример ответа 200

json

{
  "country": "string",
  "deliveryType": "string",
  "language": "string",
  "redemptionInstructions": "string",
  "terms": "string",
  "redemptionVideo": "string"
}

GET

/esim/offers

список eSIM offers.

Query-параметры

_limit *(required, number)* — количество элементов
_offset *(required, number)* — смещение для пагинации
brand *(string)* — фильтр по бренду
country *(string)* — 2-буквенный ISO-код страны
regions *(string, enum)* — регион (Global, Africa, Asia, Caribbean, Central America, Eastern Europe, Western Europe, North America, Oceania, South America, South Asia, Southeast Asia, Middle East and North Africa)
subType *(string)* — подтип оффера

Пример ответа 200 (укорочено)

json

{
  "limit": 0,
  "list": [
    {
      "brand": "string",
      "brandName": "string",
      "cost": 0,
      "costBase": 0,
      "costCurrency": "string",
      "costCurrencyDivisor": 0,
      "costFee": 0,
      "country": "string",
      "createdAt": "string",
      "dataGB": 0,
      "dataSpeeds": ["2G"],
      "dataUnlimited": true,
      "durationDays": 0,
      "notes": "string",
      "offerId": "string",
      "price": 0,
      "priceBase": 0,
      "priceCurrency": "string",
      "priceCurrencyDivisor": 0,
      "priceFee": 0,
      "priceType": "FIXED",
      "productType": "TOPUP",
      "regions": ["Global"],
      "roaming": [
        {
          "country": "string",
          "dataSpeeds": ["2G"]
        }
      ],
      "shortNotes": "string",
      "smsNumber": 0,
      "smsUnlimited": true,
      "subTypes": ["string"],
      "updatedAt": "string",
      "voiceMinutes": 0,
      "voiceUnlimited": true
    }
  ],
  "offset": 0,
  "total": 0
}

GET

/esim/offers/{offerId}

получить eSIM offer по ID.

Path-параметры

offerId *(required, string)* — catalog ID

Пример ответа

Структура аналогична одному объекту offer из GET /esim/offers.

GET

/esim/purchases

список eSIM-транзакций.

Query-параметры

_limit *(required, number)* — количество элементов
_offset *(required, integer)* — смещение
createdAt *(string)* — фильтр по дате
status *(string, enum)* — DONE, FAILED, PENDING, ACCEPTED, AUTHORIZED, IN_PROGRESS

Пример ответа 200 (укорочено)

json

{
  "limit": 0,
  "list": [
    {
      "transactionId": "string",
      "status": "DONE",
      "offerId": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "price": 0,
      "cost": 0,
      "dataGB": 0,
      "durationDays": 0,
      "refund": {
        "status": "string"
      }
    }
  ],
  "offset": 0,
  "total": 0
}

POST

/esim/purchases

покупка eSIM offer для новой eSIM или добавление offer к существующей eSIM.

Body-поля

iccid *(string)* — ICCID eSIM, если нужно применить план к существующей eSIM; если не передавать, будет выпущена новая
offerId *(required, string)* — catalog ID offer
transactionId *(required, string)* — ID транзакции со стороны партнёра

Пример body

json

{
  "iccid": "string",
  "offerId": "string",
  "transactionId": "string"
}

Пример ответа 200

json

{
  "status": "string",
  "transactionId": "string"
}

GET

/esim/purchases/{transactionId}

получить eSIM-транзакцию по ID.

Path-параметры

transactionId *(required, string)* — ID транзакции

Пример ответа 200 (укорочено)

json

{
  "transactionId": "string",
  "status": "DONE",
  "offerId": "string",
  "iccid": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "price": 0,
  "cost": 0,
  "dataGB": 0,
  "dataSpeeds": ["2G"],
  "dataUnlimited": true,
  "durationDays": 0,
  "regions": ["Global"],
  "roaming": [
    {
      "country": "string",
      "dataSpeeds": ["2G"]
    }
  ],
  "value": {
    "type": "PRICE",
    "value": 0
  },
  "voiceMinutes": 0,
  "voiceUnlimited": true,
  "smsNumber": 0,
  "smsUnlimited": true,
  "refund": {
    "status": "string"
  },
  "error": {
    "code": "string",
    "description": "string",
    "message": "string"
  },
  "log": [
    {
      "dateTime": "string",
      "status": "DONE",
      "statusMessage": "string"
    }
  ]
}

GET

/esim/purchases/{transactionId}/qrcode

получить QR code eSIM по transaction ID.

Path-параметры

transactionId *(required, string)* — ID транзакции

Пример ответа 200

Документация показывает отдельный endpoint для QR, но в доступном фрагменте страницы полноценный sample ответа не раскрыт. Практически это endpoint получения QR-кода для eSIM по ID транзакции.

GET

/esim/purchases/{transactionId}/usage

usage активных и queued plans на eSIM.

Path-параметры

transactionId *(required, string)* — ID транзакции

Пример ответа

В доступном фрагменте страницы sample ответа не был полностью раскрыт. Endpoint присутствует в оглавлении документации.

GET

/esim/purchases/{transactionId}/refund

статус refund по транзакции.

Path-параметры

transactionId *(required, string)*

Пример ответа 200 (укорочено)

json

{
  "amount": 0,
  "createdAt": "string",
  "currency": "string",
  "currencyDivisor": 0,
  "error": {
    "code": "string",
    "description": "string",
    "message": "string"
  },
  "log": [
    {
      "dateTime": "string",
      "status": "DONE",
      "statusMessage": "string"
    }
  ],
  "productType": "TOPUP",
  "status": "DONE",
  "transactionId": "string",
  "type": "DEBIT",
  "updatedAt": "string"
}

POST

/esim/purchases/{transactionId}/refund

инициировать refund.

Path-параметры

transactionId *(required, string)*

Body

В доступном фрагменте страницы body целиком не раскрылся. Endpoint присутствует в оглавлении как Initiate a transaction refund.

GET

/topups/offers

список topup offers.

Query-параметры

_limit *(required, number)* — количество элементов
_offset *(required, number)* — смещение
brand *(string)* — бренд / carrier
country *(string)* — 2-буквенный ISO-код страны
regions *(string, enum)* — регион
subType *(string, enum)* — Mobile Top Up, Mobile Bundle, Mobile Data

Пример ответа 200 (укорочено)

json

{
  "limit": 0,
  "list": [
    {
      "brand": "string",
      "brandName": "string",
      "country": "string",
      "offerId": "string",
      "enabled": true,
      "notes": "string",
      "cost": {
        "currency": "string",
        "currencyDivisor": 0,
        "discount": 0,
        "fee": 0,
        "feePct": 0,
        "fixed": 0,
        "fx": 0,
        "max": 0,
        "min": 0
      },
      "price": {
        "currency": "string",
        "currencyDivisor": 0,
        "fee": 0,
        "fixed": 0,
        "fx": 0,
        "increment": 0,
        "margin": 0,
        "max": 0,
        "min": 0,
        "suggestedFixed": 0,
        "suggestedFx": 0
      },
      "priceType": "string",
      "productType": "TOPUP",
      "regions": ["Global"],
      "shortNotes": "string",
      "smsNumber": 0,
      "smsUnlimited": true,
      "subTypes": ["Mobile Top Up"],
      "voiceMinutes": 0,
      "voiceUnlimited": true,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "offset": 0,
  "total": 0
}

GET

/topups/offers/{offerId}

получить topup offer по ID.

Path-параметры

offerId *(required, string)* — catalog ID

Пример ответа

Структура аналогична одному offer из GET /topups/offers.

GET

/topups/purchases

список topup-транзакций.

Query-параметры

_limit *(required, integer)* — количество элементов
_offset *(required, integer)* — смещение
createdAt *(string)* — фильтр по дате
status *(string, enum)* — DONE, FAILED, PENDING, ACCEPTED, AUTHORIZED, IN_PROGRESS

Пример ответа 200 (укорочено)

json

{
  "limit": 0,
  "list": [
    {
      "transactionId": "string",
      "status": "DONE",
      "offerId": "string",
      "recipientPhoneNumber": "string",
      "sender": {
        "country": "string",
        "phoneNumber": "string"
      },
      "value": {
        "type": "PRICE",
        "value": 0
      },
      "price": 0,
      "cost": 0,
      "send": 0,
      "sendCurrency": "string",
      "sendCurrencyDivisor": 0,
      "regions": ["Global"],
      "subTypes": ["Mobile Top Up"],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "offset": 0,
  "total": 0
}

POST

/topups/purchases

создать topup purchase.

Body-поля

offerId *(required, string)* — catalog ID offer
recipientPhoneNumber *(required, string)* — номер получателя в формате E.164
sender *(object)* — необязательная информация об отправителе
country *(string)*
phoneNumber *(string)*
transactionId *(required, string)* — ID транзакции партнёра
value *(object)* — сумма и тип покупки; нужна для RANGE offers, для FIXED offers не передаётся
type *(enum)* — например PRICE
value *(number)* — значение

Пример body

json

{
  "offerId": "string",
  "recipientPhoneNumber": "string",
  "sender": {
    "country": "string",
    "phoneNumber": "string"
  },
  "transactionId": "string",
  "value": {
    "type": "PRICE",
    "value": 0
  }
}

Пример ответа 200

json

{
  "status": "string",
  "transactionId": "string"
}

GET

/topups/purchases/{transactionId}

получить topup purchase по ID.

Path-параметры

transactionId *(required, string)* — ID транзакции

Пример ответа 200 (укорочено)

json

{
  "transactionId": "string",
  "status": "DONE",
  "offerId": "string",
  "recipientPhoneNumber": "string",
  "sender": {
    "country": "string",
    "phoneNumber": "string"
  },
  "value": {
    "type": "PRICE",
    "value": 0
  },
  "price": 0,
  "cost": 0,
  "send": 0,
  "sendCurrency": "string",
  "sendCurrencyDivisor": 0,
  "regions": ["Global"],
  "subTypes": ["Mobile Top Up"],
  "voiceMinutes": 0,
  "voiceUnlimited": true,
  "smsNumber": 0,
  "smsUnlimited": true,
  "error": {
    "code": "string",
    "description": "string",
    "message": "string"
  },
  "log": [
    {
      "dateTime": "string",
      "status": "DONE",
      "statusMessage": "string"
    }
  ],
  "createdAt": "string",
  "updatedAt": "string"
}

GET

/vouchers/offers

список voucher offers.

Query-параметры

_limit *(required, number)* — количество элементов
_offset *(required, number)* — смещение
brand *(string)* — бренд
country *(string)* — 2-буквенный ISO-код страны
regions *(string, enum)* — регион
subType *(string)* — подтип offer

Пример ответа 200 (укорочено)

json

{
  "limit": 0,
  "list": [
    {
      "brand": "string",
      "brandName": "string",
      "country": "string",
      "createdAt": "string",
      "enabled": true,
      "notes": "string",
      "offerId": "string",
      "priceType": "string",
      "productType": "TOPUP",
      "cost": {
        "currency": "string",
        "currencyDivisor": 0,
        "discount": 0,
        "fee": 0,
        "feePct": 0,
        "fixed": 0,
        "fx": 0,
        "max": 0,
        "min": 0
      },
      "price": {
        "currency": "string",
        "currencyDivisor": 0,
        "fee": 0,
        "fixed": 0,
        "fx": 0,
        "increment": 0,
        "margin": 0,
        "max": 0,
        "min": 0,
        "suggestedFixed": 0,
        "suggestedFx": 0
      },
      "regions": ["Global"],
      "requiredFields": ["string"],
      "send": {
        "currency": "string",
        "currencyDivisor": 0
      }
    }
  ],
  "offset": 0,
  "total": 0
}

GET

/vouchers/offers/{offerId}

получить voucher offer по ID.

Path-параметры

offerId *(required, string)* — catalog ID

Пример ответа

Структура аналогична одному offer из GET /vouchers/offers.

GET

/vouchers/purchases

список voucher purchase-транзакций.

Query-параметры

_limit *(required, integer)* — количество элементов
_offset *(required, integer)* — смещение
createdAt *(string)* — фильтр по дате
status *(string, enum)* — DONE, FAILED, PENDING, ACCEPTED, AUTHORIZED, IN_PROGRESS

Пример ответа 200 (укорочено)

json

{
  "limit": 0,
  "list": [
    {
      "transactionId": "string",
      "status": "DONE",
      "offerId": "string",
      "brand": "string",
      "brandName": null,
      "country": "string",
      "price": 0,
      "cost": 0,
      "fields": [
        {
          "key": "string",
          "value": "string"
        }
      ],
      "confirmation": {
        "confirmationNumber": "string",
        "externalReferenceId": "string",
        "transactionTime": "string"
      },
      "receipt": {
        "deliveryType": "string",
        "confirmationNumber": "string",
        "currency": "string",
        "currencyDivisor": 0,
        "epin": "string",
        "voucherId": "string",
        "redemptionUrl": "string",
        "accountId": "string",
        "expiresAt": "string",
        "instructions": "string",
        "notes": "string",
        "recipientCustomerServiceNumber": "string",
        "send": 0,
        "senderCustomerServiceNumber": "string"
      },
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "offset": 0,
  "total": 0
}

POST

/vouchers/purchases

создать voucher purchase.

Body-поля

По структуре purchase содержит:

offerId *(required, string)* — ID offer
transactionId *(required, string)* — ID транзакции
fields *(array)* — набор required fields для выбранного бренда/offer
элемент массива:
key *(string)*
value *(string)*

В документации прямо указано, что для Digital Gift Cards и Utility Payments обязательные дополнительные поля зависят от бренда; их список приходит в каталоге бренда / offer.

Пример body

json

{
  "offerId": "string",
  "transactionId": "string",
  "fields": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Пример ответа 200

json

{
  "status": "string",
  "transactionId": "string"
}

GET

/vouchers/purchases/{transactionId}

получить voucher purchase по ID.

Path-параметры

transactionId *(required, string)* — ID транзакции

Пример ответа 200

Структура аналогична одному объекту из GET /vouchers/purchases, включая confirmation, fields, receipt, error, log, price, cost, createdAt, updatedAt.

GET

/transactions

список транзакций по статусам.

Query-параметры

_limit *(required, integer)* — количество элементов
_offset *(required, integer)* — смещение
createdAt *(string)* — фильтр по дате
productType *(string)* — тип продукта
status *(string)* — статус транзакции
type *(string)* — тип записи, например debit/credit

Пример ответа 200

json

{
  "limit": 0,
  "list": [
    {
      "amount": 0,
      "createdAt": "string",
      "currency": "string",
      "currencyDivisor": 0,
      "error": {
        "code": "string",
        "description": "string",
        "message": "string"
      },
      "log": [
        {
          "dateTime": "string",
          "status": "DONE",
          "statusMessage": "string"
        }
      ],
      "productType": "TOPUP",
      "status": "DONE",
      "transactionId": "string",
      "type": "DEBIT",
      "updatedAt": "string"
    }
  ],
  "offset": 0,
  "total": 0
}

GET

/transactions/{transactionId}

получить транзакцию по ID.

Path-параметры

transactionId *(required, string)* — ID транзакции

Пример ответа 200

json

{
  "amount": 0,
  "createdAt": "string",
  "currency": "string",
  "currencyDivisor": 0,
  "error": {
    "code": "string",
    "description": "string",
    "message": "string"
  },
  "log": [
    {
      "dateTime": "string",
      "status": "DONE",
      "statusMessage": "string"
    }
  ],
  "productType": "TOPUP",
  "status": "DONE",
  "transactionId": "string",
  "type": "DEBIT",
  "updatedAt": "string"
}

GET

/tools/phonenumberlookup/{msisdn}

lookup phone number / MSISDN (beta).

Path-параметры

msisdn *(required, string)* — телефон в формате E.164

Пример ответа 200

json

{
  "brand": "string",
  "country": "string",
  "mobileCountryCode": "string",
  "mobileNetworkCode": "string",
  "msisdn": "string"
}

POST

/reports/transactions

запустить генерацию отчёта по транзакциям.

Body-поля

endLt *(required, string)* — конечная дата; в отчёт попадут транзакции, завершившиеся раньше этой даты
startGte *(required, string)* — начальная дата; попадут транзакции, начавшиеся в этот момент или позже

Пример body

json

{
  "endLt": "string",
  "startGte": "string"
}

Пример ответа 200 (укорочено)

json

{
  "createdAt": "string",
  "error": {
    "code": "string",
    "description": "string",
    "message": "string"
  },
  "file": {
    "downloadUrl": "string",
    "name": "string"
  },
  "log": [
    {
      "message": "string",
      "recordedAt": "string",
      "status": "REQUESTED"
    }
  ],
  "period": {
    "endLt": "string",
    "startGte": "string"
  },
  "reportId": "string",
  "status": "REQUESTED"
}

GET

/reports/transactions/{reportId}

статус ранее запрошенного отчёта.

Path-параметры

reportId *(required, string)* — ID отчёта

Пример ответа 200

Структура аналогична ответу генерации отчёта: createdAt, error, file, log, period, reportId, status.

GET

/reports/transactions/{reportId}/{file}

скачать готовый отчёт.

Path-параметры

reportId *(required, string)* — ID отчёта
file *(required, string)* — имя файла

Успешный ответ

Бинарный файл (application/octet-stream)

Пример error-ответа

json

{
  "errorCode": "string",
  "fields": {
    "property1": "string",
    "property2": "string"
  },
  "message": "string"
}

GET

/promos

список активных и upcoming promotions.

Query-параметры

_limit *(required, integer)* — максимум промо для возврата
_offset *(required, string)* — сколько промо пропустить
brand *(string)* — бренд
country *(string)* — список 2-буквенных ISO-кодов стран через запятую
language *(string)* — 2-буквенный ISO-код языка
region *(string, regions)* — регион

Пример ответа 200

json

{
  "limit": 0,
  "list": [
    {
      "brand": {
        "brand": "string",
        "brandName": "string"
      },
      "country": "string",
      "createdAt": "string",
      "description": {
        "description": "string",
        "language": "string",
        "terms": "string"
      },
      "endAt": "string",
      "id": "string",
      "maxValue": 0,
      "minValue": 0,
      "regions": "Global",
      "startAt": "string",
      "status": "active",
      "updatedAt": "string"
    }
  ],
  "offset": 0,
  "total": 0
}

GET

/promos/{promoId}

получить promo по ID.

Path-параметры

promoId *(required, string)* — ID промо

Пример ответа 200

Структура аналогична одному объекту из GET /promos.

# Типовые коды ответов

Почти для всех endpoint в документации указаны:

200 — OK
400 — Bad Request
401 — Unauthorized – API Token Missing or Unrecognized
403 — Forbidden – IP Not Allowed
404 — Not Found (для endpoint с path ID)
500 — Internal Server Error

# Краткий итог по endpoint

Всего в оглавлении документации перечислено 28 HTTP endpoints, если считать только разделы API-запросов и не считать webhook/event callback-описания.