Адрес и авторизация

Адрес API — https://api.gratio.net. Он же — адрес для загрузки файлов (mediaUrl). Метод можно вызвать в одной из двух форм — они равноправны.

Форма Green API

Токен — последней частью пути:

https://api.gratio.net/waInstance{idInstance}/{method}/{apiTokenInstance}

curl "https://api.gratio.net/waInstance7100000001/getStateInstance/$GRATIO_TOKEN"

Префикс /v3 (как у Green API для MAX) тоже принимается: /v3/waInstance{idInstance}/….

Форма с заголовком

Токен — в заголовке Authorization, в пути его нет:

https://api.gratio.net/v1/instances/{idInstance}/{method}
Authorization: Bearer {apiTokenInstance}

curl https://api.gratio.net/v1/instances/7100000001/getStateInstance \
  -H "Authorization: Bearer $GRATIO_TOKEN"

Эту форму удобнее держать в секрете: токен не попадает в журналы серверов и прокси.

Та же форма в коде:

Python

import os
import requests

url = f"{os.environ['GRATIO_URL']}/v1/instances/{os.environ['GRATIO_ID']}/getStateInstance"
headers = {"Authorization": f"Bearer {os.environ['GRATIO_TOKEN']}"}
print(requests.get(url, headers=headers, timeout=60).json())

Node.js

const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const response = await fetch(`${GRATIO_URL}/v1/instances/${GRATIO_ID}/getStateInstance`, {
  headers: { Authorization: `Bearer ${GRATIO_TOKEN}` },
});
console.log(await response.json());

PHP

<?php
$url = getenv('GRATIO_URL') . '/v1/instances/' . getenv('GRATIO_ID') . '/getStateInstance';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('GRATIO_TOKEN')],
    CURLOPT_RETURNTRANSFER => true,
]);
print_r(json_decode(curl_exec($ch), true));

Примеры на страницах методов написаны в форме Green API — её понимают приложения, перешедшие с Green. Любой из них переводится на форму с заголовком заменой адреса: {GRATIO_URL}/waInstance{id}/{method}/{token} → {GRATIO_URL}/v1/instances/{id}/{method} и заголовок Authorization.

Запросы

• Методы с телом — POST с Content-Type: application/json. Файлы — multipart/form-data (sendFileByUpload, setGroupPicture, sendStory) или сырое тело (uploadFile).
• Методы без тела — GET, параметры — в строке запроса: getStateInstance, getSettings, receiveNotification?receiveTimeout=20, lastIncomingMessages?minutes=60.
• deleteNotification — DELETE, номер уведомления — после токена: /waInstance{id}/deleteNotification/{token}/{receiptId}.
• Имя метода — без учёта регистра: sendMessage и SendMessage — одно и то же.
• Кодировка — UTF-8.

Неверный idInstance или токен — 401. Неизвестный метод — 404.

Пределы

Свои пределы есть и у каждого канала: сколько сообщений в секунду, как часто создавать группы, искать номера и вступать в чаты. Они защищают номер от блокировки — см. Темп и лимиты.

Тайм-ауты клиента

Некоторые методы отвечают не сразу:

• отправка ждёт своей очереди в темпе канала — до ~30 с при залпе сообщений;
• sendMessage с typingTime ждёт, пока идёт «печатает»;
• receiveNotification ждёт новое уведомление до receiveTimeout секунд;
• при перезапуске сервиса Gratio метод, которому нужен живой сеанс, ждёт до 15 с и выполняется.

Ставьте тайм-аут HTTP-клиента не меньше 60 секунд для отправки и не меньше receiveTimeout + 10 для очереди.

Обновления Gratio

Сеансы каналов работают в отдельном процессе. Пока его обновляют, API отвечает, а методы, которым нужен живой сеанс (отправка, история, группы, звонки), ждут до 15 секунд и выполняются — ответ просто приходит позже. Отказ 503 unavailable с Retry-After — только если процесс каналов недоступен дольше. Повторять отправку в этот момент безопасно: внутри Gratio она идёт с одним ключом, второго сообщения не будет.

Что дальше

• Идентификаторы чатов и сообщений — что передавать в chatId и idMessage.
• Ответы и ошибки — как отвечает API и когда повторять запрос.