h1. HTTP API dlr

{{>toc}}

Sends Delivery Receipt to a message originator.

Logic of work is following:
1. Server Smartswitch sends a message to a client.
2. Client receives a message. In case if thee message has been successfully handled, client returns message_id to the Smartswitch server.
3. Client send a Delivery Receipt, when the message has been displayed on a terminal of an end user, or when message delivery has failed.

Between 2 and 3 can pass quite a long time interval.
For example, if end user is offline.
In this case client can place the message in a buffer, respond to Smartswitch server, that message has been successfully handled, and wait to end user coming back online during 3 days.
Upon user coming appearing online, client sends to Smartswitch server delivery receipt using this API.

h2. Arguments

| *argument* | *mandatory* | *description* |
| _login | yes | coincides with the user / company login to the personal account |
| _password | yes | matches the user / company password to the personal account |
|message_id|yes|ID of a message.
It should match with message ID, which has been returned to Smartswitch server upon acceptance of a message by a client|
|message_state|yes|one of: enroute, delivered, expired, undeliverable, accepted, unknown, rejected|
|request_id| no | Value, assigned by client.
Will be returned to client in response|

h2. Returned data

Server returns response in "JSON API":https://jsonapi.org/format/ format.
Response will contain one of:

* *errors*.
  Array of errors, occured when processing the request.
* *data*.
  JSON object, which contains request results, in case if request from client contains 1 number.
  Array of JSON objects, in case if request from client contains several numbers.

*errors* and *data* will not be present in 1 response simultaneously.
Each response contains either *errors*, or *data*.
  
*data* can contain following attributes:
|*attribute*|*mandatory*|*description*|
|id|yes|response ID assigned by server|
|type|yes|"dlr"|
|request_id|yes, if client has passed request_id inside the request|argument that has been passed by the client|

*errors* can contain following attributes:
|*attribute*|*mandatory*|*description*|
|code|yes|Short error code.
Can be used by a client for conditional error handling.
It doesn't depend on a client's locale.|
|detail|yes|Error details.
Can be used by a client to display inside contents of a error dialog.
Can be returned by the server in a locale of a client.|
|title|yes|Error title.
Can be used by a client to display in the header of the error dialog.
Can be returned by the server in a locale of a client.|

h2. Examples

h3. Report of a delivery of 1 message

|*request*|POST "https://your.server.name/api/dlr?message_id=1561370632513&message_state=delivered&request_id=1&_login=LOGIN&_password=PASSWORD"|
|*response*|<pre>
{
	"data" : {
		"attributes" : {
			"status" : "ok"
		},
		"id" : "1561370632713",
		"meta" : {
			"request_id" : "1"
		},
		"type" : "dlr"
	}
}
</pre>|

h3. Report of a delivery of 2 messages

|*request*|POST "https://your.server.name/api/dlr?message_id=1561370632513&message_state=delivered&request_id=1&message_id=1561370632522&message_state=delivered&request_id=2&_login=LOGIN&_password=PASSWORD"|
|*response*|<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. Error

|*request*|POST "https://your.server.name/api/dlr?message_id=1561370632513&message_state=delivered&request_id=1&_login=LOGIN&_password=PASSWORD"|
|*response*|<pre>
{
	"errors" : [
		{
			"code" : "authentication",
			"detail" : "Please check your login and password",
			"title" : "Authentication error"
		}
	]
}
</pre>|

[[HTTP интерфейс dlr|Русский перевод]]