Документація REST API
REST API облікового запису та виставлення рахунків
Читайте баланс і дані про нарахування, доступні вашій схваленій інтеграції.
Обирайте API та облікові дані разом
Схвалені облікові записи з профілями «Розробники й автоматизація», «Бізнес» і «Постачальники комунікаційних послуг» можуть інтегрувати ввімкнені послуги. Індивідуальному розробникові не потрібно видавати себе за компанію. Для SMS/MMS із застосунків потрібні відповідне погодження надсилання та реєстрація. Послуга «Для приватних осіб і сімей» не має доступного клієнтам API для надсилання повідомлень.
| Сімейство API | Базова URL-адреса | Автентифікація та результат |
|---|---|---|
| Комунікації v3 | https://api.multitel.net/v3 | Схвалені облікові дані Basic; придатні надані токени лише для операцій, які їх підтримують. JSON status і response. |
| Реєстрація екстрених викликів | https://api.multi.tel/emergency | Схвалені облікові дані Basic або спеціально наданий доступ за bearer-токеном. JSON code, message і data. |
| REST-інтеграції порталу | Хост і операція, указані в довіднику розробника вашого облікового запису | Використовуйте задокументовані для цієї операції облікові дані, області доступу та схему. Запити із сеансу браузера використовують окремий інтерфейс. |
Перш ніж використовувати приклади, задайте MULTITEL_API_USERNAME і MULTITEL_API_PASSWORD через конфігурацію секретів вашого сервера. Ніколи не вбудовуйте їх у публічний JavaScript для браузера, URL-адреси чи систему контролю версій. Окремими обліковими даними можна керувати в розділі налаштувань інтеграції API.
Перший запит: прочитайте свій баланс
Це читання не купує послугу та не ініціює виклик чи повідомлення.
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
"https://api.multitel.net/v3/getbalance"API комунікацій v3 повертає результат застосунку всередині JSON-тіла. Перш ніж читати response, перевірте HTTP-статус і status.code; відхилений запит може не містити об’єкта відповіді. Значення кодів можуть бути рядками або числами.
{
"status": {
"code": 200,
"msg": ""
},
"response": {
"balance": "25.0000",
"currency": "USD",
"terms": "Prepaid"
}
}Це вигаданий приклад, а не баланс облікового запису. Сприймайте грошові значення як десяткові суми. Під час діагностики відхиленого запиту зберігайте повідомлення у відповіді сервера, попередньо прибравши з нього облікові дані.
Правильно користуйтеся даними про нарахування
Відповідь із балансом містить поточний баланс, валюту та умови оплати. Вона не вказує вартість майбутнього виклику й не є повним рахунком-фактурою. Для таких питань використовуйте відповідні операції тарифів і використання. Наявні номери можуть мати інші плани, ніж сьогоднішній каталог.
Обробка помилок і повторних спроб
- Збій автентифікації або дозволів
- Перевірте, чи ввімкнено облікові дані API, яку послугу дозволено та які обмеження діють для IP-адреси джерела. Cookie сеансу порталу не є обліковими даними для інтеграції.
- Недостатньо коштів або невиконане погодження
- Перш ніж повторювати операцію, усуньте проблему з балансом рахунку, погодженням надсилання або вимогою щодо документів.
- Немає результату
- Сприймайте порожній перелік номерів або відсутнє ім’я абонента як звичайний результат. Не припускайте, що синтаксично коректний номер має всі служби.
- Тайм-аут мережі або збій служби
- Для читання використовуйте обмежену кількість повторних спроб із затримкою, що зростає. Для купівлі, надсилання або реєстрації спершу перевірте стан операції: повторення прийнятого запиту може продублювати платну дію.
Підтримка ідемпотентності залежить від сімейства API. Emergency API підтримує ключі повторних спроб, але це не робить довільні запити v3 ідемпотентними. Зберігайте для служби підтримки часові позначки, повернуті ідентифікатори та відповіді, з яких вилучено конфіденційні дані.
Продовжте з довідником вашого облікового запису
Довідник після входу фільтрує операції відповідно до ваших дозволів і підключених послуг. Користуйтеся його точним хостом, типом облікових даних, полями запиту та схемою відповіді. Консолі можуть виконувати реальні операції, зокрема покупки та надсилання повідомлень.