Документация API

Скачать документацию API (Markdown)

kartesim предоставляет партнёрам реальные телефонные номера и мобильные IP через два сервиса: долгосрочную аренду номеров и прокси и OTP-сессии с оплатой за использование. Оба доступны через протокол HANDLER_API и нативный REST API.

OTP-сессииза использование

Запросите временный номер, дождитесь SMS и получите OTP-код — за один цикл вызовов API. Оплата за сессию; средства возвращаются, если вы отмените сессию до прихода кода.

Аренда номеровSIM-карты

Арендуйте выделенный номер телефона на день, неделю или месяц. Все SMS, поступающие на этот номер, пересылаются в ваш аккаунт в реальном времени.

Аренда проксиМобильные IP

Арендуйте мобильный прокси HTTP/SOCKS5 с реальным IP оператора. Каждый прокси работает на выделенном устройстве (Android или 4G-модем) с активной SIM-картой.

Аренду оформляет ваш менеджер. Свяжитесь с нами, чтобы настроить аренду, — после активации номер телефона и учётные данные прокси появятся в партнёрском портале, и их можно будет запрашивать через API. OTP-сессии доступны через API самостоятельно — настройка не требуется.

Аутентификация

Для всех запросов к API нужен ваш партнёрский ключ API. Способ передачи зависит от протокола.

Handler API — параметр запроса

GET /api/stubs/handler_api.php
  ?api_key=YOUR_KEY
  &action=getBalance

Нативный REST API — HTTP-заголовок

curl https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram"}'

Храните ключ API в секрете. Ваш ключ виден в партнёрском портале в разделе API. Там же кнопка Сгенерировать новый ключ позволяет мгновенно заменить его.

Справочник Handler API

Базовый URL: /api/stubs/handler_api.php — все запросы используют GET. Все ответы — обычный текст.

GET/api/stubs/handler_api.php?action=getBalance

Возвращает текущий предоплаченный баланс в USD.

Параметры

Имя	Тип	Обязательный	Описание
api_key	string	обязательный	Ваш ключ API
action	string	обязательный	Должно быть "getBalance"

Ответы

45.00Ваш баланс в USD

999999Фиксированное значение для аккаунтов с неограниченным балансом — это не реальный баланс, и оно не меняется при использовании

BAD_KEYНедействительный или отозванный ключ API

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

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getBalance'

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

45.00

GET/api/stubs/handler_api.php?action=getCountries

Список поддерживаемых стран с их числовыми кодами.

Параметры

Имя	Тип	Обязательный	Описание
api_key	string	обязательный	Ваш ключ API
action	string	обязательный	Должно быть "getCountries"

Ответы

JSON array[{ "id": 7, "name": "Russia" }, ...]

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

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getCountries'

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

[
  { "id": 7,   "name": "Russia" },
  { "id": 212, "name": "Morocco" }
]

GET/api/stubs/handler_api.php?action=getPrices

Текущие цены и доступный активный запас по странам и сервисам.

Параметры

Имя	Тип	Обязательный	Описание
api_key	string	обязательный	Ваш ключ API
action	string	обязательный	Должно быть "getPrices"
country	number	необязательный	Фильтр по числовому ID страны
hide_empty	integer	необязательный	Укажите 1, чтобы исключить из ответа страны с нулевым запасом

Ответы

JSON object{ "countryId": { "serviceId": { "cost": 0.1, "count": 10 } } }

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

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getPrices&hide_empty=1'

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

{
  "212": {
    "wa": { "cost": 0.15, "count": 12 },
    "tg": { "cost": 0.15, "count": 12 }
  }
}

GET/api/stubs/handler_api.php?action=getNumber

Запрос временного номера телефона для OTP-подтверждения. Возвращает ID сессии и выделенный номер. Сессия истекает через 10 минут, если SMS не пришло.

Параметры

Имя	Тип	Обязательный	Описание
api_key	string	обязательный	Ваш ключ API
action	string	обязательный	Должно быть "getNumber"
service	string	необязательный	Название сервиса (например, "telegram", "whatsapp") — только для информации
country	integer	необязательный	Телефонный код страны (например, 212 для Марокко). Не указывайте или передайте 0 для любой страны.

Ответы

ACCESS_NUMBER:id:numberСессия создана — id используется для getStatus/setStatus, number — выделенный номер телефона

NO_NUMBERSНет доступных онлайн-портов, подходящих под запрос

NO_BALANCEНедостаточно средств для оплаты OTP

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

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getNumber&service=telegram&country=212'

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

ACCESS_NUMBER:cma4x9k3b0000abc123:212661234567

GET/api/stubs/handler_api.php?action=getStatus

Опрос активной сессии для получения OTP-кода. Опрашивайте каждые 5–10 секунд, пока не получите STATUS_OK или STATUS_CANCEL.

Параметры

Имя	Тип	Обязательный	Описание
api_key	string	обязательный	Ваш ключ API
action	string	обязательный	Должно быть "getStatus"
id	string	обязательный	ID сессии из ответа ACCESS_NUMBER

Ответы

STATUS_WAIT_CODEСессия активна — SMS ещё не получено. Продолжайте опрос.

STATUS_OK:84729OTP получен — код следует после двоеточия

STATUS_CANCELСессия истекла или была отменена

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

curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=getStatus&id=cma4x9k3b0000abc123'

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

STATUS_OK:84729

GET/api/stubs/handler_api.php?action=setStatus

Подтвердите получение OTP (status=1) или отмените сессию с полным возвратом средств (status=8). Отменить можно только сессии в статусе PENDING.

Параметры

Имя	Тип	Обязательный	Описание
api_key	string	обязательный	Ваш ключ API
action	string	обязательный	Должно быть "setStatus"
id	string	обязательный	ID сессии, к которой применяется действие
status	integer	обязательный	1 = подтвердить получение, 8 = отменить и вернуть средства

Ответы

ACCESS_READYПодтверждено — сессия принята

ACCESS_CANCELОтменено — средства возвращены на баланс

BAD_ACTIONСессия не найдена или уже завершена

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

# Cancel and refund
curl 'https://www.kartesim.com/api/stubs/handler_api.php
  ?api_key=YOUR_KEY&action=setStatus&id=cma4x9k3b0000abc123&status=8'

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

ACCESS_CANCEL

Нативный REST API

Для современных интеграций используйте наш нативный REST API вместо устаревшего Handler API. Передавайте ключ API в HTTP-заголовке x-api-key.

OTP-сессии

за использование

OTP-сессии позволяют запросить временный номер телефона, получить одноразовый код и освободить номер — всё через API. Каждая сессия оплачивается один раз при создании. Если отменить сессию до прихода кода, оплата возвращается полностью.

POST/api/v1/otp/request

Запрос временного номера телефона для OTP-подтверждения. Возвращает sessionId и выделенный номер. Сразу списывает плату OTP_PER_USE.

Параметры

Имя	Тип	Обязательный	Описание
country	integer	необязательный	Телефонный код страны для фильтра (например, 212). Не указывайте для любой страны.
service	string	необязательный	Название сервиса, например "telegram" — сохраняется в сессии для вашего удобства
webhookUrl	string	необязательный	HTTPS-URL, на который придёт POST при получении OTP (вместо опроса)
expiresIn	integer	необязательный	Время жизни сессии в секундах (60–1800, по умолчанию 600)

Ответы

200 OKСессия создана — тело ответа содержит sessionId, number и expiresAt

402 Payment RequiredНедостаточно средств

503 Service UnavailableНет доступных онлайн-номеров

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

curl -X POST https://www.kartesim.com/api/v1/otp/request \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram", "country": 212}'

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

{ "sessionId": "cma4x9k3b0000abc123", "number": "212661234567", "status": "PENDING", "expiresAt": "2026-06-01T00:20:00.000Z" }

GET/api/v1/otp/:sessionId

Опрос статуса OTP-сессии и кода. Возвращает извлечённый OTP-код, как только приходит SMS. Опрашивайте каждые 5–10 секунд.

Ответы

200 OK — PENDINGstatus: "PENDING", otp: null — ожидание

200 OK — RECEIVEDstatus: "RECEIVED", otp: "84729" — код готов

200 OK — EXPIREDstatus: "EXPIRED" — SMS не пришло за отведённое время

200 OK — CANCELLEDstatus: "CANCELLED" — вы отменили сессию

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

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123

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

{ "sessionId": "cma4x9k3b0000abc123", "status": "RECEIVED", "number": "212661234567", "otp": "84729", "smsBody": "Your code is 84729" }

POST/api/v1/otp/:sessionId/cancel

Отмена сессии в статусе PENDING. Плата за OTP возвращается полностью. Сессии, по которым уже получен OTP, отменить нельзя.

Ответы

200 OKstatus: "CANCELLED", refunded: 0.10 — средства зачислены на баланс

409 ConflictСессия не в статусе PENDING — отмена невозможна

404 Not FoundСессия не найдена или принадлежит другому аккаунту

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

curl -X POST -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/otp/cma4x9k3b0000abc123/cancel

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

{ "sessionId": "cma4x9k3b0000abc123", "status": "CANCELLED", "refunded": "0.1000" }

POSTВаш URL вебхука (push с сервера)

Когда приходит OTP, мы отправляем POST на webhookUrl, указанный при создании сессии. Это альтернатива опросу: ваш сервер получает OTP автоматически, без вызова getStatus.

Тело запроса

POST на ваш webhookUrl

{
  "event":      "otp.received",
  "sessionId":  "cma4x9k3b0000abc123",
  "status":     "RECEIVED",
  "number":     "212661234567",
  "otp":        "84729",
  "smsBody":    "Your Telegram code is 84729",
  "receivedAt": "2026-06-21T12:00:00.000Z"
}

Безопасность

В продакшене URL вебхука должен использовать HTTPS — HTTP-адреса отклоняются.
Мы отправляем заголовок X-Webhook-Signature: sha256=... (HMAC-SHA256). Проверяйте его, чтобы убедиться в подлинности запроса.
При ответе 5xx мы повторяем запрос один раз через 2 секунды. Ваш endpoint должен быстро возвращать 200.
Ваш endpoint должен быть идемпотентным — при повторной попытке возможна двойная доставка.

GET/api/partner/rentals

Получить все активные аренды номеров вашего аккаунта.

Ответы

200 OKJSON-массив активных аренд номеров

401 UnauthorizedНедействительный или отсутствующий ключ API

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

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

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

[
  {
    "id": "cuid...",
    "phoneNumber": "1234567890",
    "countryCode": 1,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

GET/api/partner/proxies

Получить все активные аренды прокси вашего аккаунта, включая текущий IP-адрес и учётные данные.

Ответы

200 OKJSON-массив активных аренд прокси

401 UnauthorizedНедействительный или отсутствующий ключ API

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

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/proxies

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

[
  {
    "id": "cuid...",
    "port": "Port A",
    "host": "192.168.1.10",
    "socks5Port": 1080,
    "username": "user",
    "password": "pwd",
    "expiresAt": "2026-06-25T10:00:00.000Z"
  }
]

GET/api/partner/sms?simNumber=1234567890

Получить последние SMS, пришедшие на арендованные вами номера. Можно отфильтровать по конкретному simNumber.

Параметры

Имя	Тип	Обязательный	Описание
simNumber	string	необязательный	Фильтр SMS по конкретному арендованному номеру

Ответы

200 OKJSON-массив последних SMS

401 UnauthorizedНедействительный или отсутствующий ключ API

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

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/sms

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

[
  {
    "id": "cuid...",
    "simNumber": "1234567890",
    "fromNumber": "Twilio",
    "body": "Your verification code is 49201",
    "receivedAt": "2026-05-29T15:30:00.000Z"
  }
]

Аренда номеров

Аренда номера даёт вам эксклюзивное использование реальной SIM-карты на фиксированный срок. Каждое SMS, пришедшее на этот номер, доставляется в ваш аккаунт в реальном времени. Арендовать номера можно напрямую через API или партнёрский портал.

Период	Длительность	Описание
Сутки	24 часа	Лучше всего для краткосрочных кампаний по подтверждению
Неделя	7 дней	Лучше всего для постоянного доступа к стабильному номеру
Месяц	30 дней	Лучше всего для долгосрочного выделенного номера

Как это работает

Вызовите GET /api/v1/numbers/available, чтобы просмотреть доступные номера (в замаскированном виде).
Выберите номер и расчётный период, затем вызовите POST /api/v1/numbers/rent, чтобы сразу его арендовать.
Средства списываются с баланса сразу. Полный незамаскированный номер возвращается в ответе.
Все SMS, пришедшие на арендованный номер, в реальном времени появляются в разделе Журнал SMS.
По окончании срока номер освобождается автоматически. За неиспользованное время средства не возвращаются.

GET/api/v1/numbers/available

Просмотр номеров, доступных для аренды. Номера замаскированы (например, +212 6** *** **7), чтобы вы видели страну и оператора до оформления. Можно отфильтровать по коду страны.

Параметры

Имя	Тип	Обязательный	Описание
country	number	необязательный	Код страны по МСЭ (например, 212). Не указывайте или передайте 0 для любой страны.

Ответы

200 OKJSON со списком доступных номеров и общим количеством

401 UnauthorizedНедействительный или отсутствующий ключ API

429 Too Many RequestsПревышен лимит запросов (30 запросов/мин)

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

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/v1/numbers/available?country=212

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

{
  "available": [
    {
      "phoneId":      "clx...",
      "maskedNumber": "+212 6** *** **7",
      "countryCode":  212,
      "country":      "Morocco",
      "carrier":      "Orange",
      "pricing": { "daily": null, "weekly": 2.50, "monthly": 8.00 }
    }
  ],
  "total": 1
}

POST/api/v1/numbers/rent

Самостоятельная аренда номера. Атомарно списывает средства с баланса и создаёт эксклюзивную аренду. При успехе возвращает полный (незамаскированный) номер телефона.

Параметры

Имя	Тип	Обязательный	Описание
phoneId	string	обязательный	ID порта из /api/v1/numbers/available
billingCycle	string	обязательный	DAILY \| WEEKLY \| MONTHLY
cycles	number	необязательный	Количество расчётных периодов для предоплаты (1–12, по умолчанию 1)
autoRenew	boolean	необязательный	Автопродление по окончании срока (по умолчанию false)

Ответы

200 OKАренда создана — полный номер телефона в ответе

402 Payment RequiredНедостаточно средств или для этого периода не настроена цена

409 ConflictНомер только что арендовал другой партнёр — повторите попытку с другим номером

401 UnauthorizedНедействительный или отсутствующий ключ API

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

curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"phoneId":"clx...","billingCycle":"MONTHLY","cycles":1}' \
  https://www.kartesim.com/api/v1/numbers/rent

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

{
  "rentalId":     "cly...",
  "phoneNumber":  "+212661234567",
  "countryCode":  212,
  "carrier":      "Orange",
  "billingCycle": "MONTHLY",
  "pricePerCycle": 8.00,
  "cycles":        1,
  "totalCharged":  8.00,
  "autoRenew":     false,
  "startedAt":    "2026-06-21T20:00:00.000Z",
  "expiresAt":    "2026-07-21T20:00:00.000Z"
}

GET/api/partner/rentals

Получить все активные аренды номеров вашего аккаунта.

Ответы

200 OKJSON-массив активных аренд номеров

401 UnauthorizedНедействительный или отсутствующий ключ API

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

curl -H "x-api-key: YOUR_KEY" https://www.kartesim.com/api/partner/rentals

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

[
  {
    "id": "cuid...",
    "phoneNumber": "+212661234567",
    "maskedNumber": "+212 6** *** **7",
    "countryCode": 212,
    "expiresAt": "2026-06-25T10:00:00.000Z",
    "daysRemaining": 26
  }
]

Номера закрепляются за вашим аккаунтом. В течение срока аренды номер никогда не передаётся и не переназначается другим. Сумма за весь период списывается в момент аренды. Если выбранный номер заняли между просмотром и арендой, вы получите ответ 409 — повторите попытку с другим номером.

Аренда прокси

Каждый порт в парке предоставляет HTTP- и SOCKS5-прокси через своё мобильное подключение к интернету. Партнёры могут направлять трафик через эти прокси, чтобы получить реальный мобильный IP нужной страны.

Протокол	Порт по умолчанию	Примечания
HTTP	зависит от устройства	Прокси HTTP CONNECT — порт указан в партнёрском портале и в `/api/partner/proxies`
SOCKS5	1080	Прокси SOCKS5 — поддерживает туннелирование TCP и UDP

HTTP-прокси — curl

curl --proxy http://USER:PASS@PHONE_IP:8888 https://api.ipify.org

SOCKS5-прокси — curl

curl --proxy socks5://USER:PASS@PHONE_IP:1080 https://api.ipify.org

Учётные данные и IP прокси предоставляет ваш менеджер. IP порта обновляется автоматически при каждом heartbeat — партнёрский портал всегда показывает последний IP. Для доступа к прокси нужна аутентификация — подключения без неё отклоняются.

Просмотр активных прокси

Ваши активные подписки на прокси — с текущим IP, портом и сроком действия — видны в партнёрском портале в разделе Прокси. Поле IP обновляется в реальном времени, когда порт сообщает свой адрес.

Поддерживаемые страны

Используйте getCountries, чтобы получить актуальный список. Распространённые коды стран:

Код	Страна	Код	Страна
0	Любая (автовыбор)	7	Russia
212	Марокко	33	Франция
1	Соединенные Штаты	44	Великобритания
49	Германия	34	Испания
966	Саудовская Аравия	971	ОАЭ
20	Египет	216	Тунис

Справочник ошибок

Ответ	Значение
BAD_KEY	Недействительный, отозванный или отсутствующий ключ API
BAD_ACTION	Неизвестное действие или не указаны обязательные параметры
TOO_MANY_REQUESTS	Превышен лимит запросов — 120 запросов в минуту
NO_NUMBERS	Нет доступных онлайн-портов для вашего OTP-запроса
NO_BALANCE	Недостаточно средств для создания OTP-сессии
STATUS_WAIT_CODE	OTP ещё не получен — продолжайте опрос
STATUS_OK:code	OTP получен — цифровой код следует после двоеточия
STATUS_CANCEL	Сессия истекла или была отменена
ACCESS_NUMBER:id:num	OTP-сессия создана — далее следуют ID сессии и номер телефона
ACCESS_CANCEL	Сессия отменена, средства возвращены
ACCESS_READY	Сессия принята / подтверждена

Документация для партнёров kartesim — по вопросам ключей API и аренды обращайтесь к вашему менеджеру.