HTTP API dlr

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.

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

Returned data

Server returns response in JSON API format.
Response will contain one of:

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.

Examples

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 
{
    "data" : {
        "attributes" : {
            "status" : "ok" 
        },
        "id" : "1561370632713",
        "meta" : {
            "request_id" : "1" 
        },
        "type" : "dlr" 
    }
}

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 
{
    "data" : [
        {
            "attributes" : {
                "status" : "ok" 
            },
            "id" : "1561371433517",
            "meta" : {
                "request_id" : "1" 
            },
            "type" : "dlr" 
        },
        {
            "attributes" : {
                "status" : "ok" 
            },
            "id" : "1561371433518",
            "meta" : {
                "request_id" : "2" 
            },
            "type" : "dlr" 
        }
    ]
}

Error

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

Русский перевод