m-michalis/boxnow-api

Document describes the API description for partners in order to create and track delivery requests. ## Revision history |Date|Author|Description|Version| |-|-|-|-| |2022-09-22|Šmolík, J.|Add accepted-to-locker parcel event |1.40| |2022-09-08|Šmolík J.| Add support for user to choose partner they w

Maintainers

Details

github.com/m-michalis/boxnow-php

Homepage

Source

Issues

Installs: 13

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 1

Open Issues: 0

v0.0.6-alpha 2023-05-22 09:49 UTC

Requires

Requires (Dev)

unlicense 4fd41955e0b834853370b16f08a4a16b160e698c

phprestapisdkopenapiopenapitoolsopenapi-generator

This package is not auto-updated.

Last update: 2024-04-22 14:16:05 UTC

README

Document describes the API description for partners in order to create and track delivery requests.

Revision history

Date Author Description Version
2022-09-22 Šmolík, J. Add accepted-to-locker parcel event 1.40
2022-09-08 Šmolík J. Add support for user to choose partner they want to work with 1.39
2022-08-10 Šmolík J. Add /labels:search to download PDF labels for defined criteria 1.38
2022-08-08 Azizov. J. Add region field to /destinations and /origins endpoints 1.37
2022-07-27 Vala J. Add EP for listing shipping label data of parcels order /api/v1/delivery-requests/{orderNumber}/label 1.36
2022-07-27 Vala J. Add EP for listing shipping label data of parcel /api/v1/parcels/{id}/label 1.35
2022-07-22 Vala J. Add destination_public_id column to csv export of parcels 1.34
2022-07-08 Vala J.
  • Add exportCsvUrl to headers ['X-export-url-csv'] to response from /api/v1/parcels
  • Add endpoint to export parcels to csv file /ui/v1/parcels.csv
 1.33
2022-06-27 Vala J. Add width and printerModel query parameters for zpl shipping labels for /api/v1/delivery-requests/{orderNumber}/label.{type} and /api/v1/parcels/{id}/label.{type} 1.32
2022-06-17 Šmolík, J. Allow to select return location for delivery request 1.31
2022-05-25 Vala, J. Add single labelUrlPdf to headers ['X-labels-url-pdf'] in response from /api/v1/delivery-requests:fromCsv 1.30
2022-05-25 Vala, J. Add EP to handle csv import orders printing of shipping label /ui/v1/delivery-requests/{orderImportsNumber}/label.pdf 1.29
2022-05-20 Vala, J. Add possibility to overwrite 4 rows in shipping label sender info to /api/v1/delivery-requests endpoint 1.28
2022-05-04 Azizov, J. Add state and created filters to to /api/v1/parcels endpoint 1.27
2022-05-03 Azizov, J. Add possibility to search parcels to /api/v1/parcels endpoint 1.26
2022-04-27 Azizov, J. Add /api/v1/delivery-requests:customerReturns for customer returns delivery requests 1.25
2022-04-26 Vala, J. Add createTime, updateTime to parcel list response 1.24
2022-04-21 Šmolík, J. Add payment info to parcels 1.23
2022-02-22 Azizov, J. Add P408 and P409 error codes 1.22
2022-02-22 Azizov, J. Add notifySMSOnAccepted to DeliveryRequest 1.21
2022-02-01 Šmolík, J.
  • Add check address delivery endpoint
  • Add /api/v1/simple-delivery-requests for simpler delivery creation
 1.20
2022-01-20 Šmolík, J. Add P405, P406 and P407 error codes 1.19
2022-01-10 Šmolík, J.
  • Add CSV import endpoint
  • Add JWT custom claims description
  • Move 403 error codes to own section
 1.18
2021-12-23 Šmolík, J.
  • Add new endpoint to confirm AnyAPM delivery of a parcel
  • Partition error codes by HTTP status response
 1.17
2021-12-16 Šmolík, J. Add new error code P403 1.16
2021-12-09 Šmolík, J. Add new error codes P401, P402 1.15
2021-11-30 Šmolík, J. Add delivery request origin, destination and items fields description 1.14
2021-11-11 Šmolík, J. Add endpoint for parcel delivery cancellation 1.13
2021-11-09 Šmolík, J. Add X403 error code spec 1.12
2021-10-14 Šmolík, J. Add Accepted for return event 1.11
2021-10-05 Šmolík, J. Make DeliveryRequest.items required 1.10
2021-09-22 Šmolík, J. Add canceled event state and event 1.9
2021-09-17 Šmolík, J. Add PDF label URLs to parcels response 1.8
2021-09-13 Šmolík, J.
  • Update parcel state enum values
  • Remove history event displayName, add type
 1.7
2021-08-25 Azizov, J.
  • Add possibility to print labels for all parcels in order
  • Make contact information of origin optional in delivery request
 1.6
2021-08-02 Azizov, J. Add items metadata to parcel 1.5
2021-07-15 Šmolík, J. Add destination expected delivery time 1.4
2021-06-23 Šmolík, J. Update money value fields description 1.3
2021-06-21 Šmolík, J.
  • Update Requesting a delivery text
  • Add name filter to origins and destinations
  • Rename delivery request code of description to plain description
  • Add more specific info to value amount fields
  • Update address country to match ISO Code
  • Update address postal code formatting
  • Update origin/destination for delivery request
  • Remove height, length, width from order item
  • Add events to parcel info
  • Update delivery request response
  • Update order number description
  • Add parcel id filter to /parcels
  • Add message to error
  • Make contact name required
  • Add delivery partner parcel ids
  • Remove order items' code and status
 1.2
2021-06-14 Šmolík, J.
  • Add a todo to specify client notification type after accepting the order.
  • Let the partner choose to receive an email when successful delivery request is made.
  • Remove typeOfOrder from delivery request.
  • Add option to select delivery partner for pickup
  • Make item weight in the order optional
  • Make origin contact email required
  • Add support to add sender's name when making delivery request
  • Remove landmark and code from address
  • Add new error code or partners not eligible to create COD delivery requests
  • Add support to filter destinations/origins by type
  • Add support to send compartment size for order item, required for APM origin
  • Make typeOfService optional
 1.1
2021-06-09 Šmolík, J. Initial version 1.0

Setup

Register your company through our support.

We are going to need

  • Company name
  • List of Phone numbers for SMS OTP authentication of people who'll you want to have access to the Partner CMS
  • List of addresses for pickup points - where do we pickup your order for delivery

You will get in return

  • OAUTH_CLIENT_ID - OAuth2 Client ID for authenticating with the Partner API. Keep it safe. Value may vary for each environment.
  • OAUTH_CLIENT_SECRET - OAuth2 Client Secret for authenticating with the Partner API. Keep it safe. Value may vary for each environment.
  • API_URL - Base URL for Partner API

Environments

Product offers multiple environments

  • Sandbox - For you to test the integration. Limited functionality.
  • Production - Connected to real end-users. Use with care.

Environment setting summary:

Value \ Env Sandbox Production
API_URL N/A N/A
OAUTH_CLIENT_SECRET Contact Support Contact Support
OAUTH_CLIENT_ID Contact Support Contact Support

API

Authentication

Authentication is based on OAuth2 standard, Client Credentials grant. Token endpoint /auth-sessions, see examples below.

Client ID and Secret MUST be passed to you from BoxNow support in advance.

In order to use the API, you MUST attach the access token to Authorization header as a Bearer token.

Custom JWT claims

You can find additional user information in custom claims under namespace key https://boxnow.gr. For example

{
  \"iat\": 1641980553,
  \"exp\": 1641984153,
  \"https://boxnow.gr\": {
    \"permission\": {
      \"warehouseAsOrigin\": true,
      \"anyApmAsOrigin\": true,
      \"anyApmToSameApmDelivery\": true,
      \"anyApmToSameApmDeliveryWithoutConfirmation\": true,
      \"depotAsOrigin\": true
    }
  }
}

Listing available destinations

You can skip this if you don't want to deliver your order to one of our APMs.

Use /destinations to list available APM locations we can deliver the goods to. You will refer to these records by id when requesting delivery later on.

Requesting a delivery

Create a delivery request to delivery your order to the client. Use /delivery-requests endpoint for this operation.

Once a successful request delivery is made

  • (optional) we send you an email notifying about successful delivery request creation, if you choose to receive this email
  • you should fetch the PDF label for each of the parcel from /parcels/{id}/label.pdf, print it and stick it to the parcel/s
  • we send a courier to pick up the labeled parcel/s
  • we notify the client via email that we have accepted the order from you and its being delivered by us

Modifying a delivery request

After a delivery request is successfully made, you can alter some parts of it later on. Use /delivery-requests/{id} endpoint for these modifications.

Checking on the deliveries

You can list parcel related to your delivery requests via /parcels endpoint.

Error codes

Description of codes for 400 Unprocessable entity responses

  • P400 - Invalid request data. Make sure are sending the request according to this documentation.
  • P401 - Invalid request origin location reference. Make sure you are referencing a valid location ID from Origins endpoint or valid address.
  • P402 - Invalid request destination location reference. Make sure you are referencing a valid location ID from Destinations endpoint or valid address.
  • P403 - You are not allowed to use AnyAPM-SameAPM delivery. Contact support if you believe this is a mistake.
  • P404 - Invalid import CSV. See error contents for additional info.
  • P405 - Invalid phone number. Make sure you are sending the phone number in full international format, e.g. +30 xx x xxx xxxx.
  • P406 - Invalid compartment/parcel size. Make sure you are sending one of required sizes 1, 2 or 3. Size is required when sending from AnyAPM directly.
  • P407 - Invalid country code. Make sure you are sending country code in ISO 3166-1 alpha-2 format, e.g. GR.
  • P408 - Invalid amountToBeCollected amount. Make sure you are sending amount in the valid range of (0, 5000>
  • P409 - Invalid delivery partner reference. Make sure you are referencing a valid delivery partner ID from Delivery partners endpoint.
  • P410 - Order number conflict. You are trying to create a delivery request for order ID that has already been created. Choose another order id.
  • P411 - You are not eligible to use Cash-on-delivery payment type. Use another payment type or contact our support.
  • P412 - You are not allowed to create customer returns deliveries. Contact support if you believe this is a mistake.
  • P413 - Invalid return location reference. Make sure you are referencing a valid location warehouse ID from Origins endpoint or valid address.
  • P420 - Parcel not ready for cancel. You can cancel only new, undelivered, or parcels that are not returned or lost. Make sure parcel is in transit and try again.
  • P430 - Parcel not ready for AnyAPM confirmation. Parcel is probably already confirmed or being delivered. Contact support if you believe this is a mistake.

Description of codes for 403 Forbidden responses

  • X403 - Account disabled. Your account had been disabled, contact support.
  • P414 - Unauthorized parcel access. You are trying to access information to parcel/s that don't belong to you. Make sure you are requesting information for parcels you have access to.

Description of codes for 503 Service Unavailable responses

Code Description
P600 Locker bridge communication failed. There has been some error when communicating with the locker bridge. Try again later or contact support.
P610 Geolocation API failed. There has been some error when translating address to gps coordinates. Try again later or contact support.

Installation & Usage

Requirements

PHP 7.4 and later. Should also work with PHP 8.0.

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/m-michalis/boxnow-api.git"
    }
  ],
  "require": {
    "m-michalis/boxnow-api": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');




$apiInstance = new Boxnow\Api\AuthenticationApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client()
);
$api_v1_auth_sessions_post_request = new \Boxnow\Model\ApiV1AuthSessionsPostRequest(); // \Boxnow\Model\ApiV1AuthSessionsPostRequest

try {
    $result = $apiInstance->apiV1AuthSessionsPost($api_v1_auth_sessions_post_request);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling AuthenticationApi->apiV1AuthSessionsPost: ', $e->getMessage(), PHP_EOL;
}

API Endpoints

All URIs are relative to https://boxnow.gr/media/yaml/TBA

Class Method HTTP request Description
AuthenticationApi apiV1AuthSessionsPost POST /api/v1/auth-sessions Obtain authentication tokens
DeliveryPartnersApi apiV1DeliveryPartnersGet GET /api/v1/delivery-partners List of available delivery partners
DeliveryRequestsApi apiV1DeliveryRequestsOrderNumberPut PUT /api/v1/delivery-requests/{orderNumber} Update a created delivery request
DeliveryRequestsApi apiV1DeliveryRequestsPost POST /api/v1/delivery-requests Create a delivery request for your order
DeliveryRequestsApi apiV1DeliveryRequestscheckAddressDeliveryPost POST /api/v1/delivery-requests:checkAddressDelivery Check delivery for address is available
DeliveryRequestsApi apiV1DeliveryRequestscustomerReturnsPost POST /api/v1/delivery-requests:customerReturns Create a request delivery of parcel that customer would like to return
DeliveryRequestsApi apiV1DeliveryRequestsfromCsvPost POST /api/v1/delivery-requests:fromCsv Create delivery requests
DeliveryRequestsApi apiV1SimpleDeliveryRequestsPost POST /api/v1/simple-delivery-requests Create delivery request for order with minimal data
LabelsApi apiV1DeliveryRequestsOrderNumberLabelGet GET /api/v1/delivery-requests/{orderNumber}/label Get shipping label data of parcels order
LabelsApi apiV1DeliveryRequestsOrderNumberLabelTypeGet GET /api/v1/delivery-requests/{orderNumber}/label.{type} Get printable labels for all parcels in a delivery request.
LabelsApi apiV1LabelssearchPost POST /api/v1/labels:search Find labels as PDF
LabelsApi apiV1ParcelsIdLabelGet GET /api/v1/parcels/{id}/label Get shipping label data of parcel
LabelsApi apiV1ParcelsIdLabelTypeGet GET /api/v1/parcels/{id}/label.{type} Get printable label for parcel.
LabelsApi uiV1DeliveryRequestsOrderImportsNumberLabelPdfGet GET /ui/v1/delivery-requests/{orderImportsNumber}/label.pdf Get printable labels for all parcels in a delivery request.
LocationsApi apiV1DestinationsGet GET /api/v1/destinations List available destinations to deliver the order to
LocationsApi apiV1OriginsGet GET /api/v1/origins List available origins to pickup the order from
ParcelsApi apiV1ParcelsGet GET /api/v1/parcels List parcel info related to your delivery requests
ParcelsApi apiV1ParcelsIdcancelPost POST /api/v1/parcels/{id}:cancel Cancel parcel delivery
ParcelsApi apiV1ParcelsIdconfirmAnyapmDeliveryPost POST /api/v1/parcels/{id}:confirm-anyapm-delivery Confirm parcel has been delivered to AnyAPM
ParcelsApi uiV1ParcelsCsvGet GET /ui/v1/parcels.csv List parcels to csv file

Models

Authorization

Authentication schemes defined for the API:

bearer

  • Type: Bearer authentication (JWT)

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

  • API version: 1.40
  • Build package: org.openapitools.codegen.languages.PhpClientCodegen