Документация для разработчиков

Справочник API

Полный справочник по публичному API ApiCodes: каталог направлений, активация номера, проверка статуса, изменение статуса и прием входящих SMS в одном месте.

Базовый URL https://apicodes.org/api

TTL номера 5 минут

Стоимость $0.01

Код-примеры

Подставьте ваш API-ключ

Примеры ниже обновляются сразу после подстановки ключа. Если поле пустое, используется заглушка YOUR_API_KEY.

Техподдержка Telegram: @APIcodesbot

Краткий справочник

Основные маршруты API

Главные методы публичного каталога, API для разработчиков и входящего webhook-канала.

JSON API

Метод	Маршрут	Назначение	Обязательные поля
GET	`/api/catalog`	Страны, сервисы, маршруты и сводная статистика	—
GET	`/api/developer/balance`	Текущий баланс по API-ключу	`x-api-key`
POST	`/api/developer/activate`	Резерв номера по стране и сервису	`x-api-key`, `countryCode`, `serviceCode`
GET	`/api/developer/activation/{id}`	Статус активации и входящие сообщения	`x-api-key`, `id`
POST	`/api/developer/activation/{id}/status`	Завершение или отмена активации	`x-api-key`, `action`
POST	`/api/provider/inbound`	Прием входящего SMS от поставщика или оператора	`x-provider-token`, `phoneNumber`, `body`

Сценарий

Типовой порядок интеграции

Получите список доступных стран и сервисов через /api/catalog.
Зарезервируйте номер через /api/developer/activate.
Проверяйте /api/developer/activation/{id} каждые 5 секунд в течение 5 минут.
После получения входящего SMS активация перейдет в RECEIVED, и только в этот момент произойдет списание баланса.
Завершите активацию через action=complete или остановите ее через action=cancel.

Правила

Ошибки и поведение платформы

401 Unauthorized

{"error":"missing api key"} или {"error":"invalid api key"}.

400 Bad Request

invalid json payload, insufficient balance, unknown action, no numbers available for this route.

403 Forbidden

{"error":"invalid provider token"} для входящего webhook-запроса.

404 Not Found

{"error":"activation not found"} при запросе несуществующей активации.

Сервисы управляются вручную внутри платформы. Парсинг сервисов со стороны поставщиков не используется.
Стоимость номера всегда фиксирована и составляет $0.01.
Баланс не списывается в момент выдачи номера. Списание происходит только после реального получения кода.
Если на маршруте доступно несколько поставщиков, платформа автоматически использует рабочий канал и при необходимости переключается на резервный.

GET

/api/catalog

Публичный каталог стран, сервисов, маршрутов и общей статистики.

Параметры

Параметры отсутствуют, авторизация не требуется.

Ответ

Массивы countries, services, routes и блок stats.

curl https://apicodes.org/api/catalog

import requests

response = requests.get("https://apicodes.org/api/catalog")
data = response.json()
print(data["stats"])

const res = await fetch("https://apicodes.org/api/catalog");
const data = await res.json();
console.log(data.stats);

$response = file_get_contents("https://apicodes.org/api/catalog");
$data = json_decode($response, true);
print_r($data["stats"]);

GET

/api/developer/balance

Возвращает текущий баланс аккаунта и валюту.

Заголовки

x-api-key: YOUR_API_KEY или Authorization: Bearer YOUR_API_KEY.

Ответ

{"balanceCents":1499,"currency":"USD"}

curl https://apicodes.org/api/developer/balance \
  -H "x-api-key: __API_KEY__"

import requests

response = requests.get(
    "https://apicodes.org/api/developer/balance",
    headers={"x-api-key": "__API_KEY__"},
)
print(response.json())

const res = await fetch("https://apicodes.org/api/developer/balance", {
  headers: { "x-api-key": "__API_KEY__" }
});
const data = await res.json();
console.log(data);

$ch = curl_init("https://apicodes.org/api/developer/balance");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: __API_KEY__"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

POST

/api/developer/activate

Резервирует номер для выбранного сервиса и страны. Номер активен 5 минут.

Тело запроса

{"countryCode":"GB","serviceCode":"IG"}

Важно

Стоимость номера фиксирована: $0.01. Баланс списывается только после получения SMS-кода.

curl -X POST https://apicodes.org/api/developer/activate \
  -H "Content-Type: application/json" \
  -H "x-api-key: __API_KEY__" \
  -d '{"countryCode":"GB","serviceCode":"IG"}'

import requests

response = requests.post(
    "https://apicodes.org/api/developer/activate",
    headers={
        "x-api-key": "__API_KEY__",
        "Content-Type": "application/json",
    },
    json={"countryCode": "GB", "serviceCode": "IG"},
)
print(response.json())

const res = await fetch("https://apicodes.org/api/developer/activate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "__API_KEY__"
  },
  body: JSON.stringify({ countryCode: "GB", serviceCode: "IG" })
});
const data = await res.json();
console.log(data.activation);

$payload = json_encode([
    "countryCode" => "GB",
    "serviceCode" => "IG",
]);

$ch = curl_init("https://apicodes.org/api/developer/activate");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "x-api-key: __API_KEY__",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

{
  "activation": {
    "id": "1d9d7f0c-1f7b-4b0b-8f95-1a51c2c6b500",
    "reference": "ACT-GB-IG-2048",
    "phoneNumber": "+447400000101",
    "provider": "RackSim",
    "countryCode": "GB",
    "countryName": "United Kingdom",
    "serviceCode": "IG",
    "serviceName": "Instagram",
    "purchasePriceCents": 1,
    "status": "PENDING",
    "reservedUntil": "2026-05-06T12:05:00Z",
    "receivedAt": null,
    "closedAt": null,
    "messages": []
  }
}

GET

/api/developer/activation/{id}

Статус активации, выданный номер, поставщик и входящие сообщения.

Опрос

Запрашивайте этот маршрут каждые 5 секунд, пока статус не станет RECEIVED, COMPLETED, CANCELED или EXPIRED.

404

{"error":"activation not found"}

curl https://apicodes.org/api/developer/activation/ACTIVATION_ID \
  -H "x-api-key: __API_KEY__"

import requests
import time

activation_id = "ACTIVATION_ID"

while True:
    response = requests.get(
        f"https://apicodes.org/api/developer/activation/{activation_id}",
        headers={"x-api-key": "__API_KEY__"},
    )
    data = response.json()
    status = data["activation"]["status"]
    print(status)
    if status in {"RECEIVED", "COMPLETED", "CANCELED", "EXPIRED"}:
        break
    time.sleep(5)

const activationId = "ACTIVATION_ID";

async function pollActivation() {
  const res = await fetch(`https://apicodes.org/api/developer/activation/${activationId}`, {
    headers: { "x-api-key": "__API_KEY__" }
  });
  const data = await res.json();
  const status = data.activation.status;
  console.log(status, data.activation.messages);
  if (["RECEIVED", "COMPLETED", "CANCELED", "EXPIRED"].includes(status)) {
    return;
  }
  setTimeout(pollActivation, 5 * 1000);
}

pollActivation();

$activationId = "ACTIVATION_ID";
$ch = curl_init("https://apicodes.org/api/developer/activation/" . $activationId);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: __API_KEY__"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

POST

/api/developer/activation/{id}/status

Обновляет статус активации. Поддерживаются действия complete и cancel.

Тело запроса

{"action":"complete"} или {"action":"cancel"}

Ошибки

unknown action, activation is already finalized, activation does not belong to this account.

curl -X POST https://apicodes.org/api/developer/activation/ACTIVATION_ID/status \
  -H "Content-Type: application/json" \
  -H "x-api-key: __API_KEY__" \
  -d '{"action":"complete"}'

import requests

response = requests.post(
    "https://apicodes.org/api/developer/activation/ACTIVATION_ID/status",
    headers={
        "x-api-key": "__API_KEY__",
        "Content-Type": "application/json",
    },
    json={"action": "cancel"},
)
print(response.json())

const res = await fetch("https://apicodes.org/api/developer/activation/ACTIVATION_ID/status", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "__API_KEY__"
  },
  body: JSON.stringify({ action: "complete" })
});
const data = await res.json();
console.log(data.activation.status);

$payload = json_encode(["action" => "complete"]);

$ch = curl_init("https://apicodes.org/api/developer/activation/ACTIVATION_ID/status");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "x-api-key: __API_KEY__",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

POST

/api/provider/inbound

Webhook для входящих SMS. Может вызываться интеграцией поставщика или операторским потоком.

Заголовки

x-provider-token: YOUR_PROVIDER_TOKEN

Тело запроса

{"phoneNumber":"+447400000101","sender":"Instagram","body":"Your Instagram code: 483201"}

curl -X POST https://apicodes.org/api/provider/inbound \
  -H "Content-Type: application/json" \
  -H "x-provider-token: YOUR_PROVIDER_TOKEN" \
  -d '{"phoneNumber":"+447400000101","sender":"Instagram","body":"Your Instagram code: 483201"}'

import requests

response = requests.post(
    "https://apicodes.org/api/provider/inbound",
    headers={
        "x-provider-token": "YOUR_PROVIDER_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "phoneNumber": "+447400000101",
        "sender": "Instagram",
        "body": "Your Instagram code: 483201",
    },
)
print(response.json())

const res = await fetch("https://apicodes.org/api/provider/inbound", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-provider-token": "YOUR_PROVIDER_TOKEN"
  },
  body: JSON.stringify({
    phoneNumber: "+447400000101",
    sender: "Instagram",
    body: "Your Instagram code: 483201"
  })
});
const data = await res.json();
console.log(data.activation.status);

$payload = json_encode([
    "phoneNumber" => "+447400000101",
    "sender" => "Instagram",
    "body" => "Your Instagram code: 483201",
]);

$ch = curl_init("https://apicodes.org/api/provider/inbound");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "x-provider-token: YOUR_PROVIDER_TOKEN",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;