Документація REST API
REST API для SMS і MMS
Надсилайте схвалені повідомлення застосунків і обробляйте прийняття, події доставки, сегментацію та нарахування.
Обирайте 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.
Підготовка запиту SMS
Використовуйте схвалений номер відправника з підтримкою SMS, що належить обліковому запису, одержувача, який погодився на повідомлення, і потрібну реєстрацію Brand/Campaign або перевірку номера з безкоштовними дзвінками для абонента. Наведений нижче приклад надсилає справжнє повідомлення, якщо його заповнено робочими обліковими даними та номерами; це не пісочниця.
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
--request POST \
--header "Content-Type: application/json" \
--data '{"from":"YOUR_APPROVED_NUMBER","to":"YOUR_CONSENTED_RECIPIENT","text":"Your requested update is ready."}' \
"https://api.multitel.net/v3/sendsms"Замініть заповнювачі відправника й одержувача телефонними номерами в міжнародному форматі: лише цифри, включно з кодом країни. Для MMS вкажіть у media підтримувану, публічно доступну URL-адресу медіафайлу та спершу перевірте умови доступу до MMS і ціну.
Прийняття — це не доставлення
Перевіряйте і зовнішній статус застосунку, і повернутий результат обміну повідомленнями. Записуйте ідентифікатор повідомлення, наданий службою, і стежте за статусом доставлення та подіями вебхуків. Успішне подання не може довести, що телефон одержувача отримав повідомлення.
SMS тарифікуються за сегментами. Кодування та довжина повідомлення можуть утворити кілька сегментів; плата за медіа та пов’язана з оператором може відрізнятися від SMS. Перед надсиланням ознайомтеся з поточною ціною продажу для вашого облікового запису. Ніколи сліпо не повторюйте надсилання після тайм-ауту: спершу перегляньте записаний результат.
Обробка помилок і повторних спроб
- Збій автентифікації або дозволів
- Перевірте, чи ввімкнено облікові дані API, яку послугу дозволено та які обмеження діють для IP-адреси джерела. Cookie сеансу порталу не є обліковими даними для інтеграції.
- Недостатньо коштів або невиконане погодження
- Перш ніж повторювати операцію, усуньте проблему з балансом рахунку, погодженням надсилання або вимогою щодо документів.
- Немає результату
- Сприймайте порожній перелік номерів або відсутнє ім’я абонента як звичайний результат. Не припускайте, що синтаксично коректний номер має всі служби.
- Тайм-аут мережі або збій служби
- Для читання використовуйте обмежену кількість повторних спроб із затримкою, що зростає. Для купівлі, надсилання або реєстрації спершу перевірте стан операції: повторення прийнятого запиту може продублювати платну дію.
Підтримка ідемпотентності залежить від сімейства API. Emergency API підтримує ключі повторних спроб, але це не робить довільні запити v3 ідемпотентними. Зберігайте для служби підтримки часові позначки, повернуті ідентифікатори та відповіді, з яких вилучено конфіденційні дані.
Продовжте з довідником вашого облікового запису
Довідник після входу фільтрує операції відповідно до ваших дозволів і підключених послуг. Користуйтеся його точним хостом, типом облікових даних, полями запиту та схемою відповіді. Консолі можуть виконувати реальні операції, зокрема покупки та надсилання повідомлень.