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

BASEURL: https://api.yimatongsms.com

Создать заказ

GET /api/order/createOrder

Параметры

Параметр	Тип	Обяз.	Описание
`secretKey`	str	Да	API ключ
`smsCountryId`	int	Да	ID сервиса страны (smsCountryId из каталога)
`buyNum`	int	Да	Количество (обяз.). Не меньше минимального количества покупки, указанного в каталоге (обычно 1).

Ответ

Параметр	Тип	Описание
`code`	int	Код: 0=успех (в т.ч. queryOrder в обработке); 400=бизнес-ошибка; 401=только createOrder неверный secretKey; 404=не найдено; 429=лимит; 500=ошибка сервера
`message`	str	Сообщение
`data.apiOrderId`	str	ID заказа

Успешный пример

{
  "code": 0,
  "message": "创建成功",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

Пример ошибки

{
  "code": 401,
  "message": "密钥无效或缺失",
  "data": null
}

Другие примеры: createOrder — async (code=0)

{
  "code": 0,
  "message": "处理中，请稍后查询",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

Другие примеры: createOrder — 401 invalid secretKey

{
  "code": 401,
  "message": "密钥无效或缺失",
  "data": null
}

Другие примеры: createOrder — 404 invalid country

{
  "code": 404,
  "message": "国家服务不存在或已停用",
  "data": null
}

Другие примеры: createOrder — 400 insufficient balance

{
  "code": 400,
  "message": "余额不足",
  "data": null
}

Другие примеры: createOrder — 500 create failed

{
  "code": 500,
  "message": "创建失败",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

Проверить заказ

GET /api/order/queryOrder

Параметры

Параметр	Тип	Обяз.	Описание
`apiOrderId`	str	Да	ID заказа

Ответ

Параметр	Тип	Описание
`code`	int	Код: 0=успех (в т.ч. queryOrder в обработке); 400=бизнес-ошибка; 401=только createOrder неверный secretKey; 404=не найдено; 429=лимит; 500=ошибка сервера
`message`	str	Сообщение
`data.apiOrderId`	str	ID заказа
`data.contents`	json(list)	Фиксированный формат списка contents, каждый элемент — одна строка контента заказа

Поля элемента data

Параметр	Тип	Описание
`data.contents[].contentId`	string	ID строки; параметр contentId для resolveNumber
`data.contents[].type`	int	1=текст, 2=строка со ссылкой getdata
`data.contents[].content`	string	Строка контента
`data.contents[].expiresAt`	string	Рекомендуемый срок получения SMS-кода (ISO-8601, местное время). После этого времени код может быть недоступен.

Успешный пример

{
  "code": 0,
  "message": "查询成功",
  "data": {
    "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721",
    "contents": [
      { "contentId": "806779395c1640c882e65aaf1aba21d9", "type": 2, "content": "13800138000----/api/order/getdata?contentId=806779395c1640c882e65aaf1aba21d9", "expiresAt": "2026-05-28T15:04:00" },
      { "contentId": "a1b2c3d4e5f6", "type": 2, "content": "13900139000----/api/order/getdata?contentId=a1b2c3d4e5f6", "expiresAt": "2026-05-28T15:08:00" }
    ]
  }
}

Пример ошибки

{
  "code": 404,
  "message": "订单不存在或无权限",
  "data": { "apiOrderId": "not-exists-order-id" }
}

Другие примеры: queryOrder — processing (code=0)

{
  "code": 0,
  "message": "处理中，请稍后查询",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721", "contents": [] }
}

Другие примеры: queryOrder — 404 not found

{
  "code": 404,
  "message": "订单不存在或无权限",
  "data": { "apiOrderId": "not-exists-order-id" }
}

Освободить номер

GET /api/order/resolveNumber

Освободить номера в заказе (без secretKey). GET BASEURL + /api/order/resolveNumber?apiOrderId=...; необязательный contentId (contents[].contentId из queryOrder) — одна строка, без него — все неосвобождённые строки без SMS. Строки с SMS освободить нельзя. При успехе message содержит информацию о возврате; code=400 при ошибке (можно повторить). Неподдерживаемый тип заказа — тоже 400.

Параметры

Параметр	Тип	Обяз.	Описание
`apiOrderId`	str	Да	ID заказа
`contentId`	str	необяз.	Необязательно. data.contents[].contentId из queryOrder; освобождает только эту строку

Ответ

Параметр	Тип	Описание
`code`	int	Код: 0=успех (в т.ч. queryOrder в обработке); 400=бизнес-ошибка; 401=только createOrder неверный secretKey; 404=не найдено; 429=лимит; 500=ошибка сервера
`message`	str	Сообщение
`data.apiOrderId`	str	ID заказа

Успешный пример

{
  "code": 0,
  "message": "已释放，退 0.050 USD",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

Пример ошибки

{
  "code": 400,
  "message": "号码已收到短信，无法释放",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

Другие примеры: resolveNumber — 400 has SMS

{
  "code": 400,
  "message": "号码已收到短信，无法释放",
  "data": { "apiOrderId": "f7f145f39f9d4f67a4f2cfdf1fd8e721" }
}

Другие примеры: resolveNumber — 404 not found

{
  "code": 404,
  "message": "订单不存在或无权限",
  "data": { "apiOrderId": "not-exists-order-id" }
}

Get Data

GET /api/order/getdata

Сначала /queryOrder. Для type=2: BASEURL + /api/order/getdata?contentId=... Ответ: только текст.

Параметры

Параметр	Тип	Обяз.	Описание
`contentId`	str	Да	Извлеките contentId из /api/order/getdata?contentId=...

Ответ

HTTP статус	Пример тела	Значение
`200`	`123456`	Успех; тело — обычный текст (например код SMS)
`400`	`invalid contentId`	Неверный contentId
`404`	`not found`	Контент не найден
`429`	`Too Many Requests`	Лимит запросов
`502`	`fetch error`	Не удалось получить содержимое

Успешный пример

Пример ошибки

not found

Другие примеры: getdata — 429 rate limited

Too Many Requests

Часто задаваемые вопросы (FAQ)

Q1. Какая структура data у queryOrder?

data — объект с apiOrderId и contents. Каждая строка: contentId, type, content; для SMS-верификации также expiresAt. contentId — необязательный параметр resolveNumber.

Q2. Как получить содержимое getdata?

При type=2 извлеките contentId и вызовите /api/order/getdata?contentId=... (текст).

Q3. В каком формате возвращается getdata?

getdata возвращает чистый текст без JSON-обертки.

Q4. Возвращает ли createOrder code=202?

Нет. И createOrder, и queryOrder в обработке возвращают code=0. Смотрите message и пустой ли contents; опрашивайте queryOrder.

Q5. В какой валюте баланс и списания?

Баланс, цена и суммы заказов — USD (до 3 знаков). В message возвраты тоже в USD, напр. «已释放，退 0.050 USD».