Entrego API

Entrego LMS API GUIDE

Basics

Communication with Entrego’s API is web based (https only). The payload is JSON encoded, which allows flexibility with client software implementation. There are 3 different environments: live, staging and sandbox with the following endpoints:

Endpoints per Environment

Environment	URL
Live	https://api.entrego.org
Staging	https://api-staging.entrego.org
Sandbox	https://api-sandbox.entrego.org

All following URLs will be relative to these endpoints

HTTP Methods

RESTful notes adheres as closely as possible to standard HTTP and REST conventions in its use of HTTP methods.

HTTP Method	Description
GET	Used to retrieve a resource
POST	Used to create a new resource
PATCH	Used to update an existing resource, including partial updates

HTTP Status Codes

LMS adheres as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes:

HTTP Status Code	Description
200 OK	The request was successfully completed
201 Created	A new resource has successfully been created. The resource’s URI is available from the response’s Location header
202 Accepted	An update to an existing resource: partially accepted. This will give a JSON response body for the fields that are not updated
204 No Content	An update to an existing resource has been applied successfully
400 Bad Request	The request was malformed. The response body will include an error providing further information
403 Forbidden	Access to the resource was denied
404 Not Found	The requested resource does not exist
500 Internal Server Error	The server encountered an internal server error

Resources

Authentication

To maintain backwards compatibility, there are currently two endpoints for JWT token retrieval. Endpoints differ in the naming convention for the parameters and return keys.

Method 1

URL: /v1/authenticate

Method: POST

Entrego utilizes JWT Token based authentification with a validity of 24h. To retrieve a token, send the following payload to authenticate:

                                            
                                            
                                        POST /v1/authenticate HTTP/1.1
                                        Content-Type: application/json;charset=UTF-8
                                        Host: api.entrego.com
                                        Content-Length: 55

                                        {
                                        "secretKey" : "admin",
                                        "accessKey" : "admin"
                                        }

The following response will display after successful authentication:

                                            
                                            
                                            HTTP/1.1200OK
                                            Authorization:Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJqdGkiOiIxOGVhZTAyMi1jMTVhLTQ4MWYtYjQ3YS1jODBmMTg5Njc4YmUiLCJzdWIiOiJhZG1pbiIsImlzcyI6IkVudHJlZ28gTG9naXN0aWNzIFBIIiwiaWF0IjoxNTQ1MzgyNDExLCJleHAiOjE1NDU0Njg4MTEsInJvbGVzIjpbIlJPTEVfQURNSU4iXX0.v2Jh1USeQ3gCLqyKlx0064uW_yxFevPISlwb9-zQl83Z3fRoTSsswZv-8d_lB6p3FNqflFYrn8lN-XHx1co70Q
                                            Content-Type:application/json;charset=UTF-8
                                            X-Content-Type-Options: nosniff
                                            X-XSS-Protection: 1; mode=block
                                            Cache-Control:no-cache, no-store, max-age=0, must-revalidate
                                            Pragma:no-cache
                                            Expires:0
                                            Strict-Transport-Security:max-age=31536000 ; includeSubDomains
                                            Content-Length:337
                                            {
                                            "jwt" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJqdGkiOiIxOGVhZTAyMi1jMTVhLTQ4MWYtYjQ3YS1jODBmMTg5Njc4YmUiLCJzdWIiOiJhZG1pbiIsImlzcyI6IkVudHJlZ28gTG9naXN0aWNzIFBIIiwiaWF0IjoxNTQ1MzgyNDExLCJleHAiOjE1NDU0Njg4MTEsInJvbGVzIjpbIlJPTEVfQURNSU4iXX0.v2Jh1USeQ3gCLqyKlx0064uW_yxFevPISlwb9-zQl83Z3fRoTSsswZv-8d_lB6p3FNqflFYrn8lN-XHx1co70Q"
                                            }

Sensitive parts of the API are only accessible if the obtained token is sent along with every request as an Authorization header, as demonstrated by the successful response above.

Method 2 (Deprecated)

URL: /api/authenticate

Method: POST

Request:

                                        
                                        
                                        POST /v1/authenticate HTTP/1.1
                                        Content-Type: application/json;charset=UTF-8
                                        Host: api.entrego.com
                                        Content-Length: 55

                                        {
                                        "password" : "admin",
                                        "username" : "admin"
                                        }

Response:

                                        
                                        
                                        HTTP/1.1 200 OK
                                        Authorization:Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJqdGkiOiIxOGVhZTAyMi1jMTVhLTQ4MWYtYjQ3YS1jODBmMTg5Njc4YmUiLCJzdWIiOiJhZG1pbiIsImlzcyI6IkVudHJlZ28gTG9naXN0aWNzIFBIIiwiaWF0IjoxNTQ1MzgyNDExLCJleHAiOjE1NDU0Njg4MTEsInJvbGVzIjpbIlJPTEVfQURNSU4iXX0.v2Jh1USeQ3gCLqyKlx0064uW_yxFevPISlwb9-zQl83Z3fRoTSsswZv-8d_lB6p3FNqflFYrn8lN-XHx1co70Q
                                        Content-Type:application/json;charset=UTF-8
                                        X-Content-Type-Options: nosniff
                                        X-XSS-Protection: 1; mode=block
                                        Cache-Control:no-cache, no-store, max-age=0, must-revalidate
                                        Pragma:no-cache
                                        Expires:0
                                        Strict-Transport-Security:max-age=31536000 ; includeSubDomains
                                        Content-Length:337
                                        {
                                        "id_token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJqdGkiOiIxOGVhZTAyMi1jMTVhLTQ4MWYtYjQ3YS1jODBmMTg5Njc4YmUiLCJzdWIiOiJhZG1pbiIsImlzcyI6IkVudHJlZ28gTG9naXN0aWNzIFBIIiwiaWF0IjoxNTQ1MzgyNDExLCJleHAiOjE1NDU0Njg4MTEsInJvbGVzIjpbIlJPTEVfQURNSU4iXX0.v2Jh1USeQ3gCLqyKlx0064uW_yxFevPISlwb9-zQl83Z3fRoTSsswZv-8d_lB6p3FNqflFYrn8lN-XHx1co70Q"
                                        }

Order Creation

Request

URL: /v1/sales-order

Method: POST

An order document consists of the order-related details, along with the nested recipient and pickup document fields:

Note: If an optional parameter is omitted or left empty, default values will apply.

Parameter	Data Type	Constraint	Description
shipperReference	String	Required	A unique identifier provided by the client
trackingNumber	String	Optional	Can be generated by the client or left empty. In the latter case it will be generated by the system
paymentMethod	String	Optional	The default value is NO_PAYMENT, other possible value is: * CASH_ON_DELIVERY
collectAmount	Number	Optional	The total amount collected. Should be 0 (zero) if paymentMethod is NO_PAYMENT * Required if paymentMethod is CASH_ON_DELIVERY
deliveryType	String	Optional	The default value is STANDARD, other possible value is: *EXPRESS
portCode	String	Optional	Port code. Refer to Location API on how to generate.
pickupPortCode	String	Optional	Pickup port code * Required if serviceType is RTM
productName	String	Optional	A short description of the content of the package
packageType	String	Required	Possible values are: * Entrego Pouch (POUCH) * Entrego Eco Pouch (ECOPOUCH) * Entrego Box (BOX) * Own Packaging (OWN_PACKAGING)
packageSize	String	Required	Possible values per packageType: * Entrego Pouch (POUCH) - SMALL, MEDIUM, LARGE, EXTRA_LARGE * Entrego Eco Pouch (ECOPOUCH) - SMALL, MEDIUM, LARGE * Entrego Box (BOX) - SMALL, MEDIUM, LARGE * Own Packaging (OWN_PACKAGING) - Send as null. Note: All orders under OWN_PACKAGING should provide dim weights etc.
packageValue	Number	Optional	The value of package in PHP
weightActual	Number	Optional	Actual weight of the package
weightVolumetric	Number	Optional	Volumetric weight of the package
width	Number	Optional	Width of the package in centimeter
height	Number	Optional	Height of the package in centimeter
length	Number	Optional	Length of the package in centimeter
scheduledDeliveryDate	String	Optional	Earliest possible delivery date of the package
expectedDeliveryDate	String	Optional	Expected delivery date of the package by the client
deliveryInstructions	String	Optional	Additional instruction for the delivery personnel
recipient	Object	Required	The recipient details of the package
pickup	Object	Required	The pickup details of the package
pickupType	String	Optional	The default value is DROP, other possible value is: * PICKUP
serviceType	String	Required	Possible values are: * FDY * RTN * RTM
businessUnitCode	String	Optional	A sub code that can be used as an identifier.
additionalInfo	Object	Optional	A field to store various customer-specific data

Below are the details of the recipient and pickup objects:

Recipient Object

Parameter	Data Type	Constraint	Description
fullname	String	Required	Salutation, first name and last name
address	String	Required	Delivery address
city	String	Required	Delivery city
barangay	String	Required	Name of the barangay
zipcode	String	Required	Delivery zip code
email	String	Optional	Recipient’s email address
phone	String	Optional	Recipient’s phone number
province	String	Required	Name of the province. See Appendix for the list of supported province names
isBranchDelivery	Boolean	Optional	Denotes if a package is to be delivered to a branch for consignee to pickup. Possible values are 1 and 0
deliveryBranchId	Number	Optional	Branch ID where a package will be delivered to. This is the branch is where the consignee is picking up his/her package.

Pickup Object

Parameter	Data Type	Constraint	Description
fullname	String	Required	Salutation, first name and last name
address	String	Required	Customer's pickup address
city	String	Required	Customer's pickup city
barangay	String	Required	Name of the barangay
zipcode	String	Required	Customer's zip code
email	String	Optional	Customer's email address
phone	String	Optional	Customer's phone number
province	String	Required	Name of the province. See Appendix for the list of supported province names
isBranchDropOff	Boolean	Optional	Denotes if a package is to be dropped off by the sender in a branch. Possible values are 1 and 0

This list above includes all possible fields required for creating a sales order. Though only a small subset is mandatory, clients are encouraged to provide as much data as possible to ensure efficient and frictionless delivery.

Below is an example of how to create a request using curl:


                                        
                                        
                                            $ curl 'https://api.entrego.com/v1/sales-order' -i -X POST \
                                             -H 'Content-Type: application/json;charset=UTF-8' \
                                             -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJqdGkiOiJhMDMwODMxZC02ZGM0LTRmMzQtYTVhNS05Yzg0N2NhNzc0ZTUiLCJzdWIiOiJhZG1pbiIsImlzcyI6IkVudHJlZ28gTG9naXN0aWNzIFBIIiwiaWF0IjoxNTQ1MzgyNDI3LCJleHAiOjE1NDU0Njg4MjcsInJvbGVzIjpbIlJPTEVfQURNSU4iXX0.HkheMEmJ1l62gcEWe6zQ00CGIwiZr7sFbj-dspb9OQpFWQOen1nb-M20QphLk6WH6ODksOoRALuB3FvNNvrKMw' \
                                             -d '{
                                            "shipperReference" : "fc75d430-a6b4-40b8-ab60-dbf17b21ec0a",
                                            "trackingNumber" : "0031-123456789010",
                                             "paymentMethod" : "CASH_ON_DELIVERY",
                                            "collectAmount" : 900,
                                            "deliveryType" : "STANDARD",
                                            "portCode" : "BTN",
                                            "pickupPortCode" : "ZMB",
                                            "productName" : "SanDisk OTG USB 64GB",
                                            "packageType" : "POUCH",
                                            "packageSize" : "LARGE",
                                            "packageValue" : 900,
                                            "weightActual" : 1.5,
                                            "weightVolumetric" : 2.3,
                                            "width" : 1.5,
                                            "height" : 4.5,
                                            "length" : 2.5,
                                            "scheduledDeliveryDate" : "2018-09-15",
                                            "expectedDeliveryDate" : "2018-09-16",
                                            "deliveryInstructions" : "Please beware of the dogs",
                                            "recipient" : {
                                            "fullname" : "Recipient Name",
                                            "address" : "Recipient Address",
                                            "city" : "Recipient City",
                                            "barangay" : "Test Barangay",
                                            "zipcode" : "123456",
                                            "phone" : "09123456789",
                                            "email" : "recipient.name@example.com",
                                            "province" : "Metro Manila"
                                            },
                                            "pickup" : {
                                                "fullname" : "Pickup Name",
                                                "address" : "Pickup Address",
                                                "city" : "Pickup City",
                                                "barangay" : "Test Barangay",
                                                "zipcode" : "123456",
                                                "phone" : "09987654321",
                                                "email" : "pickup.name@example.com",
                                                "province" : "Metro Manila"
                                            },
                                            "serviceType" : "FDY"
                                            }'

Response

Below is the example response with a success creation of order:


                                            
                                            
                                                HTTP/1.1 201 Created 
                                                Location: /v1/sales-order/21c123fb-472a-4602-adef-f37104ae8bb2
                                                X-LMS-alert: A new SalesOrder was created with identifier 0031-123456789010
                                                X-LMS-params: 0031-123456789010                                                
                                                Content-Type:application/json;charset=UTF-8
                                                X-Content-Type-Options: nosniff
                                                X-XSS-Protection: 1; mode=block
                                                Cache-Control:no-cache, no-store, max-age=0, must-revalidate
                                                Pragma:no-cache
                                                Expires:0
                                                Strict-Transport-Security:max-age=31536000 ; includeSubDomains
                                                Content-Length:1482
                                                {
                                              
                                                "shipperReference" : "fc75d430-a6b4-40b8-ab60-dbf17b21ec0a",
                                                "trackingNumber" : "0031-123456789010",
                                                "paymentMethod" : "CASH_ON_DELIVERY",
                                                "collectAmount" : 900,
                                                "collectCurrency" : "PHP",
                                                "deliveryType" : "STANDARD",
                                                "portCode" : "BTN",
                                                "pickupPortCode" : "ZMB",
                                                "productName" : "SanDisk OTG USB 64GB",
                                                "packageType" : "POUCH",
                                                "packageSize" : "LARGE",
                                                "packageValue" : 0,
                                                "packageValueCurrency" : "PHP",
                                                "weightActual" : 1.5,
                                                "weightVolumetric" : 2.3,
                                                "width" : 1.5,
                                                "height" : 4.5,
                                                "length" : 2.5,
                                                "scheduledDeliveryDate" : "2018-09-15",
                                                "expectedDeliveryDate" : "2018-09-16",                                                
                                                "orderNumber" : "21c123fb-472a-4602-adef-f37104ae8bb2",
                                                "deliveryInstructions" : "Please beware of the dogs",
                                                "customerData" : null,
                                                "fsmState" : "NEW",
                                                "recipient" : {
                                                    "fullname" : "Recipient Name",
                                                    "address" : "Recipient Address",
                                                    "city" : "Recipient City",
                                                    "barangay" : "Test Barangay",
                                                    "zipcode" : "123456",
                                                    "phone" : "+639123456789",
                                                    "email" : "recipient.name@example.com",
                                                    "province" : "Metro Manila"
                                                    },
                                                    "pickup" : {
                                                        "fullname" : "Pickup Name",
                                                        "address" : "Pickup Address",
                                                        "city" : "Pickup City",
                                                        "barangay" : "Test Barangay",
                                                        "zipcode" : "123456",
                                                        "phone" : "+639987654321",
                                                        "email" : "pickup.name@example.com",
                                                        "province" : "Metro Manila",
                                                    },
                                                    "serviceType" : "FDY",
                                                    "pickupType" : "DROP",
                                                    "sellerReference" : null,
                                                    "additionalInfo" : null,
                                                    }

Order Creation (Marketplace)

Prerequisites

Before using this endpoint, all clients must provide the following information for all sellers. For any new seller, this information must be provided at least five (5) working days before launch. Please see the required information below:

Parameter	Constraint	Description
Seller Reference	Required	Unique seller ID as stored in the client’s system. This is the same sellerReference the client will be sending as seen in the request. (Please see Request section below.)
Name	Required	Name of the seller
Address	Required	Seller's pickup address
City	Required	Seller's pickup city
Barangay	Required	Name of the barangay
Province	Required	Name of the province. See Appendix for the list of supported province names
Zipcode	Required	Seller's pickup zip code
Email	Optional	Seller's email address
Phone	Optional	Seller's phone number

Request

URL: /v1/sales-order/marketplace

Method: POST

An order document consists of the order-related details, along with the nested recipient document fields:

Note: If an optional parameter is omitted or left empty, default values will apply.

Parameter	Data Type	Constraint	Description
shipperReference	String	Required	A unique identifier provided by the client
trackingNumber	String	Optional	Can be generated by the client or left empty. In the latter case it will be generated by the system
paymentMethod	String	Optional	The default value is NO_PAYMENT, other possible value is: * CASH_ON_DELIVERY
collectAmount	Number	Optional	The total amount collected. Should be 0 (zero) if paymentMethod is NO_PAYMENT * Required if paymentMethod is CASH_ON_DELIVERY
deliveryType	String	Optional	The default value is STANDARD, other possible value is: *EXPRESS
portCode	String	Optional	Port code. Refer to Location API on how to generate.
pickupPortCode	String	Optional	Pickup port code * Required if serviceType is RTM * Required if client cannot provide SellerID in API
productName	String	Optional	A short description of the content of the package
packageType	String	Required	Possible values are: * Entrego Pouch (POUCH) * Entrego Eco Pouch (ECOPOUCH) * Entrego Box (BOX) * Own Packaging (OWN_PACKAGING)
packageSize	String	Required	Possible values per packageType: * Entrego Pouch (POUCH) - SMALL, MEDIUM, LARGE, EXTRA_LARGE * Entrego Eco Pouch (ECOPOUCH) - SMALL, MEDIUM, LARGE * Entrego Box (BOX) - SMALL, MEDIUM, LARGE * Own Packaging (OWN_PACKAGING) - Send as null. Note: All orders under OWN_PACKAGING should provide dim weights etc.
packageValue	Number	Optional	The value of package in PHP
weightActual	Number	Optional	Actual weight of the package
weightVolumetric	Number	Optional	Volumetric weight of the package
width	Number	Optional	Width of the package in centimeter
height	Number	Optional	Height of the package in centimeter
length	Number	Optional	Length of the package in centimeter
scheduledDeliveryDate	String	Optional	Earliest possible delivery date of the package
expectedDeliveryDate	String	Optional	Expected delivery date of the package by the client
scheduledPickupDate	String	Optional	Scheduled Pick Up Date of Package from Seller
deliveryInstructions	String	Optional	Additional instruction for the delivery personnel
recipient	Object	Required	The recipient details of the package
pickupType	String	Optional	The default value is DROP, other possible value is: * PICKUP
sellerReference	String	Optional	Seller ID or supplier ID that is defined in the client’s system that will determine the pickup information
businessUnitCode	String	Optional	A sub code that can be used as an identifier.
additionalInfo	Object	Optional	A field to store various customer-specific data

Below are the details of the Recipient Object

Recipient Object

Parameter	Data Type	Constraint	Description
fullname	String	Required	Salutation, first name and last name
address	String	Required	Delivery address
city	String	Required	Delivery city
barangay	String	Required	Name of the barangay
zipcode	String	Required	Delivery zip code
email	String	Optional	Recipient's email address
phone	String	Optional	Recipient's phone number
province	String	Required	Name of the province. See Appendix for the list of supported province names

Below are the details of the Pickup Object

Pickup Object

Parameter	Data Type	Constraint	Description
fullname	String	Required	Name of the seller
address	String	Required	Seller's pickup address
city	String	Required	Seller's pickup city
barangay	String	Required	Name of the barangay
zipcode	String	Required	Seller's pickup zip code
email	String	Optional	Seller's email address
phone	String	Optional	Seller's phone number
province	String	Required	Name of the province. See Appendix for the list of supported province names

Below is an example of how to create a request using curl:


                                            
                                            
                                            $ curl 'https://api.entrego.com/v1/sales-order/marketplace' -i -X POST \
                                             -H 'Content-Type: application/json;charset=UTF-8' \
                                             -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJqdGkiOiJhMDMwODMxZC02ZGM0LTRmMzQtYTVhNS05Yzg0N2NhNzc0ZTUiLCJzdWIiOiJhZG1pbiIsImlzcyI6IkVudHJlZ28gTG9naXN0aWNzIFBIIiwiaWF0IjoxNTQ1MzgyNDI3LCJleHAiOjE1NDU0Njg4MjcsInJvbGVzIjpbIlJPTEVfQURNSU4iXX0.HkheMEmJ1l62gcEWe6zQ00CGIwiZr7sFbj-dspb9OQpFWQOen1nb-M20QphLk6WH6ODksOoRALuB3FvNNvrKMw' \
                                             -d '{
                                            "shipperReference" : "fc75d430-a6b4-40b8-ab60-dbf17b21ec0a",
                                            "trackingNumber" : "0031-123456789010",
                                             "paymentMethod" : "NO_PAYMENT",
                                            "collectAmount" : 0,
                                            "deliveryType" : "STANDARD",
                                            "portCode" : "BTN",
                                            "pickupPortCode" : "ZMB",
                                            "productName" : "SanDisk OTG USB 64GB",
                                            "packageType" : "POUCH",
                                            "packageSize" : "LARGE",
                                            "packageValue" : 0,
                                            "weightActual" : 1.5,
                                            "weightVolumetric" : 2.3,
                                            "width" : 1.5,
                                            "height" : 4.5,
                                            "length" : 2.5,
                                            "deliveryInstructions" : "Please beware of the dogs",
                                            "scheduledPickupDate" : "2018-06-14",
                                            "recipient" : {
                                            "fullname" : "Recipient Name",
                                            "address" : "Recipient Address",
                                            "city" : "Recipient City",
                                            "barangay" : "Test Barangay",
                                            "zipcode" : "123456",
                                            "phone" : "09123456789",
                                            "email" : "recipient.name@example.com",
                                            "province" : "Metro Manila"
                                            },
                                            "pickup" : {
                                                "fullname" : "Pickup Name",
                                                "address" : "Pickup Address",
                                                "city" : "Pickup City",
                                                "barangay" : "Test Barangay",
                                                "zipcode" : "123456",
                                                "phone" : "09123456789",
                                                "email" : "pickup.name@example.com",
                                                "province" : "Metro Manila"
                                                },
                                            "serviceType" : "MP"
                                            "sellerReference" : "ABC123"
                                            }'

Response

Below is the example response with a success creation of order:


                                            
                                            
                                                HTTP/1.1 201 Created
                                                Location: /v1/sales-order/de180dd7-5d1c-42c2-9e01-5c2534cad2b2
                                                X-LMS-alert: A new SalesOrder was created with identifier 0031-123456789010
                                                X-LMS-params: 0031-123456789010                                                
                                                Content-Type:application/json;charset=UTF-8
                                                X-Content-Type-Options: nosniff
                                                X-XSS-Protection: 1; mode=block
                                                Cache-Control:no-cache, no-store, max-age=0, must-revalidate
                                                Pragma:no-cache
                                                Expires:0
                                                Strict-Transport-Security:max-age=31536000 ; includeSubDomains
                                                Content-Length:1405
                                                {
                                              
                                                "shipperReference" : "fc75d430-a6b4-40b8-ab60-dbf17b21ec0a",
                                                "trackingNumber" : "0031-123456789010",
                                                "paymentMethod" : "NO_PAYMENT",
                                                "collectAmount" : 0,
                                                "collectCurrency" : "PHP",
                                                "deliveryType" : "STANDARD",
                                                "portCode" : "BTN",
                                                "pickupPortCode" : "SOU",
                                                "productName" : "SanDisk OTG USB 64GB",
                                                "packageType" : "POUCH",
                                                "packageSize" : "LARGE",
                                                "packageValue" : 0,
                                                "packageValueCurrency" : "PHP",
                                                "weightActual" : 1.5,
                                                "weightVolumetric" : 2.3,
                                                "width" : 1.5,
                                                "height" : 4.5,
                                                "length" : 2.5,
                                                "scheduledDeliveryDate" : null,
                                                "expectedDeliveryDate" : null,
                                                "scheduledPickupDate" : "2018-06-14",
                                                "orderNumber" : "de180dd7-5d1c-42c2-9e01-5c2534cad2b2",                                                
                                                "deliveryInstructions" : "Please beware of the dogs",
                                                "customerData" : null,
                                                "fsmState" : "NEW",
                                                "recipient" : {
                                                    "fullname" : "Recipient Name",
                                                    "address" : "Recipient Address",
                                                    "city" : "Recipient City",
                                                    "barangay" : "Test Barangay",
                                                    "zipcode" : "123456",
                                                    "phone" : "+639123456789",
                                                    "email" : "recipient.name@example.com",
                                                    "province" : "Metro Manila",
                                                    },
                                                    "pickup" : {
                                                        "fullname" : "Seller Name",
                                                        "address" : "4 Test Lane Address",
                                                        "city" : "Test City",
                                                        "barangay" : null,
                                                        "zipcode" : "123456",
                                                        "phone" : null,
                                                        "email" : null,
                                                        "province" : "Bataan"
                                                    },
                                                    "serviceType" : "MP",
                                                    "pickupType" : "PICKUP",
                                                    "sellerReference" : "ABC123",
                                                    "additionalInfo" : null
                                                    }

Order Update

Request

URL: /v1/sales-order

Method: PATCH

Entrego supports two types of partial updates via PATCH : with and without condition.

Below is an example of how to update the value without factoring in the current value. Take note however, that this is not considered as a real PATCH request, because as with patching code, a patch will not be applied if the conditions are not met, to prevent data corruption.

                                            
                                            
                                            {                                           
                                            
                                            "trackingNumber" : "0031-0987654321",
                                            "patchPayload" : {
                                                "weightVolumetric" : {
                                                "oldValue" : null,
                                                "newValue" : 0.2,
                                                "realPatch" : false,
                                                },
                                                "weightActual" : {
                                                    "oldValue" : null,
                                                    "newValue" : 0.5,
                                                    "realPatch" : false,
                                                    }
                                                
                                                }
                                                }

Below is an example of how the client can update two values in one go, with the last containing a condition:

                                                
                                                
                                                {                                           
                                                
                                                "trackingNumber" : "0031-0987654321",
                                                "patchPayload" : {
                                                    "width" : {
                                                    "oldValue" : null,
                                                    "newValue" : 3.5,
                                                    "realPatch" : false
                                                    },
                                                    "height" : {
                                                        "oldValue" : 6.5,
                                                        "newValue" : 4.5,
                                                        "realPatch" : true
                                                        }
                                                    
                                                    }
                                                    }

Here is the detailed description of the parameters:

Parameter	Data Type	Constraint	Description
trackingNumber	String	Required	The tracking number of the package the client wish to update
patchPayload	Object	Required	A map of objects
patchPayload.*	Object	Required	The parameter the client wish to update. See Appendix for valid updatable parameters
patchPayload.*.oldValue	Varies	Optional	The old value in the database - This will be translated as the WHERE condition * Required if the realPatch is equals to TRUE
patchPayload.*.newValue	Varies	Required	The value to be set
patchPayload.*.realPatch	Boolean	Optional	TRUE means the oldValue parameter is taken into account as the where condition

Below is an example of how to make a request using curl:

                                                
                                            
                                                $ curl 'https://api.entrego.com/v1/sales-order' -i -X PATCH \
                                                 -H 'Content-Type: application/json;charset=UTF-8' \
                                                 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJqdGkiOiJhMDMwODMxZC02ZGM0LTRmMzQtYTVhNS05Yzg0N2NhNzc0ZTUiLCJzdWIiOiJhZG1pbiIsImlzcyI6IkVudHJlZ28gTG9naXN0aWNzIFBIIiwiaWF0IjoxNTQ1MzgyNDI3LCJleHAiOjE1NDU0Njg4MjcsInJvbGVzIjpbIlJPTEVfQURNSU4iXX0.HkheMEmJ1l62gcEWe6zQ00CGIwiZr7sFbj-dspb9OQpFWQOen1nb-M20QphLk6WH6ODksOoRALuB3FvNNvrKMw' \
                                                 -d '{
                                                "trackingNumber" : "0031-123456789010",
                                                "patchPayload" : {
                                                "weightVolumetric" : {
                                                "oldValue" : null,
                                                "newValue" : 0.2,
                                                "realPatch" : false,
                                                },
                                                "weightActual" : {
                                                    "oldValue" : null,
                                                    "newValue" : 0.5,
                                                    "realPatch" : false
                                                    }
                                                
                                                }
                                                }'

Response

Below is the example response with a successful update of order:

                                            
                                            
                                        HTTP/1.1 204 No Content 
                                        X-LMS-alert: A new SalesOrder was updated with identifier 0031-123456789010
                                        X-LMS-params: 0031-123456789010
                                        X-Content-Type-Options: nosniff
                                        X-XSS-Protection: 1; mode=block
                                        Cache-Control:no-cache, no-store, max-age=0, must-revalidate
                                        Pragma:no-cache
                                        Expires:0
                                        Strict-Transport-Security:max-age=31536000 ; includeSubDomains

Order Cancellation

Request

URL: /v1/sales-order/marketplace/cancel

Method: POST

Entrego supports Cancellation API before package is picked up.

Parameter	Data Type	Constraint
trackingNumber	String	Required
cancellationReason	String	Optional

Below is an example of the cancellation request payload

                                                
                                                
                                                {
                                                "trackingNumber" : "0031-LOC201905232",
                                                "cancellationReason":  "user cancelled",
                                                }

Below is an example of how to make a request using curl:

                                                
                                            
                                                $ curl 'https://api.entrego.com/v1/sales-order/marketplace/cancel' -i -X POST \
                                                 -H 'Content-Type: application/json;charset=UTF-8' \
                                                 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJqdGkiOiJhMDMwODMxZC02ZGM0LTRmMzQtYTVhNS05Yzg0N2NhNzc0ZTUiLCJzdWIiOiJhZG1pbiIsImlzcyI6IkVudHJlZ28gTG9naXN0aWNzIFBIIiwiaWF0IjoxNTQ1MzgyNDI3LCJleHAiOjE1NDU0Njg4MjcsInJvbGVzIjpbIlJPTEVfQURNSU4iXX0.HkheMEmJ1l62gcEWe6zQ00CGIwiZr7sFbj-dspb9OQpFWQOen1nb-M20QphLk6WH6ODksOoRALuB3FvNNvrKMw' \
                                                 -d '{
                                                "trackingNumber" : "0031-123456789010",
                                                "cancellationReason" : user cancelled
                                                }'

Response

Below is the example response with a successful cancellation of order:

                                            
                                            
                                        HTTP/1.1 200 OK 
                                        Content-Type application/json;charset=UTF-8
                                        Transfer-Encoding chunked
                                        Connection keep-alive
                                        X-Content-Type-Options: nosniff
                                        X-XSS-Protection: 1; mode=block
                                        Cache-Control:no-cache, no-store, max-age=0, must-revalidate
                                        Pragma:no-cache
                                        Expires:0
                                        {                                              
                                            "state" : "CANCELLED",
                                            "stateMetaData" : {
                                                "recipientName" : "Mr. Roger Wilco",
                                                "currentCity" : "Kerona",
                                                "city" : "Recipient City",
                                                },
                                        "trackingNumber" : "0031-LOC201905233",
                                        }

Below is the example response with a failed cancellation of order:

                                            
                                            
                                        HTTP/1.1 500 Internal Server Error 
                                        Content-Type application/json;charset=UTF-8
                                        Transfer-Encoding chunked
                                        Connection keep-alive
                                        X-Content-Type-Options: nosniff
                                        X-XSS-Protection: 1; mode=block
                                        Cache-Control:no-cache, no-store, max-age=0, must-revalidate
                                        Pragma:no-cache
                                        Expires:0
                                        {                                              
                                        "link" : "https://www.entrego.org/api-error/problem-with-message",
                                        "status" : "INTERNAL_SERVER_ERROR",
                                        "message" : "An error occurred",
                                        "details" : "Transition from PICKED_UP to CANCEL failed",
                                        }

Webhooks

Entrego implements webhooks to notify the client of order status updates. At present, onboarding for client webhook configuration is done manually. The following are necessary for onboarding:

Production and Staging environment URLs.

URL to staging takes priority

If available, authentication credentials or token

Prerequisites

The client must provide the endpoint where updates are to be sent. Please include all authentication methods necessary to access it.

Payload

Below are the details for the webhook payload structure:

Parameter	Data Type	Description
status	String	The current status of the package
tracking_number	String	The tracking number of the package
timestamp	String	The timestamp of which the package was moved to new status Has a format of yyyy-MM-dd’T’HH:mm:ss.SSS’Z’
comments	Object	Contains the additional metadata for the webhook.

Comments Object

Parameter	Data Type	Description
receiveCounter	Number	The number of times the package has been received from the client/customer
transitCounter	Number	The number of times the package was transferred to an Entrego warehouse/hub
deliveryAttemptCounter	Number	TThe number of times package delivery was attempted
deliveryFailedCounter	Number	The number of times a failed delivery was reattempted
deliveryFailedReasonCode	String	The failed reason code for the failed delivery See Appendix for a list of failed reasons recognized by Entrego
pickupAttemptCounter	Number	The number of times package pick-up was attempted
pickupFailedCounter	Number	The number of times a failed pick-up was reattempted
pickupFailedReasonCode	String	The failed reason code for the failed delivery See Appendix for the failed reasons recognized by Entrego

Below is an HTTP request example of how the payload is sent to the client:

POST /entrego-webhook HTTP/1.1

Content-Type: application/json;charset=UTF-8

Host: client-endpoint.example.com

Content-Length: 281

{

"status" : "RECEIVED_AT_HUB",

"tracking_number" : "0031-0987654321",

"timestamp" : 2018-09-21T01:05:10.000Z",

"comments" : {

"receiveCounter" : 1

}

Location API

Endpoints

Staging URL	https://api-core-staging.entrego.org
Production URL	https://api-core.entrego.org

Core APIs

HTTP Method	URL Path	Description	Sample
GET	/v1/locations/provinces	Retrieve All Provinces	https://api-core-staging.entrego.org/v1/locations/provinces
GET	/v1/locations/provinces/{province - id}/municipalities	Retrieve All Municipalities by Province ID	https://api-core-staging.entrego.org/v1/locations/provinces/43044/municipalities
GET	/v1/locations/municipalities/{municipality - id}/barangays	Retrieve All Barangays by Municipality ID	https://api-core-staging.entrego.org/v1/locations/municipalities/44738/barangays

Other APIs

HTTP Method	URL Path	Description	Sample
GET	/v1/locations/port-codes	Retrieve All Port Codes	https://api-core-staging.entrego.org/v1/locations/port-codes
GET	/v1/locations/port-cides/{port-code}	Retrieve Port Code by {port-code}	https://api-core-staging.entrego.org/v1/locations/port-codes/SOU
GET	/v1/locations/port-codes/islands/{island-name}	Retrieve Port Code by island-name	N/A
GET	/v1/locations/provinces/iso/{iso-code}	Retrieve provinces by ISO Code. Refer to Entrego API Docs for ISO Codes	N/A
GET	/v1/locations/provinces/{province-name}	Retrieve Province by Province Name	https://api-core-staging.entrego.org/v1/locations/provinces/negros occidental
GET	/v2/locations/barangay-cluster?provinceName={province-name}&cityName={city-name}	Retrieve Portcode or Barangay Cluster per Province/City combination	https://api-core-staging.entrego.org/v2/locations/barangay-cluster?provinceName=metro manila&cityName=quezon city
GET	/v2/locations/barangay-cluster?provinceName={province-name}&cityName={city-name}&barangayName={barangay-name}	Retrieve Portcode or Barangay Cluster per Province/City/Barangay combination	https://api-core-staging.entrego.org/v2/locations/barangay-cluster?provinceName=metro manila&cityName=quezon city&barangayName=kamuning

Address Clean-up API

For clients with limited capability to separate cities and provinces from long addresses, we provide a clean-up API to provide the separation of city and province.

URL: /v1/cleanup/address

Method: POST

Request Body (JSON format):

                                        
                                        
        
                                        {
                                        "address" : "<long address>",
                                        "pdfStatus" : "pending"
                                        }

Example:

Request

                                        
                                        
        
                                        {
                                        "address" : "123 Street, Bonifacio Global City, Taguig, Metro Manila",
                                        "pdfStatus" : "pending"
                                        }

Response

                                        
                                        
        
                                        {
                                        "provinceId" : 43044,
                                        "cityId" : 44738,
                                        "provinceName" : "Metro Manila,
                                        "cityName" : "Taguig"
                                        }

Waybill API

Step 1: Generate Token

Endpoints

Staging URL	https://api-staging.entrego.org
Production URL	https://api.entrego.org

URL: /v1/authenticate

Method: POST

Entrego utilizes JWT Token based authentification with a validity of 24h. To retrieve a token, send the following payload to authenticate:

                                        
                                        
                                    POST /v1/authenticate HTTP/1.1
                                    Content-Type: application/json;charset=UTF-8
                                    Host: api.entrego.com
                                    Content-Length: 55

                                    {
                                    "secretKey" : "admin",
                                    "accessKey" : "admin"
                                    }

Step 2: Generate Document ID

Endpoints

Staging URL	https://api-core-staging.entrego.org
Production URL	https://api-core.entrego.org/

URL: /v1/awb-tool/client-waybill-generation

Method: POST

Headers:

Authorization (This is where you put the bearer token generated on Step 1)
Content-type: application/json

Request Body:

                                            
                                            
    
                                        {
                                        "clientName" : "Entrego Client",
                                        "requestedBy" : "Juan dela Cruz",
                                        "contactNumberMasked" : "true",
                                        "trackingNumbers" : [
                                            "0123-XXXXXXXXXXX",
                                            "0123-XXXXXXXXXXX"
                                    ]
                                        }

clientName is the name of the client-generating waybill.
requestedBy is the one printing the waybill. So this can be representative of the client-side.
contactNumberMasked is a boolean parameter wherein you can mask the contact number shown on the waybill. It will still be seen by the rider via the app they are using for delivery purposes. You can set it to true to mask or drop it if not needed.
trackingNumbers is an array of the Entrego tracking number of the packages created via order creation.
The maximum number of tracking numbers per request is 500.

Response (JSON format):

                                                
                                                
        
                                            {
                                            "documentID" : "e1140ab7-24fd-4ee6-8c95-63b11914c73d"
                                            }

Step 3: Generate Waybill PDF for Printing

Endpoints

Staging URL	https://api-core-staging.entrego.org
Production URL	https://api-core.entrego.org/

URL: /v1/awb-tool/client-generate-output/getByDocumentId?documentId=<documentId>

Sample URL: https://api-core-staging.entrego.org/v1/awb-tool/client-generate-output/getByDocumentId?documentId=e1140ab7-24fd-4ee6-8c95-63b11914c73d

Method: GET

Sample Output:

Pending

                                                
                                                
        
                                            {
                                            "pdfUrl" : "",
                                            "pdfStatus" : "pending"
                                            }

Success

                                                
                                                
        
                                            {
                                            "pdfUrl" : "https://s3.ap-southeast-1.amazonaws.com/entrego-waybills/dev/apiclient/2020-08-13/LAZADA_001_cdb9196d-21ee-449e-ab86-40a6e6f2f508.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200813T042155Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=AKIAQ3QICJZ57YKDRWE3%2F20200813%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Signature=0c6155b81ed72981b6ac4ed8a9623539c745a0a13bd602b08ebeaecc34b4625e%22",
                                            "pdfStatus" : "success"
                                            }

Failed

                                                
                                                
        
                                            {
                                            "pdfUrl" : "",
                                            "pdfStatus" : "failed",
                                            }

Appendix A: Failed Reasons

Failed reasons used by Entrego

Reason Code	Description
1A	Customer could not pay
1B	Customer refused to accept parcel
1C	Customer cancelled while parcel was in transit
1D	Customer re-scheduled delivery to another date
1E	Customer was not available during delivery
1G	Customer was not able to provide Valid ID for proper identification
1H	Customer deceased
1I	Customer is no longer affiliated with address
1J	Customer consignee with unidentified information
2A	Courier could not find customer address
2B	Customer is unknown in the area
2C	Business is no longer operational
2D	Erroneous issuance / not ordered
2E	Pullout / Client cancelled while parcel was in transit
3A	Courier faced technical issues
3B	Courier did not have enough time to deliver the package
3C	Unavoidable weather issues
3D	Courier lost the parcel
3E	Courier damaged the parcel
3G	Incorrect delivery details on package sticker
3F	Customer address is incomplete
3H	Courier attempted delivery outside office hours
3I	Force Majeure
4A	Merchant - Not Ready
4B	Merchant - Not Around

Appendix B: Valid Updatable Parameters

The following are the currently supported updatable parameters for PATCH:

Field	Data Type	Description
weightActual	Number	Actual weight of the package
weightVolumetric	Number	Volumetric weight of the package
deliveryInstructions	String	Additional instruction for the delivery personnel
length	Number	Length of the package in centimeter
width	Number	Width of the package in centimeter
height	Number	Height of the package in centimeter
scheduledPickupDate	String	Scheduled Pickup Date of the package

Appendix C: Webhook Status

Webhook status used by Entrego

Event	Description
BAGGED	Indicates that the package is bagged alongside other packages and ready to be dispatched to another Hub/Warehouse of Entrego for Last Mile Delivery
RECEIVED_AT_HUB	Indicates that the package is already in Entrego’s possession
NOT_RECEIVED	Indicates that the package was not handed over to Entrego
REJECTED	Indicates that the package was rejected. Package rejection is dependent on factors, including size, weight, etc.
REJECTED_AND_RETURNED	Indicates that the package was rejected and was successfully delivered back to the client’s hub/warehouse
CANCELLED	Indicates that the package was cancelled by Entrego
LOST	Indicates that the package was lost. Package loss encompasses cases including accidents, mishandling of package etc
DELIVERY_PENDING	Indicates that the package is en route to the recipient
DELIVERY_FAILED	Indicates failed package delivery
DELIVERED	Indicates successful package delivery
READY_FOR_RTC	Indicates that a package wasn’t able to be delivered and will be ready to return back to the client
RECEIVED_AT_HUB_RTC	Indicates that the package is stationed in Entrego’s hub/warehouse and is ready to be delivered back to the client
DELIVERY_PENDING_RTC	Indicates that the package is en route back to the client
RETURNED_TO_SENDER	Indicates that the package was successfully delivered back to the client’s hub/warehouse
PICKUP_PENDING	Indicates that the package was successfully assigned for rider pick-up
PICKED_UP	Indicates that the package is en route to one of the hubs/warehouses
PICKUP_FAILED	Indicates failed package pick-up
IN_TRANSIT	Indicates that package is in transit to another Hub/Warehouse of Entrego for Last Mile Delivery
IN_TRANSIT_RTC	Indicates that package is in transit to another Hub/Warehouse of Entrego for Return to Client
HANDOVER_TO_3PL	Indicates that the package was handed over to another 3PL
HANDOVER_TO_TRANSPORT	Indicates that the package is already handed over to a transport vehicle ready for transfer to another Hub/Warehouse of Entrego

Appendix D: Supported Provinces

List of provinces in the Philippines

ISO	Province Name
PH-ABR	Abra
PH-AGN	Agusan del Norte
PH-AGS	Agusan del Sur
PH-AKL	Aklan
PH-ALB	Albay
PH-ANT	Antique
PH-APA	Apayao
PH-AUR	Aurora
PH-BAS	Basilan
PH-BAN	Bataan
PH-BTN	Batanes
PH-BTG	Batangas
PH-BEN	Benguet
PH-BIL	Biliran
PH-BOH	Bohol
PH-BUK	Bukidnon
PH-BUL	Bulacan
PH-CAG	Cagayan
PH-CAN	Camarines Norte
PH-CAS	Camarines Sur
PH-CAM	Camiguin
PH-CAP	Capiz
PH-CAT	Catanduanes
PH-CAV	Cavite
PH-CEB	Cebu
PH-COM	Compostela Valley
PH-NCO	Cotabato
PH-DAV	Davao del Norte
PH-DAS	Davao del Sur
PH-DVO	Davao Occidental
PH-DAO	Davao Oriental
PH-DIN	Dinagat Islands
PH-EAS	Eastern Samar
PH-GUI	Guimaras
PH-IFU	Ifugao
PH-ILN	Ilocos Norte
PH-ILS	Ilocos Sur
PH-ILI	Iloilo
PH-ISA	Isabela
PH-KAL	Kalinga
PH-LUN	La Union
PH-LAG	Laguna
PH-LAN	Lanao del Norte
PH-LAS	Lanao del Sur
PH-LEY	Leyte
PH-MAG	Maguindanao
PH-MAD	Marinduque
PH-MAS	Masbate
PH-MSC	Misamis Occidental
PH-MSR	Misamis Oriental
PH-MOU	Mountain Province
PH-NEC	Negros Occidental
PH-NER	Negros Oriental
PH-NSA	Northern Samar
PH-NUE	Nueva Ecija
PH-NUV	Nueva Vizcaya
PH-MDC	Occidental Mindoro
PH-MDR	Oriental Mindoro
PH-PLW	Palawan
PH-PAM	Pampanga
PH-PAN	Pangasinan
PH-QUE	Quezon
PH-QUI	Quirino
PH-RIZ	Rizal
PH-ROM	Romblon
PH-WSA	Samar
PH-SAR	Sarangani
PH-SIG	Siquijor
PH-SOR	Sorsogon
PH-SCO	South Cotabato
PH-SLE	Southern Leyte
PH-SUK	Sultan Kudarat
PH-SLU	Sulu
PH-SUN	Surigao del Norte
PH-SUR	Surigao del Sur
PH-TAR	Tarlac
PH-TAW	Tawi-Tawi
PH-ZMB	Zambales
PH-ZAN	Zamboanga del Norte
PH-ZAS	Zamboanga del Sur
PH-ZSI	Zamboanga Sibugay
PH-00	Metro Manila