Обращения, сообщения и вложения

Результат

После подключения партнёр и менеджер Yario будут работать с одним обращением и общей историей сообщений. Отдельную копию диалога создавать не нужно.

Создайте обращение

Используйте POST /v1/installations/{installationId}/tickets. Ключ должен иметь разрешение tickets:write, а clientId — относиться к компании выбранного подключения.

POST /v1/installations/5bf6b037-6087-4e70-87e5-cce14774a74d/tickets HTTP/1.1
Api-Key: yario_test_...
Idempotency-Key: ticket-crm-48151-v1
Content-Type: application/json

{
  "clientId": "125cd83f-dc53-4425-95ab-91a487fb88d3",
  "summary": "Нужна проверка реквизитов",
  "description": "Клиент просит уточнить данные договора.",
  "externalReference": "crm-48151",
  "priority": "Regular",
  "attachments": []
}

Первый успешный запрос возвращает 201. Заголовок Idempotency-Key защищает от случайного создания дубля:

• тот же ключ и то же тело вернут уже созданное обращение;
• тот же ключ с другим телом вернёт 409.

Прочитайте или обновите обращение

• GET /v1/tickets/{ticketId} — получить актуальное состояние;
• PATCH /v1/tickets/{ticketId} — изменить только переданные поля;
• партнёр может изменить summary, status и priority;
• для каждого изменяющего запроса используйте отдельный стабильный Idempotency-Key.

Возможные состояния:

Приоритеты: обычный Regular, повышенный Sticky и срочный Emergency.

Обменивайтесь сообщениями

GET /v1/tickets/{ticketId}/messages возвращает сообщения по времени создания. Параметр after позволяет получить только новые сообщения, а limit — ограничить размер ответа от 1 до 200 элементов.

POST /v1/tickets/{ticketId}/messages добавляет сообщение партнёра. Текст может быть пустым только тогда, когда сообщение содержит хотя бы одно вложение.

Поле author показывает источник:

• partner — сообщение отправлено партнёром через Integration API;
• yario — сообщение добавил менеджер или другой канал Yario.

Передавайте вложения

Integration API получает не сам файл, а защищённую ссылку и метаданные:

{
  "name": "company-registration.pdf",
  "mimeType": "application/pdf",
  "url": "https://files.example.com/signed/company-registration.pdf",
  "hash": "sha256:7a9c..."
}

Ссылка должна использовать HTTPS и оставаться доступной на время обработки. Для персональных документов используйте краткоживущую подписанную ссылку. Передавайте hash, чтобы получатель мог проверить целостность файла.

Как понять, что всё работает

Создайте тестовое обращение, прочитайте его, обновите состояние, добавьте сообщение и получите это сообщение обратно через API. Затем повторите создание с тем же ключом идемпотентности и убедитесь, что дубль не появился.

Если идентификатор относится к другой среде или другой организации, API вернёт 404 и не раскроет существование чужого ресурса.

Навигация: начало работы · обзор API · безопасность ключей · ошибки и повторы · тестирование