Notification API for Zegoal
Вступление
Нотификации непосредственно клиенту выполняет только Zegoal. Биллинг нотифицирует внешнюю систему (Zegoal) через API о событиях. Все нотификации имеют тип и подтип (код нотификации), которые определяют событие, по которому было сформировано нотификацию и логику формирования (сроки, ...).
Описание API
REST API по HTTPS. Метод POST. Ключи (подпись) отправляются в заголовках сообщений.
В ответ получаем или успех (код = 200) или ошибку.
URL Zegoal
Для прод-сервера:
- основной сайт прода: `https://web.zegoal.com`
- нотификации будут обрабатываться по пути: `{subdomain}.zegoal.com/api/billing_notification/`
- пример subdomain: org1. Полный адрес обработки нотификации для каждого аккаунта храним в атрибуте contact.noti_user в account.
- пример пути для нотификаций для org1: https://org1.zegoal.com/api/billing_notification/
На стороне нашего клиента они используют отдельный сабдомен для КАЖДОГО АБОНЕНТА.
То есть один канал нотификации ожидает события ТОЛЬКО по одному абоненту.
Принимает POST запросы с форматом json. Ориентировалась на https://docs.true-item.com/display/ZEG/Notification+JSON+examples . Минимальная проверка - присутствие `billing_id`. Если обработка успешна - придёт http-код 2хх, конкретно сейчас приходит 201. Проблемы при обработке -> отрицательные коды(4хх или 5хх, в зависимости от степени проблемы).
Типы нотификаций
| № | Code | Описание | Триггер события | Время доставки | Приоритет | UseCase | |
|---|---|---|---|---|---|---|---|
| 1 | InvoiceForNewPeriod | Выставленный счет (1-ого числа) | планировщик | По расписанию, раз в сутки | При выполнения триггера на формирования инвойсов "с 1 по 1". Для всех аккаунтов в состоянии Active, Suspended, для которых сформировались инвойсы. | 1 | |
| 2 | InvoiceForNewProduct | Выставление счета при продаже нового продукта | real time, планировщик | Сразу после генерирования | После выполнения продажи продукта (любого типа) для аккаунта с типом Prepaid и формирования инвойса на предоплату нового продукта. Для всех аккаунтов в состоянии Trial, Active, Suspended. | 1 | |
| 3 | UnPaidInvoice | Все еще неоплаченный счет, не покрытый полностью (5, 7, 9 дней с момента выставления) | планировщик | По расписанию, раз в сутки | Для всех аккаунтов в состояниях Trial, Active, Suspended проверить, есть ли для него инвойсы c атрибутом Paid = No. | 1 | |
| 4 | AccountStateChange | Смена состояния аккаунта (с любого в любое) | real time, планировщик | Сразу после генерирования | После выполнения API SetLC. Для всех аккаунтов в состоянии Trial, Active, Suspended. | 1 | |
| 5 | TrialReminder | Остаток срока триального периода (5, 3, 1 день) | планировщик | По расписанию, раз в сутки | Для аккаунтов в состоянии Trial. | 1 | 1.7 |
| 6 | PercentOfBalanceUsed | % задач или единиц продукта использовано (50, 80, 100) | real time | Сразу после генерирования | 2 | ||
| 7 | ProductStateChange | Активация/Деактивация продукта (любого) | real time, планировщик | Сразу после генерирования | После выполнения API UpdateSoldProductLC. Для всех аккаунтов в состоянии Trial, Active, Suspended. | 1 | |
| 8 | NewPayment | Для аккаунта создан платеж | real time | Сразу после генерирования | После выполнения API AddPayment. Для всех аккаунтов в состоянии Trial, Active, Suspended. | 1 |
Подтипы нотификаций
| Тип (code) | Подтип (Код нотификации) | Описание | |
|---|---|---|---|
| 1 | InvoiceForNewPeriod | FromFirstToFirst | Новый счет по периоду с 1 по 1 число месяца |
| 2 | InvoiceForNewProduct | NewPrepaidProduct | Счет для предоплаты нового продукта |
| 3 | UnPaidInvoice | UnPaid5Days | Все еще неоплаченный счет 5 дней с момента выставления |
| 4 | UnPaid7Days | Все еще неоплаченный счет 7 дней с момента выставления | |
| 5 | UnPaid9Days | Все еще неоплаченный счет 9 дней с момента выставления | |
| 6 | AccountStateChange | AllStateChanges | Нотификация по всем сменам состояния |
| 7 | TrialReminder | 5DayReminder | 5 дней до завершения триального периода |
| 8 | 3DayReminder | 3 дня до завершения триального периода | |
| 9 | 1DayReminder | 1 день до завершения триального периода | |
| 10 | PercentOfBalanceUsed | 50Tasks | Использовано 50% баланса задач за текущий период |
| 11 | 80Tasks | Использовано 80% баланса задач за текущий период | |
| 12 | 100Tasks | Использовано 100% баланса задач за текущий период | |
| 13 | 50ProductUser | Использовано 50% баланса единиц продукта (пользователей) за текущий период | |
| 14 | 80ProductUser | Использовано 80% баланса единиц продукта (пользователей) за текущий период | |
| 15 | 100ProductUser | Использовано 100% баланса единиц продукта (пользователей) за текущий период | |
| 16 | ProductStateChange | AllStateChanges | Изменения состояния продуктов любого типа для аккаунта |
| 17 | NewPaymentCreated | AllTypePayment | Для аккаунта создан новый платеж |
Структура нотификаций
Нотификации состоят из корневых атрибутов (шапка) и атрибутов конкретного сообщения, которые могут отличаться для всех типов нотификаций.
Корневые атрибуты
| № | описание |
|---|---|
| 1 | ID сообщения |
| 2 | timestamp, когда произошло событие, по которому надо послать нотификацию |
| 3 | timestamp, когда было сгенерировано сообщение |
| 4 | timestamp, когда отправилась нотификация |
| 5 | Тип события (например, "PercentOfBalanceUsed" - нотификация по достижению порогового значения) |
| 6 | Код нотификации (например, "80% задач использовано") |
| 7 | Внутренний ID аккаунта (абонента) - Ti-Rate Account ID |
| 8 | Внешний ID аккаунта (абонента) - тот, который важен для ZeGoal |
| 9 | Атрибуты события (тело нотификации) |
| 10 | Код языка аккаунта TAD-1923 - Getting issue details... STATUS |
| 11 | Код валюты аккаунта TAD-1923 - Getting issue details... STATUS |
Атрибуты событий по типам
| Тип нотификации | Description and attributes | |
|---|---|---|
| 1 | InvoiceForNewPeriod | Содержит
На каждый инвойс высылается отдельное сообщение. |
| 2 | InvoiceForNewProduct | Содержит
На каждый инвойс высылается отдельное сообщение. |
| 3 | UnPaidInvoice | Содержит
На каждый неоплаченный инвойс отдельная нотификация. |
| 4 | AccountStateChange | Содержит
|
| 5 | TrialReminder | Содержит
|
| 6 | PercentOfBalanceUsed | Содержит
|
| 7 | ProductStateChange | Содержит
|
| 8 | NewPaymentCreated | Содержит
|