The Bilagscan API exposes a WebSocket endpoint to allow a consumer to subscribe to and listen for changes to specific resources. The WebSocket is exposed at /v1/websocket and is subject to the same authorization constraints and methods as any other endpoint.
It is important to note that the current version of the WebSocket endpoint only allows a user to listen for changes and does not have commands for creating and updating resources via the WebSocket. This has to be done via the respected endpoints for each resource.

Data transmission

The WebSocket uses UTF-8 encoded JSON for all messages. All messages are furthermore required to be JSON object of the following structure:

{
    "type": "<message type>",
    [any additional message data]
}

Requests and responses

The following message types can be transmitted from the client:
request

A command sent from the client, with the following basic structure:

{
    "type": "request",
    "command": "<command name>",
    "state": "<opaque client side reference for the request, such as a sequence number>",
    "data": <request data>
}

It is optional to pass a state, but it can be very helpful for tracking request/response relationships for a client.
response

A response from the server will be sent to the client, with the following basic structure:

{
    "type": "response",
    "status": "<response status>",
    "state": "<opaque client side reference for the request the server is responding to>",
    "data": <response data>
}

Note that a response does not always contain any data and that the state is only present if it was parseable from the client request.

The status can be one of:


success

The request was successful.

parse_error

The server failed to parse the client message.

invalid_type

The provided message type is not valid.

invalid_command

The provided command is not valid.

The client will now receive notifications whenever the particular resource is either updated or deleted. Please see the subscribe section for further details

Notifications

A notification from the server, likely due to a subscription by the client, with the following basic structure:

{
    "type": "notification",
    "event": "<event>",
    "data": <notification data>
}

The event can be one of:


resource_changed

The resource was changed. Data will contain the new resource ex data”:{"type":"voucher","id":5,"organization_id":1,"uploaded_by_user_id":1,...}.

resource_deleted

The resource was deleted. Data will the id of the resource and the type ex data: {"id":5,"type":"voucher"}.

Commands

The websocket endpoint currently supports 2 different commands; subscribe and unsubscribe:

Subscribe

To subscribe to notifications about changes to one or more resources, the client issues a subscribe request with the data being a list of resources:

{
    "type": "request",
    "state": "<opaque client side reference for the command>",
    "command": "subscribe",
    "data": [
        {
            "type": "<resource type>",
            "id": <ID>
        },
        [..]
    ]
}

Note that the provided ID must be integers just as in the rest of the API.

If successful, the server will respond with a success response:

{
    "type": "response",
    "state": "<same opaque client side reference as provided in the command>",
    "status": "success",
    "data": [
        {
            "type": "<resource type>",
            "id": <ID>,
            "status": <optional error code>
        },
        [..]
    ]
}

The status for a given resource can be one of:


subscribed

The client was successfully subscribed to the resource.

not_found

The resource was not found.

After this, the client will receive the following notification event types:


resource_changed

Emitted when a resource the client has subscribed to is changed. The data of the notification contains the data of the resource.

resource_deleted

Emitted when a resource the client has subscribed to is deleted. The data of the notification contains the type and ID of the resource.

Important: Subsequent to the response, the server will emit resource_changed notifications for the resources providing the state at the time of subscription to allow the client to be certain it has the latest state.

Available resource types:

The following resource types are supported:


voucher

Listen to changes on a particular voucher

file_posting

Listen to changes on a particular file posting

user

Listen to changes on a particular user

organization

Listen to changes on a particular organization

organization_status

Listen to changes on a particular organization’s vouchers

Example:
The following example shows how you can subscribe to the voucher with ID 5
request

{
    "type": "request",
    "state": "1",
    "command": "subscribe",
    "data": [
        {
            "type": "voucher",
            "id": 5
        }
    ]
}

response

{
    "type": "response",
    "state": "1",
    "status": "success",
    "data": [
        {
            "type": "voucher",
            "id": 5,
            "status": "subscribed"
        }
    ]
}

Immediately after a subscription has been established the endpoint will emmit a resource_changed notification so the client always have the current version of the resource:

{
    "type": "notification",
    "event": "resource_changed",
    "data": [
        {
            "type": "voucher",
            "id": 5,
            "organization_id":1,
            "status":"queued",
            "edited":null,
            "edited_in_web_app":null,
            "edited_in_affiliate":null,
            "edited_in_hdr":null
        }
    ]
}

When the voucher resource is updated the client will receive a resource_changed or resource_deleted event as soon as it happens with the appropriate data.

Unsubscribe

To unsubscribe from notifications about changes to one or more resources, the client issues an unsubscribe request with data analogous to that of the subscribe request:

{
    "state": "<opaque client side reference for the command>",
    "command": "unsubscribe",
    "data": [
        {
            "type": "<resource type>",
            "id": <ID>
        },
        [..]
    ]
}

To prevent excessive error handling, the server always responds with success even if the user is not subscribed to the provided resources.

Available resource types:

The following resource types are supported:


voucher

Unsubscribe to changes on a particular voucher

file_posting

Unsubscribe to changes on a particular file posting

user

Unsubscribe to changes on a particular user

organization

Unsubscribe to changes on a particular organization

organization_status

Unsubscribe to changes on a particular organization’s vouchers

Example:
The following example shows how you can unsubscribe to the file posting with ID 2
request

{
    "type": "request",
    "state": "1",
    "command": "unsubscribe",
    "data": [
        {
            "type": "file_posting",
            "id": 2
        }
    ]
}

response

{
    "type": "response",
    "state": "1",
    "status": "success"
}