Hammaly - API Documentation

Overview

This section of the documentation is intended to get you up-and-running with HAMMALY's API module. We'll cover everything you need to know, from authentication, to retrieving or creating data.

All data used in this tutorial is dummy and will not be valid if used in a test, staging or production environment.

Feel free to comment sending an email to info@hammaly.com in order to improve the quality of the API.

URI components

All API requests will follow the same pattern and will vary depending on: tenant thas is making the request, environment, version of the API and method be called. The scructure can seen as follows:

http://{tenant}.{env}.004delivery.com/api/v{ver}/external/{method}/

Notice that ALL end-points end with a slash (/). For the sake of the argument we will show a demo tenant account that will point to staging and production environments. So far, there is only one version of the API, so we will use v1.

Staging

http://hammaly.routes.004delivery.com/api/v1/external/regions/

Production

http://hammaly.routes.004delivery.com/api/v1/external/regions/

API Token management

API tokens are modeled as special users with no default login capabilites that have staff permissions and can only operate through an API interface. For managing API Tokens, the admin will have create them directly from the dashboard (Go to API Tokens > Create New API token). The only input required will be:

  • Managing regions: Those regions in which the API token will be access to.
  • Managing enterprises: Those enterprises in which the API token will create orders in behalf to.

It will be up to the administrator to decide how to split permissions. In some cases, it will be more convenient to have a single API token in charge of all enterprises and regions, whereas there will be other cases that, for security resions, it will be more convenient to have a different token user per region and/or enterprise.

Authentication

Once a new API token has been created we will be able to copy it directly from the list of API tokens. An API token is a unique 40-hexadecimal chars length string randomly distributed.

To authenticate our API requests we will have to include a standard token authentication header into our HTTP request. Continuing with the example showed above, in this case we would have to include the following header:

Header Name Header Value
Authorization Token ece01a24cba8a2faa20385cc995729d9bbfb496e

List regions

During order creation, it will be required to creation origin and destination locations. For each location we will need to set to which region does it belong and both location will need to share the same region. The following endpoint returns the list of regions assigned to the API token.

HTTP Method Rest Action End-Point Description
GET List /regions/ Returns a non-paginated list of all the regions associated to the API token doing the request

Response region object

Name Type Description
id integer Identifier of the region
name string Name of the region
key string Slug name of the region
is_active boolean Whether this region is active or not
country object Country associated to the region
bounds object Minimum rectangle that contains this region
timezone string Timezone associated to the region
transports list Different transports available in the region
option_groups list Different options group available in the region
option_delivery_times list Different options delivery times available in the region

Response country object

Name Type Description
name string Name of the country
code string Two letter ISO code of the country
currency object Currency associated to the country

Response currency object

Name Type Description
code string Three letter ISO code of the currency
symbol string Symbol of the currency

Response bounds object

Name Type Description
bl object Bottom-left GPS coordinates of the rectangle
tr object Top-right GPS coordinates of the rectangle

Response coordinates object

Name Type Description
gps_lat float GPS latitude
gps_lng float GPS longitude

Response transport object

Name Type Description
id integer Identifier of the transport
key string Slug identifier of the transport
name string Name of the transport
price float Base price of using this transport
charge_km_threshold float Distance from which an additional cost is charged
per_km_extra_price float Price per km when there is extra charge per km

Response option groups object

Name Type Description
id integer Identifier of the option group
key string Slug identifier of the option group
name string Name of the option group
is_mandatory boolean Whether is mandatory when creating an order
allows_multiple boolean Whether allows to select more than one option when creating the order
options list List of available options for this group

Response option object

Name Type Description
id integer Identifier of the option
key string Slug identifier of the option
name string Name of the option
price float Additional cost of selecting this option

Response option delivery time object

Name Type Description
id integer Identifier of the option
key string Slug identifier of the option
name string Name of the option
price float Additional cost of selecting this option
starts_at string Datetime corresponding to the earliest delivery time
ends_at string Datetime corresponding to the latest delivery time

Below, we can see and an example of a server response

List enterprises

During order creation, it will be required to set an link an order to the enterprise requiring for the service. The following endpoint returns the list of enterprises assigned to the API token.

HTTP Method Rest Action End-Point Description
GET List /enterprises/ Returns a non-paginated list of all the enterprises associated to the API token doing the request

Response enterprise object

Name Type Description
id integer Identifier of the enterprise
name string Name of the enterprise
key string URL to the logo or picture of the enterprise
is_active boolean Whether this enterprise is active or not

Create order

Main end-point for order creation on behalf of an enterprise that wants a package to be picked up and delivered to final customer.

HTTP Method Rest Action End-Point Description
POST Create /orders/ Creates an order (pick up and delivery transactions)

We will need to send the following order information as JSON encoded in the body of the request.

Request order object

Name Type Required Description
pickup_location object yes Location to pick the package up
delivery_location object yes Location to deliver the package
sender object yes Person that will be sending the package
receiver object yes Person that will be receiving the package
option_transport integer yes Id of the transport object (retreived from regions) required for doing the shipment
option_extras list no List of id of the extra options object (retreived from regions) required for doing the shipment
option_delivery_time integer yes Id of delivery time slot object (retreived from regions) required for doing the shipment
enterprise integer yes Id of the enterprise that will be sending the package
external_code string no Unique code to attach to the order
comment string no Comment to attach to the order

Request location object

Name Type Required Description
region integer yes Id of the region to create the location in
formatted_address string yes Displayable address of the location
route string no Street name of the address (as it appears in Google Maps API)
street_number string no Street number of the address (as it appears in Google Maps API)
premise string no Location or building name of the address (as it appears in Google Maps API)
postal_code string no Postal code of the address (as it appears in Google Maps API)
locality string no Locality of the address (as it appears in Google Maps API)
sublocality string no Sublocality of the address (as it appears in Google Maps API)
door_details string no Additional indication to reach the location (door, floor, etc.)
comments string no Comments to attach to the location
gps_lat float yes GPS latitude of the location
gps_lng float yes GPS longitude of the location

Request user object

Name Type Required Description
first_name string yes First name of the person
last_name string no Last name of the person
email string yes Email address to contact the person
phone string yes Phone number to contact the person

Below, we can see and an example of an order creation request

After this, the server will create an order object and will attach/compute some additional fields required for processing the orders. This is the detail of the information received back

Response order object

Name Type Description
delivery_location object Location of the delivery place
pickup_location object Location of the pickup place
receiver object Person that will be receiving the package
sender object Person that will be sending the package
option_transport object To deprecate
option_extras list To deprecate
option_delivery_time object To deprecate
option_delivery_time_pricing_rule object To deprecate
items list All concepts that conform the invoice
code string Unique 6-letter uppercased code that identifies the order
external_code string Unique customer provided code that identifies the order
comment string Comment attached to the order the order
confirmation_state string State that indicates whether the order has been insterted correctly
assignation_state string State that indicates whether the order has already been assigned to a courier
logistic_state string State that indicates the state along the whole logistic process
receiver_signature string URL to the image that contains the signature of the receiver
package_picture string URL to the image that contains the picture of the package
package_description string Description of the package
receipt_picture string To deprecate
n_packages integer Number of packages that contained in the order
service_exc_tax_amount float Gross value of the service
service_tax_amount float Tax amount value of the service
service_inc_tax_amount float Net value of the service
tip_amount float To deprecate
polyline string Google Maps created polyline from origin to destination
meters integer Distance between origin and destination
seconds integer Time to complete the route between origin and destination
pickup_starts_after string Datetime that indicates the earliest time to pickup
pickup_ends_after string Datetime that indicates the latest time to pickup
delivery_starts_after string Datetime that indicates the earliest time to deliver
delivery_ends_after string Datetime that indicates the latest time to deliver
created_at string Timestamp of the order creation
enterprise object Enterprise related to the order

Response Item object

Name Type Description
position integer Position of this item in the invoice
concept string Description of the item
price float Cost of the item
tax float Tax amount of the item

Below, we can see and an example of a server response to the request sent above.

Retrieve order

HTTP Method Rest Action End-Point Description
GET Retrieve /orders/{pk}/ Returns the order associated to the pk provided

The object returned will be the same than the object returned when creating the order.

List orders

HTTP Method Rest Action End-Point Description
GET List /orders/ Returns a paginated list of orders

The object returned will be a pagination wrapper that contains a list of orders. The order object returned will be the same than the object returned when creating the order. In addition, some filters can be passed through querystring to obtain some more accurate results.

Name of the filter Description
enterprise Id of an enterprise from which we want to retrieve all orders
region Id of a region from which we want to retrieve all orders
logistic_state Logistic state of the order. All possible values are: initial, picked-up, delivered, rejected, returned and cancelled

Response paginated list of orders object

Name Type Description
count integer Total number of elements in the list
next string URL to next batch of orders
previous string URL to previous batch of orders
results list Actual list of orders