Основы

Идемпотентность

Сеть рвётся, и запрос приходится повторять. Чтобы повтор не создал второй контакт, вторую запись или второй звонок клиенту, передавайте в каждом запросе на создание заголовок Idempotency-Key - любую уникальную строку до 64 символов.

Заголовок

curl https://api.ru.dialogi.io/v1/contacts \
  -H "Authorization: Bearer dk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20195208" \
  -d '{"name": "Анна Смирнова", "phone": "+79101234567"}'

Заголовок обязателен в запросах на создание. Запросы на чтение (GET) и изменение (PATCH) его не учитывают - их повтор ничего не дублирует.

Вместо Idempotency-Key можно передать X-Idempotency-Key. Если есть оба, действует Idempotency-Key.

Что происходит при повторе

Ситуация	Ответ	Что делать
Тот же ключ, то же тело	Прежний ответ, заголовок `Idempotent-Replayed: true`	Ничего - это успех
Тот же ключ, другое тело	`409` idempotency-conflict	Новый ключ для нового запроса
Первый запрос ещё выполняется	`409` idempotency-in-progress	Повторить через пару секунд
Заголовка нет	`400` idempotency-key-required	Добавить заголовок

Удобный ключ - id действия в вашей системе, например номер заказа. Повтор того же действия сам получит тот же ключ, и дубля не будет. Для нового действия по тому же заказу нужен новый ключ, например order-20195208-2.

Ключ хранится 24 часа. Ответы с ошибкой не запоминаются - после исправления запроса можно повторить его с тем же ключом.

У заявок на звонок, записей и сообщений в диалог ключ, кроме того, закреплён за созданным объектом без срока - так повтор не закажет второй звонок, не займёт время второй раз и не отправит клиенту сообщение дважды. Повтор с тем же ключом и тем же телом вернёт этот объект, с другим телом - 409 idempotency-conflict.

У сообщений ключ закреплён за диалогом, в который ушло сообщение. Тот же ключ в запросе к другому диалогу в первые 24 часа - 409 idempotency-conflict, а позже отправит новое сообщение. Для каждого сообщения берите свой ключ.

Правила ключа

Длина от 1 до 64 символов: латинские буквы, цифры и символы _ - : .. Другой ключ - ошибка 400 idempotency-key-invalid.
Ключи идемпотентности разных ключей API не пересекаются. Одна и та же строка у двух ключей API - два независимых ключа.
«То же тело» значит буквально те же байты. Другой порядок полей или лишний пробел - уже другое тело и ответ 409. Сохраняйте тело запроса и при повторе отправляйте его без изменений.
Повтор возвращает тот же статус и то же тело, что и первый ответ. Исключение - повтор заявки, записи или сообщения позже, чем через 24 часа: статус тот же, а в теле объект в его текущем состоянии, например уже отменённая запись. Request-Id у повтора свой, и повтор тоже расходует лимит запросов.