Содержание
Интерактивная документация к API
https://promo-api.grattis.ru/explorer
Обязательные параметры запросов к API
partnerId – ваш идентификатор в партнерской программе
apiKeyId – ключ к API, получить его можно здесь: https://partner.grattis.ru/keys-api/new
Работа с каталогом
Каталог имеет структуру виде дерева, оно формируется за счет поля parentId (ссылка на идентификатор родителя). У верхнего уровня parentId равен 0.
Все категории
GET https://promo-api.grattis.ru/categories?partnerId=…&apiKeyId=…
Данные одной категории
GET https://promo-api.grattis.ru/categories/{id}?partnerId=…&apiKeyId=….
Где:
{id} – идентификатор нижней категории у которой нет потомков
Ответ: см. интерактивную документацию (Модель SiteCategory)
Данные одной категории (аудио-поздравления, имена)
Аудиопоздравления в списке отсортированы по популярности.
GET https://promo-api.grattis.ru/categories/{id}/data?partnerId=…&apiKeyId=….
Где:
{id} – идентификатор нижней категории у которой нет потомков
Ответ:
{
| type | number | Тип данных (1 – список поздравлений, 2 – список имен) |
| data | […] | Массив данных в зависимости от типа |
}
Данные выбранного имени
GET https://promo-api.grattis.ru/categories/{id}/names/{nameId}/data?partnerId=…&apiKeyId=…
Где:
{id} – идентификатор нижней категории
{nameId} – идентификатор выбранного имени
Аудио-поздравления
Данные поздравления
GET https://promo-api.grattis.ru/audio-cards/{id}?partnerId=…&apiKeyId=…
Где:
{id} – идентификатор аудио-поздравления
Ответ:
См. интерактивную документацию (Модель AudioCard)
MP3 Аудио-поздравления
GET https://cdn-static.grattis.ru/cards/{id}.mp3
Где:
{id} – идентификатор аудио-поздравления
Имена
Все имена
GET https://promo-api.grattis.ru/names?partnerId=..&apiKeyId=…
Ответ:
См. интерактивную документацию (Модель Names)
Данные одного имени
GET https://promo-api.grattis.ru/names/{id}?partnerId=…&apiKeyId=…
Где:
{id} – идентификатор имени
Ответ:
См. интерактивную документацию (Модель Names)
Страны
Нужны для поддержки платежей и звонков в разные страны
см. интерактивную документацию (Модель Country)
Все поддерживаемые страны
GET https://promo-api.grattis.ru/countries?partnerId=…&apiKeyId=…
Ответ:
Array<Country> см. интерактивную документацию (Модель Country)
Определение страны по IP
GET https://promo-api.grattis.ru/countries/{ip}/detect?partnerId=…&apiKeyId=…
Где:
{ip} – ip клиента
Ответ:
{
iso: “код страны”
}
Статус отправителя (опция подпись)
Опция подпись дает возможность клиенту, за дополнительную плату, подсказать имениннику, кто именно его поздравил.
Данные SenderStatus – статус отправителя (кем приходится – бабушка, друг, подруга и т. д.)
GET https://promo-api.grattis.ru/sender-statuses/{id}?partnerId=…&apiKeyId=…
Где:
{id} – идентификатор статуса отправителя
Ответ:
Array<SenderStatus> см. интерактивную документацию
Оплата
Формирование заказа
POST https://promo-api.grattis.ru/orders?partnerId=…&apiKeyId=…
BODY:
OrderData {
| productId* | number | Идентификатор аудио поздравления |
| phoneTo* | string | Телефон получателя |
| phoneFrom* | string | Телефон отправителя |
| countryTo* | string | Страна получателя (ISO например RU) |
| countryFrom* | string | Страна отправителя (ISO например RU) |
| dateTimeSend* | number | Желаемое время доставки (количество миллисекунд, прошедших с 1 января 1970) |
| signSenderStatusId | number | Идентификатор статуса отправителя (опция “подпись”) |
| signNameId | number | Идентификатор имени отправителя (опция “подпись”) |
| externalId | number | Ваш идентификатор заказа (для проверки статуса заказа) |
}
Ответ:
{
url: “ссылка на страницу оплаты”
}
Проверка статуса заказа
GET https://promo-api.grattis.ru/orders/external/{externalId}/status?partnerId=…&apiKeyId=...&secretKey=…&date=
Где externalId — внешний идентификатор, передается при создании заказа, формируется на стороне партнера
secretKey – секретный ключ API
Ответ: JSON – объект OrderStatus
OrderStatus {
| statusPayment | number | Статус оплаты (0 – в процессе оплаты, 1 – оплачен, -1 платеж не прошел) |
| statusSend | number | Статус доставки (0 – в процессе доставки, 1 – доставлен) |
}
Статистика: детальная за один день
GET https://promo-api.grattis.ru/orders/statistics/day?partnerId=…&apiKeyId=…&secretKey=…&date=
Где date — дата, за которую требуются данные по заказам, формат даты (yyyy-mm-dd)
secretKey – секретный ключ API
Если в вашем secretKey есть спецсимволы, то ключ надо кодировать. Можно использовать сервис вроде https://urlencoder.org/.
- secretKey до кодирования – $MtS)$&sd
- secretKey после кодирования – %24MtS%29%24%26sd
Ответ: JSON – Массив объектов OrderStatisticsDay
OrderStatisticsDay {
| id | number | Идентификатор заказа |
| externalId | number | Внешний идентификатор |
| date | string($date-time) | Дата заказа |
| promoType | string | Тип промо |
| promoId | string | Идентификатор промо |
| promoTitle | string | Название промо |
| phoneFrom | string | Телефон отправителя |
| countryFrom | string | Страна отправителя (ISO например RU) |
| isPayment | boolean | Оплачено? |
| paymentMethod | string | Метод оплаты |
| money | number | Сколько заработал партнер |
| utm_source | string | |
| utm_medium | string | |
| utm_campaign | string | |
| utm_content | string | |
| utm_term | string | |
| ip | string | IP адрес клиента |
}
Кэширование статистики. Как сбросить кэш и получить актульные данные?
У нас длительное кэширование данных до 4 дней. Чтобы сбросить кэш, попробуйте добавить лишний параметр ?v=1222 к запросу.