API Documentation

General Instructions

Welcome to the API documentation! This page provides information about the available API endpoints and their usage. Please review the documentation before making API calls.

Base URL: Will be provided for staging and production environments

Requirements:

Authentication: The API requires authentication using an bearer token. Include the token in the Authorization request header Authorization: Bearer the_provided_api_token.

Pickup location code: You will have one unique identifier per pickup location which will be provided by SLM.

POST /api/v1/shipping_order

Creates a new shipping order in the database and returns a voucher to be printed and stuck on the parcel.

Instructions about the pickup date and times: The pickup date must be the date the order will be ready for pickup from the merchant location. At pickup times you can use either the morning pickup window (10:00-14:00) or the afternoon one (15:00-17:00). Please note that you can use today as a pickup date with the afternoon pickup window but only if the order is created until 14:00.

Endpoint: POST /api/v1/shipping_order

Variables:

Name Type Explanation
customer_reference string The customer reference (Your internal unique identifier of the order)
is_return boolean Indicates if the shipment is a return (Always use false)
number_of_parcels number The number of parcels (Always use 1. Multiple-package orders are not supported for locker deliveries.)
pickup_date string ("YYYY-MM-DD") The date of the order pickup
pickup_location_code string The unique code for the pickup location. It corresponds to a pre-agreed location for picking up parcels. A merchant can have multiple pickup location codes where each one corresponds to a different pickup location.
pickup_notes string Any additional notes for the pickup
pickup_time_from UTC datetime The start time of the pickup time window
pickup_time_to UTC datetime The end time of the pickup time window
recipient_name string The full name of the recipient
recipient_phone string The mobile phone number of the recipient
sender_phone string The phone number of the merchant
skroutz_point_id string The ID of the chosen Skroutz Point locker from the map (Mandatory for Skroutz Point delivery)
recipient_street_name string Street name of the recipient's address (Mandatory for home delivery)
recipient_street_number string Street number of the recipient's address (Mandatory for home delivery)
recipient_city string City of the recipient's address (Mandatory for home delivery)
recipient_zip string Zip code of the recipient's address (Mandatory for home delivery)
weight number The weight of the parcel
estimated_slot_size string Estimated slot size where the parcel fits. Possible values: {null, 'S', 'S_SB', 'M', 'M_SB', 'L', 'L_SB', 'XL'}

Locker Delivery Example Request Body:

{
  "customer_reference": "CustRef123",
  "is_return": false,
  "number_of_parcels": 1,
  "pickup_date": "2023-06-22",
  "pickup_location_code": "zbamies",
  "pickup_notes": "Απο την πλαινή πόρτα",
  "pickup_time_from": "2023-06-22T12:00:00+00:00",
  "pickup_time_to": "2023-06-22T14:00:00+00:00",
  "recipient_name": "Γιώργος Αποστολόπουλος",
  "recipient_phone": "6900000000",
  "sender_phone": "2100000000",
  "skroutz_point_id": "skroutz_demo",
  "weight": 2.5,
  "estimated_slot_size": 'S_SB'
}

Home Delivery Example Request Body:

{
  "customer_reference": "CustRef123",
  "is_return": false,
  "number_of_parcels": 1,
  "pickup_date": "2023-06-22",
  "pickup_location_code": "zbamies",
  "pickup_notes": "Απο την πλαινή πόρτα",
  "pickup_time_from": "2023-06-22T12:00:00+00:00",
  "pickup_time_to": "2023-06-22T14:00:00+00:00",
  "recipient_name": "Γιώργος Αποστολόπουλος",
  "recipient_phone": "6900000000",
  "sender_phone": "2100000000",
  "recipient_street_name": "Πλουτάρχου",
  "recipient_street_number": "10",
  "recipient_city": "Αθήνα",
  "recipient_zip": "10676"
  "weight": 2.5
}

Example Response:

{
  "success": true,
  "order_id": "soid123",
  "tracking_ids": ["X84K9ZN13K0W5"]
}

GET /api/v1/shipment/track/:tracking_id

Returns tracking information on the parcel delivery and pickup.

Endpoint: GET /api/v1/shipment/track/:tracking_id

Variables:

Name Type Explanation
tracking_id string The tracking ID of the shipment

Example Response:

{
  "success": true,
  "status_description": "picked_up",
  "courier_notes": "Parcel picked up",
  "picked_up_at": "2023-06-05T12:30:00+00:00",
  "delivered_at": null,
  "updated_at": "2023-06-05T12:30:00+00:00",
  "expected_day_of_delivery": null,
  "shipping_order_id": "order123"
}

Status descriptions:

[
  'awaiting_pickup',
  'picked_up',
  'assigned_to_courier_for_delivery',
  'delivered',
  'recipient_rejected',
  'returned_to_sender',
  'returning_to_sender',
  'attempted_delivery',
  'lost_or_damaged',
  'at_locker'
]

DELETE /api/v1/shipping_order/:order_id

Cancel an order any time before it is received by the customer.

Endpoint: DELETE /api/v1/shipping_order/:order_id

Example Response:

{
  "success": true
}

GET api/v1/shipping_order/voucher/:tracking_id

Returns the voucher on pdf or base64 encoded string

Endpoint: GET api/v1/shipping_order/voucher/:tracking_id

Variables:

Name Type Explanation
tracking_id string The tracking ID of the shipment
paper_size string The form of the voucher to print, can be 'thermal' or 'A4'
direct_download boolean If it is true it returns the voucher as pdf file, else as a base64 encoded string

PUT api/v1/shipping_order/:order_id

Used to reschedule the pickup date and time window for an order. Use the same instruction for these fields as in the order creation endpoint.

Endpoint: PUT api/v1/shipping_order/:order_id

Variables:

Name Type Explanation
pickup_date string("YYYY-MM-DD") The date of the order pickup
pickup_time_from UTC datetime The start time of the pickup time window
pickup_time_to UTC datetime The end time of the pickup time window

Example Request Body:

{
  "pickup_date": "2023-06-19",
  "pickup_time_from": "2023-06-19T12:00:00+00:00",
  "pickup_time_to": "2023-06-19T14:00:00+00:00"
}

Example Response:

{
  "success": true,
  "order_id": "soid123",
  "tracking_ids": ["X84K9ZN13K0W5"]
}

GET /mapwidget/list_all

Returns all available lockers for the consumer to choose from.

Endpoint: GET /mapwidget/list_all

Example Response:

{
    "skroutz_points": [
      {
        "id": "sb_roma_pizza_glyfada",
        "type": "locker",
        "name": "Skroutz Point Roma Pizza Γλυφάδα (Σοφίας Βέμπο)",
        "street_name": "Σοφίας Βέμπο",
        "street_number": "33",
        "city": "Γλυφάδα",
        "zip": "16561",
        "region": "Αττική",
        "working_hours": [
          {
            "to": "24:00",
            "day": "Monday",
            "from": "12:00"
          },
          {
            "to": "24:00",
            "day": "Tuesday",
            "from": "12:00"
          },
          {
            "to": "24:00",
            "day": "Wednesday",
            "from": "12:00"
          },
          {
            "to": "24:00",
            "day": "Thursday",
            "from": "12:00"
          },
          {
            "to": "24:00",
            "day": "Sunday",
            "from": "12:00"
          }
        ],
        "indoor": true,
        "lng": 37.880232923,
        "lat": 23.758159832,
        "model": "SwipboxInfinity",
        "active": true,
        "obsolete": false,
        "swipbox_version": "v2"
      }
    ]
  }