Distribution Channel API Guide

This guide outlines the API calls that should be made when moving a P2PE Device from a KIF to a Client via a Distribution Channel. For instruction on how to create a Device follow the KIF User Guide to the Management APIs

📘

API vs GUI

The following guide describes an API integration for the distribution of a Device from the perspective of the KIF, the Distribution Channel and the Client. Not all parts of this guide have to be integrated via APIs. All actions can be completed on the GUI as well as the APIs. It may be the case that a Distribution Channel integrates to the APIs and the Client uses the GUI.

KIF Actions

When creating a shipment entry via the POST shipments endpoint the KIF must specify 1) the Distribution Channel that is going to receive the Devices, 2) the Distribution Channel's Partner, 3) a location associated with the Distribution Channel, and 4) a list of Device serial number and tamper number pairs. For example:

POST https://cert-apis.p2pemanager.com/api/v1/shipments
Authorization: Basic dXNlcjpwYXNzd29yZA==

{
    "location": {
        "id": 33668
    },
    "kif": {
        "id": 4
    },
    "dcKif": {
        "id": 8 //Where 8 is Distribution Channel’s id
    },
    "carrier": "UPS",
    "tracking": "1Z999AA10123456784",
    "dateShipped": "2017-12-15 15:45:34",
    "items": [
        {
            "tamperLabel": "650WHF6849",
            "serialNumber": "123123123"
        }
    ]
}

The response object will contain the new shipping entry's ID. At this point the Device state has been set to inTransit.

{
    "id": 323
}

Distribution Channel Actions

The distribution Channel can list all inbound shipments.

GET https://cert-apis.p2pemanager.com/api/v1/shipments?kif=8&direction=incoming&take=2&skip=0
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
    "total": 1,
    "data": [

        {
            "id": "73",
            "carrier": "UPS",
            "tracking": "1Z999AA10123456784",
            "dateShipped": "2017-12-15T21:45:34.000Z",
            "dateReceived": null,
            "partner": {
                "id": 6580,
                "name": "ASM Software"
            },
            "kif": {
                "id": 4,
                "name": "Kriptithe Technologies"
            },
            "kif": {
                "id": 8,
                "name": "Acme DC"
            },
            "shipmentType": "KIF Shipment",
            "version": 0
        }
    ]
}

When the Distribution Channel receives the shipment they can register the even by making an API call to the Device the /api/v1/devices/receive endpoint.

POST https://cert-apis.p2pemanager.com/api/v1/devices/receive
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
    "tamperLabel": "650WHF6849",
    "serialNumber": "123123123"
}

Response:

{
    "id": 4532
}

If the Distribution Channel isn't shipping the device to a Client right away they can set it's state to stored.

PATCH https://cert-apis.p2pemanager.com/api/v1/devices/175108
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
    "deviceState": {
        "name": "stored"
    }
}

Ship Device to Client

When it comes time to allocate a Device to a Client the Distribution Channel can update the client record on the Device with the following API call.

PATCH https://cert-apis.p2pemanager.com/api/v1/devices/175108
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
    "client": {
        "id": "4684",
        "name": "The Tired Window"
    }
}

Response:

{
    "id": 175108
}

When creating a shipment entry via the POST shipments endpoint the Distribution Channel must specify:

  1. The Client that is going to receive the Devices
  2. The Client's Partner
  3. The Client's location
  4. A list of Device serial number and tamper number pairs
POST https://cert-apis.p2pemanager.com/api/v1/shipments
Authorization: Basic dXNlcjpwYXNzd29yZA==

{
    "partner": {
        "id": "6580"
    },
    "client": {
        "id": "4684"
    },
    "location": {
        "id": 33778
    },
    "carrier": "UPS",
    "tracking": "1Z999AA10123456784",
    "dateShipped": "2017-12-15 15:45:34",
    "items": [
        {
            "tamperLabel": "500WHF7070",
            "serialNumber": "123123123"
        }
    ]
}

Response:

{
    "id": 547345
}

Client Actions

When the Client receives the shipment they can register the even by making an API call to the Device the /api/v1/devices/receive endpoint.

POST https://cert-apis.p2pemanager.com/api/v1/devices/receive
Authorization: Basic dXNlcjpwYXNzd29yZA==
{
    "tamperLabel": "500WHF7070",
    "serialNumber": "123123123"
}

Response

{
    "id": 3452
}

After the Device is received an API call should be made to the /api/v1/devices/receive endpoint that sets the Device state to activating. Note: this action is automatically completed when a Client received a Device shipment on the P2PE Manager GUI.

PATCH https://cert-apis.p2pemanager.com/api/v1/devices/175108
Authorization: Basic dXNlcjpwYXNzd29yZA==

{
    "deviceState": {
        "name": "activaing"
    }
}

Response:

{
   "id": 175108
}

At this point the Client must complete a decryption on the terminal to complete the setup.


Did this page help you?