Documentation

Public Carrier Protocol (PCP)

Introduction

The Public Carrier Protocol provides a way for any carrier to integrate with the delivery platform. As an integrator you will provide information shipment data to the platform. You will also receive information back to your systems when different events occur, i.e. a parcel has been delivered. Ingrid will provide you with the necessary credentials to connect to the platform. These are the steps involved in a typical delivery journey When the carrier receives a shipment booking, the carrier pre-advice the platform with shipment data. The parcel is arrival scanned at the store and the platform notifies the carrier that a parcel has been received and is ready to be picked up by consumer The carrier notifies the consumer that the parcel is ready to be picked up The consumer identifies themselves with a pre-authenticated QR code or an identity document. The platform requests validation from the carrier. If everything is ok, the parcel is handed out to the consumer. The platform notifies the carrier that the parcel has been delivered.

Sequence diagrams

Pre Advise

sequenceDiagram participant carrier as Carrier participant pcp as Ingrid PCP participant locker as Service Point / Locker carrier->>pcp: UpsertParcel pcp->>locker: UpsertParcel

Ingestion

sequenceDiagram participant locker as Service Point / Locker participant pcp as Ingrid PCP participant carrier as Carrier locker->>locker: Scan code locker->>pcp: Query(code) pcp->>pcp: Search pre-advised parcel alt Pre advised parcel not found pcp->>carrier: Query(code) carrier-->>pcp: Parcel data end pcp-->>locker: Parcel data locker->>locker: Accept parcel locker->>pcp: Ingested(parcel) pcp->>carrier: Ingested(parcel) carrier->>carrier: Notify recipient

Delivery

sequenceDiagram participant locker as Service Point / Locker participant pcp as Ingrid PCP participant carrier as Carrier locker->>locker: Scan receive code locker->>pcp:Query(receive code) pcp->>carrier:Query(receive code) carrier-->>pcp: OK pcp-->>locker: OK alt Parcel accpeted by recipient locker->>locker: Hand out parcel locker->>pcp: Delivered pcp->>carrier: Delivered else Parcle refused by customer locker->>pcp: Refused reason pcp->>carrier: Refused reason end

1st mile (Send / Customer return)

sequenceDiagram participant locker as Service Point / Locker participant pcp as Ingrid PCP participant carrier as Carrier locker->>locker: Scan drop off code locker->>pcp: Query(code) pcp->>carrier: Query(code) carrier-->>pcp: Parcel data pcp-->>locker: Parcel data locker->>locker: Accept parcel locker->>pcp: Accepted(parcel) pcp->>carrier: Accepted(parcel)

Overdue returns

sequenceDiagram participant locker as Service Point / Locker participant pcp as Ingrid PCP participant carrier as Carrier locker->>locker: List pending returns locker->>pcp: HandleReturns(tracking numbers) loop Loop over returns pcp->>carrier: /parcel/returned carrier-->>pcp: Parcel data end pcp-->>locker: Parcel data

API

In-Store side endpoints

Upsert parcel 🔗

Pre-advise parcel or to update already stored parcel/ For Ingrid to work as efficiently as possible it is required by the carrier to keep the In-Store system up-to-date with current parcel information. This includes pre-advicing parcel, that is, provide information about parcels which has been booked for a certain location. It also includes updating parcels already at location, i.e. if a parcel should be recalled to the merchant ahead of time.

Carrier side endpoints

Query a parcel

Query parcel by a given code. This endpoint is used for gathering more information about a parcel given for example a tracking number, a receive code or a drop-off code.

Request

GET /api/v1/parcel/query?code=997123123&location_id=123 HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

Response

{
  "parcel_id": "9971231233",
  "tracking_id": "string",
  "receive_code": "1234",
  "product_code": "instr-dummyproduct",
  "journey_stage": "JOURNEY_STAGE_LAST_MILE",
  "sender": {
    "name": "John Test",
    "phone": "987654321",
    "email": "john@test.com",
    "address": {
      "street": "437 Lytton",
      "city": "Palo Alto",
      "state": "CA",
      "country": "US",
      "zip": "94301"
    }
  },
  "recipient": {
    "name": "John Test",
    "phone": "987654321",
    "email": "john@test.com",
    "address": {
      "street": "437 Lytton",
      "city": "Palo Alto",
      "state": "CA",
      "country": "US",
      "zip": "94301"
    }
  },
  "dimensions": {
    "height": 1000,
    "width": 500,
    "length": 500
  },
  "weight": 2000,
  "is_identity_confirmed": false,
  "delivery_requirements": [
    {
      "type": "DELIVERY_REQUIREMENT_TYPE_CASH_ON_DELIVERY",
      "data": {
        "amount": 200,
        "currency": "USD"
      }
    }
  ],
  "blocker": {
    "blocked": true,
    "reasons": [
      {
        "language": "en-GB",
        "text": "Canceled by merchant."
      }
    ]
  }
}

Ingest a parcel 🔗

Acknowledge that a parcel is ingested so is dropped off by a courier in a given location. It concerns B2C parcels. It means that the parcel is physically stored in one of the locations either in a locker or on a shelf and from now on the parcel can be picked up by a customer. This is the time to notify the recipient that the parcel is ready to be picked up.

Request

POST /api/v1/parcel/ingested HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
  "parcel_id": "9971231233",
  "location_id": "9b6b047bfc1f4d06a2f5a567e5144345",
  "delivery_module": "MODULE_TYPE_RACK",
  "relocated": false
}

Response

{
  "receive_code": "1234"
}

Refuse a parcel 🔗

Acknowledge that a parcel is refused by a customer. It means that the customer refused to pick up the parcel. Reasons for refusing picking up a parcel includes for example damaged parcel and parcel not ordered

Request

POST /api/v1/parcel/refused HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
  "parcel_id": "9971231233",
  "deviation": {
    "comment": "Customer reports that a parcel is damaged.",
    "type": "DEVIATION_TYPE_GOODS_DAMAGED"
  }
}

Response

{
  "digital_receipt_sent": true,
  "receipt": {
    "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "content_type": "PDF"
  }
}

Deliver a parcel 🔗

Acknowledge that a parcel is successfully delivered to a customer.

Request

POST /api/v1/parcel/delivered HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
  "parcel_id": "9971231233",
  "recipient_identity_document": {
    "number": "123456789",
    "type": "DOCUMENT_TYPE_SWEDISH_DRIVING_LICENSE"
  },
  "proxy_identity_document": {
    "number": "123456789",
    "type": "DOCUMENT_TYPE_SWEDISH_DRIVING_LICENSE"
  },
  "deviation": {
    "comment": "Customer reports that a parcel is damaged.",
    "type": "DEVIATION_TYPE_GOODS_DAMAGED"
  }
}

Response

{
  "digital_receipt_sent": true,
  "receipt": {
    "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "content_type": "PDF"
  }
}

Return a parcel 🔗

Acknowledge that a parcel is returned. It means that the parcel previously ingested in a location is now returned. It's used for all return types except a customer return. Common case is an overdue return.

Request

Request

POST /api/v1/parcel/returned HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
  "parcel_id": "9971231233"
}

Response

{
  "label": {
    "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "content_type": "PDF"
  }
}

Accept a parcel 🔗

Acknowledge that a parcel is delivered to a given location by a customer and accepted by a staff member. It means that a parcel is physically in the location and waits to be picked-up by a driver. It applies only to customer parcels so C2B (customer returns) and C2C (send) parcels.

Request

POST /api/v1/parcel/accepted HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer base64-encoded-api-token

{
  "parcel_id": "9971231233",
  "location_id": "9b6b047bfc1f4d06a2f5a567e5144345"
}

Response

{
  "digital_receipt_sent": true,
  "document": {
    "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "content_type": "PDF"
  }
}

Last updated: Thu, Nov 21, 06:15 AM