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| |-|-|-|-| |2024-09-26|Hoffmann, P.| Add P466 error code |1.65| |2024-09-25|Filatov, R.| Add P465 error for /api/{v1,v2}/delivery-requests:checkA

Maintainers

Details

github.com/m-michalis/boxnow-php

Homepage

Source

Issues

Installs: 611

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 1

Open Issues: 0

v0.0.8-alpha 2025-04-03 09:02 UTC

Requires

Requires (Dev)

unlicense 0db2ada53806594ffafc0e93f582adb8ee40e3c8

phprestapisdkopenapiopenapitoolsopenapi-generator

This package is not auto-updated.

Last update: 2025-05-15 09:28:17 UTC

README

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

Revision history

Date Author Description Version
2024-09-26 Hoffmann, P. Add P466 error code 1.65
2024-09-25 Filatov, R. Add P465 error for /api/{v1,v2}/delivery-requests:checkAddressDelivery 1.64
2024-08-13 Hoffmann, P. Update shippingRegions in /api/v1/entrusted-partners response. 1.63
2024-07-22 Hoffmann, P. Add shippingRegions and phoneNumber to /api/v1/entrusted-partners response. 1.62
2024-07-11 Filatov, R. Add P461, P462, P464 errors for ArcGIS validations to /api/v2/delivery-requests:checkAddressDelivery 1.61
2024-07-08 Hoffmann, P. Add email and phoneNumber to /api/v1/entrusted-partners response. Add originContactEmail and originContactNumber to /api/v1/delivery-requests:fromCsv request body 1.60
2024-05-23 Balagazova, K. Add lost parcel event 1.59
2024-04-08 Hoffmann, P. Add declareDeliveryPartnerReturn 1.58
2024-03-15 Šmolík, J. Add generate upload label link 1.57
2024-02-02 Šmolík, J. Add location id to /api/v1/parcels events 1.56
2023-11-15 Filatov, R. Add P422, P423, P424 error codes 1.55
2023-11-13 Filatov, R. Add new /api/v2/delivery-requests:checkAddressDelivery endpoint switched to ArcGIS 1.54
2023-11-08 Filatov, R. Add customerReturnsMaxAllowedSize for /api/v1/entrusted-partners 1.53
2023-06-10 Filatov, R. Add weight min/max validation (error cde P421) and always round it to 2 decimals on /api/v1/delivery-requests:customerReturns 1.52
2023-05-10 Balagazova, K. Forbid usage of q parameter of api/v1/parcels for partner server accounts 1.51
2023-04-28 Hoffmann, P. Remove X-Overwrite-Date request header from /api/v1/delivery-requests and /api/v1/entrusted-partners 1.50
2023-04-28 Azizov, J. Add P442 error code 1.49
2023-04-12 Balagazova, K. Add limit field and automatic ordering by distance to /api/v1/destinations 1.48
2023-04-04 Balagazova K. Add showRecipientInformation field to /api/v1/delivery-requests /api/v1/delivery-requests:fromCsv 1.47
2023-02-23 Balagazova K. Add customer information to the webhook message 1.46
2022-11-29 Azizov J. Add Webhook schema and an example endpoint 1.45
2022-11-28 Vala J. Add partner permission to /entrusted-partners response 1.44
2022-11-24 Vala J. Add partner permission addressAsDestination, codAddressAsDestination. Validate partner permission for delivery to address and cod payment use for delivery to address when creating delivery request 1.43
2022-11-14 Vala J. Add X-Overwrite-Date request header for delivery request to test Croatian currency conversion, only testeable on dev 1.42
2022-10-21 Vala J. Add validation error code to /api/v1/simple-delivery-requests /api/v1/delivery-requests /api/v1/delivery-requests:customerReturns 1.41
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.

What can influence /destinations endpoint response

  • Only APMs with Box Now Ready state are considered
  • APMs must be available for your required package size (see: '#/components/parameters/LocationRequiredSize')

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 Bad Request 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.
  • C404 - 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.
  • P415 - You are not allowed to create delivery to home address. Contact support if you believe this is a mistake.
  • P416 - You are not allowed to use COD payment for delivery to home address. Contact support if you believe this is a mistake.
  • P417 - You are not allowed to use q parameter. It is forbidden for server partner accounts.
  • 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.
  • P421 - Invalid parcel weight. Make sure you are sending value between 0 and 10^6.
  • P422 - Address not found. Try to call just with postal code and country.
  • P423 - Nearby locker not found.
  • P424 - Invalid region format. Please ensure the format includes a language code followed by a country code in ISO 3166-1 alpha-2 format, separated by a hyphen, e.g. el-GR, or region exists in context.
  • P425 - Parcel not ready to declare a delivery partner return. Make sure parcel is not in any of the following states in order to declare a delivery partner return: 'canceled-return', 'lost', 'canceled', 'returned', 'expired-return'.
  • P426 - Parcel not eligible to declare a delivery partner return. Parcel needs to use a delivery partner in order to declare a return.
  • P430 - Parcel not ready for AnyAPM confirmation. Parcel is probably already confirmed or being delivered. Contact support if you believe this is a mistake.
  • P440 - Ambiguous partner. Your account is linked to multiple partners and is unclear on whose behalf you want to perform this action. Send X-PartnerID header with ID of the partner you want to manage. You can get list of available Partner IDs from /entrusted-partners endpoint.
  • P441 - Invalid X-PartnerID header. Value you provided for X-PartnerID header is either invalid or references partner you don't have access to. Make sure you are sending ID from /entrusted-partners endpoint.
  • P442 - Invalid limit query parameter. The query limit for this API has been exceeded. Please reduce the size of your query (max allowed is 100).
  • P460 - Parcel not eligible for external destination delivery. Delivery request destination.deliveryPartnerId is not set.
  • P461 - Invalid street. Make sure the length is not more than 100 characters.
  • P462 - Invalid city. Make sure the length is not more than 50 characters.
  • P464 - Invalid postal code. Make sure the length is not more than 20 characters.

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.
  • P465 - Partner doesn't have access for checking delivery addresses.
  • P466 - You are not allowed to create a delivery request because your account has an overdue flag and you are not a vip partner.

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 8.1 and later.

Composer

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

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git"
    }
  ],
  "require": {
    "GIT_USER_ID/GIT_REPO_ID": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/MMMIKE/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 http://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 apiV1DeliveryRequestsCheckAddressDeliveryPost POST /api/v1/delivery-requests:checkAddressDelivery Check delivery for address is available using Google Maps Geocoding API
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 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 apiV1SimpleDeliveryRequestsPost POST /api/v1/simple-delivery-requests Create delivery request for order with minimal data
DeliveryRequestsApi apiV2DeliveryRequestsCheckAddressDeliveryPost POST /api/v2/delivery-requests:checkAddressDelivery Check delivery for address is available using ArcGIS Geocoding API
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 apiV1ParcelsIdDestinationlabelGenerateUploadUrlPost POST /api/v1/parcels/{id}/destinationlabel:generateUploadUrl Get upload url for a custom label
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 apiV1ParcelsIdDeclareDeliveryPartnerReturnPost POST /api/v1/parcels/{id}:declareDeliveryPartnerReturn Initiate a parcel return from a delivery partner
ParcelsApi uiV1ParcelsCsvGet GET /ui/v1/parcels.csv List parcels to csv file
PartnersApi apiV1EntrustedPartnersGet GET /api/v1/entrusted-partners Get list of partner you can manage
WebhooksApi yourWebhookEndpointPost POST /{your-webhook-endpoint} Your webhook endpoint. Used to send You parcel events messages. You should set this endpoint in your BoxNow account.

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.65
    • Generator version: 7.13.0-SNAPSHOT
  • Build package: org.openapitools.codegen.languages.PhpClientCodegen