h1. HTTP интерфейс dlr

{{>toc}}

Отправляет отчет о доставке отправителю сообщения.

Логика работы:
1. Сервер Smartswitch отправляет сообщение поставщику.
2. Поставщик получает сообщение. В случае если сообщение было успешно обработано, возвращает серверу Smartswitch message_id.
3. Поставщик отправляет отчет о доставке, когда сообщение было отображено на терминале конечного абонента, либо когда доставка не удалась.

Между 2 и 3 может пройти большой интервал времени.
Например, если конечный абонент не в сети.
В этом случае поставщик может поместить сообщение в буфер, ответить серверу Smartswitch, что сообщение было успешно обработано, и ждать появления абонента в сети до 3 дней.
По появлению абонента в сети, поставщик отправляет серверу Smartswitch отчет о доставке посредством данного API.

h2. Аргументы

|*аргумент*|*обязательный*|*описание*|
|_login|да|совпадает с логином пользователя/компании к личному кабинету|
|_password|да|совпадает с паролем пользователя/компании к личному кабинету|
|message_id|да|ID сообщения.
Должно совпадать с ID сообщения, которое было возвращено серверу Smartswitch при приеме сообщения|
|message_state|да|одно из: enroute, delivered, expired, undeliverable, accepted, unknown, rejected|
|request_id|нет|назначаемый клиентом ID запроса, будет возвращен клиенту в ответе от сервера Smartswitch|

h2. Возвращаемые данные

Сервер возвращает ответ в формате "JSON API":https://jsonapi.org/format/.
В ответе может присутствовать одно из:

* *errors*.
  Массив ошибок, возникших при обработке запроса.
* *data*.
  JSON объект, содержащий результаты запроса, если запрос от клиента содержит 1 номер.
  Массив JSON объектов, если запрос от клиента содержит несколько номеров.

*errors* и *data* не присутствуют в 1 ответе одновременно.
Каждый ответ содержит либо *errors*, либо *data*.
  
*data* может содержать следующие атрибуты:
|*атрибут*|*обязательный*|*описание*|
|id|да|назначенный сервером ID сообщения|
|type|да|"dlr"|
|request_id|да, если клиент передал request_id в запросе|переданный клиентом аргумент|

*errors* может содержать следующие атрибуты:
|*атрибут*|*обязательный*|*описание*|
|code|да|Короткий код ошибки.
Может использоваться клиентом для условной обработки ошибки.
Не зависит от локали клиента.|
|detail|да|Детали ошибки.
Может использоваться клиентом для отображения в содержимом диалогового окна ошибки.
Может быть выдано сервером в локали клиента.|
|title|да|Заголовок ошибки.
Может использоваться клиентом для отображения в заголовке диалогового окна ошибки.
Может быть выдано сервером в локали клиента.|

h2. Примеры

h3. Отчет о доставке 1 сообщения

|*запрос*|POST "https://имя.вашего.сервера/api/dlr?message_id=1561370632513&message_state=delivered&request_id=1&_login=LOGIN&_password=PASSWORD"|
|*ответ*|<pre>
{
	"data" : {
		"attributes" : {
			"status" : "ok"
		},
		"id" : "1561370632713",
		"meta" : {
			"request_id" : "1"
		},
		"type" : "dlr"
	}
}
</pre>|

h3. Отчет о доставке 2 сообщений

|*запрос*|POST "https://имя.вашего.сервера/api/dlr?message_id=1561370632513&message_state=delivered&request_id=1&message_id=1561370632522&message_state=delivered&request_id=2&_login=LOGIN&_password=PASSWORD"|
|*ответ*|<pre>
{
	"data" : [
		{
			"attributes" : {
				"status" : "ok"
			},
			"id" : "1561371433517",
			"meta" : {
				"request_id" : "1"
			},
			"type" : "dlr"
		},
		{
			"attributes" : {
				"status" : "ok"
			},
			"id" : "1561371433518",
			"meta" : {
				"request_id" : "2"
			},
			"type" : "dlr"
		}
	]
}
</pre>|

h3. Ошибка

|*запрос*|POST "https://имя.вашего.сервера/api/dlr?message_id=1561370632513&message_state=delivered&request_id=1&_login=LOGIN&_password=PASSWORD"|
|*ответ*|<pre>
{
	"errors" : [
		{
			"code" : "authentication",
			"detail" : "Please check your login and password",
			"title" : "Authentication error"
		}
	]
}
</pre>|

[[HTTP API dlr|English translation]]