Courier Company API

Courier Company API allows to communicate with Tiramizoo.
Host: https://sandbox.tiramizoo.com/courier_company_api.
Text payloads are supported only as UTF-8-encoded.

All API endpoints are protected.
Authorization required via param api_token or header Api-Token

External Offers Management ¶

Notification offer request ¶

Notification offer request
POST`/offers_notification_api_url`

If your company:

has Third party offer based system as distribution method. You can check it in your courier company dashboard page
had provided us offers_notification_api_url

then we will make notification POST request to given offers_notification_api_url with offer details for handling new order.

Request is made over SSL.
If your company has ssl_verify_peer set to false than SSL peer verification is switched off.

Attribute name	Type	Description	Available types:
id	`string`	Order identifier
distance	`number`	Distance in between pickup & delivery locations
hazard_index	`number`	Dangerous goods carriage index, More
from:	`object`	Pickup data
address_line	`string`	Sender’s address
postal_code	`string`	Sender’s postal code
country_code	`string`	Sender’s country code
city	`string`	Sender’s city
after	`string`	Pickup after
before	`string`	Pickup before
phone_number_type	`string`	Phone number type
requirements:	`array`	Pickup requirements
type:	`string`	Requirement type	loading_assistance
message:	`string`	Message of requirement in client’s language	Loading assistance needed
to:	`object`	Delivery data
address_line	`string`	Recipient’s address
postal_code	`string`	Recipient’s postal code
country_code	`string`	Recipient’s country code
city	`string`	Recipient’s city
after	`string`	Delivery after
before	`string`	Delivery before
phone_number_type	`string`	Phone number type
requirements:	`array`	Delivery requirements
type:	`string`	Requirement type	loading_assistance
message:	`string`	Message of requirement in client’s language	Loading assistance needed
packages:	`array`	Order packages
weight	`number`	Package weight
height	`number`	Package height
width	`number`	Package width
length	`number`	Package length
size	`string`	Package size

Example URI

POST https://sandbox.tiramizoo.com/courier_company_api/offers_notification_api_url

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "K6BYDF",
  "from": {
    "address_line": "Frank-Strasse 10",
    "postal_code": "14195",
    "country_code": "de",
    "city": "Berlin",
    "after": "2018-04-02T10:22:59+02:00",
    "before": "2018-04-02T11:22:59+02:00",
    "phone_number_type": "mobile",
    "requirements": [
      {
        "type": "loading_assistance",
        "message": "Loading assistance needed"
      }
    ]
  },
  "to": {
    "address_line": "Berlin-Strasse 77",
    "postal_code": "14195",
    "country_code": "de",
    "city": "Berlin",
    "after": "2018-04-02T14:22:59+02:00",
    "before": "2018-04-02T15:22:59+02:00",
    "phone_number_type": "mobile",
    "requirements": [
      {
        "type": "loading_assistance",
        "message": "Loading assistance needed"
      }
    ]
  },
  "distance": 2.9,
  "hazard_index": 0,
  "packages": [
    {
      "length": 30,
      "weight": 5,
      "height": 20,
      "width": 10,
      "size": "L"
    }
  ]
}

Response 201

HideShow

The endpoint orders_notification_api_url should respond with status 201.

Headers

Content-Type: application/json

Order notification ¶

Order notification request
POST`/orders_notification_api_url`

If your company:

has Third party system as distribution method. You can check it in your courier company dashboard page
had provided us orders_notification_api_url

then we will create offer for handling new order. We accept this offer in behalf of your company and we make notification POST request to given orders_notification_api_url with the order details.

Request is made over SSL.
If your company has ssl_verify_peer set to false than SSL peer verification is switched off.

Attribute name	Type	Description	Available types:
id	`string`	Order identifier
uuid	`string`	Order uuid IMPORTANT! This property is deprecated and will be removed by the end of July 2016
webhook_url	`string`	Url under which there is information about the order (More )
current_state	`string`	Order current state
delivery_type	`string`	Delivery type
from:	`object`	Pickup data
address_line	`string`	Sender’s address
postal_code	`string`	Sender’s postal code
country_code	`string`	Sender’s country code
city	`string`	Sender’s city
after	`string`	Pickup after
before	`string`	Pickup before
phone_number_type	`string`	Phone number type
requirements:	`array`	Pickup requirements
type:	`string`	Requirement type	age security_code loading_assistance custom signature external_identifier_scanning
value:	`string`	Requirement value. Requirements with a type `loading_assistance` and `signature` doesn’t have value parameter.
to:	`object`	Delivery data
address_line	`string`	Recipient’s address
postal_code	`string`	Recipient’s postal code
country_code	`string`	Recipient’s country code
city	`string`	Recipient’s city
after	`string`	Delivery after
before	`string`	Delivery before
phone_number_type	`string`	Phone number type
requirements:	`array`	Delivery requirements
type:	`string`	Requirement type	age security_code loading_assistance custom signature external_identifier_scanning
value:	`string`	Requirement value. Requirements with type `loading_assistance` and `signature` doesn’t have value parameter.
packages:	`array`	Order packages
weight	`number`	Package weight
height	`number`	Package height
width	`number`	Package width
length	`number`	Package length
description	`string`	Package description
size	`string`	Package size
identifier	`string`	Package identifier
non_rotatable	`boolean`	Specify if package can be rotated/turned around during transport

Example URI

POST https://sandbox.tiramizoo.com/courier_company_api/orders_notification_api_url

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "OTROVL",
  "uuid": "2fd5cc89-dfa7-4aac-bc1a-99af8b88d6db",
  "webhook_url": "https://sandbox.tiramizoo.com/courier_company_api/v1/orders/OTROVL?api_token=6dd9c41aa6ce4462007df7b673ef3767",
  "from": {
    "name": "Otto Schmidt",
    "address_line": "Frank-Strasse 10",
    "country_code": "de",
    "postal_code": "14195",
    "city": "Berlin",
    "information": "go go go",
    "phone": "30049223333",
    "after": "2018-04-02T08:22:59Z",
    "before": "2018-04-02T09:22:59Z",
    "requirements": [
      {
        "type": "loading_assistance"
      },
      {
        "type": "signature"
      },
      {
        "type": "age",
        "value": 18
      },
      {
        "type": "security_code",
        "value": "ABC734"
      },
      {
        "type": "custom",
        "value": "Satellite installation service"
      },
      {
        "type": "external_identifier_scanning",
        "value": "A1010[0-9]{10}z"
      }
    ]
  },
  "to": {
    "name": "Anna Schneider",
    "address_line": "Berlin-Strasse 77",
    "country_code": "de",
    "postal_code": "14195",
    "city": "Berlin",
    "information": "now now now",
    "phone": "30049224444",
    "after": "2018-04-02T12:22:59Z",
    "before": "2018-04-02T13:22:59Z",
    "requirements": [
      {
        "type": "loading_assistance"
      },
      {
        "type": "signature"
      },
      {
        "type": "age",
        "value": 18
      },
      {
        "type": "security_code",
        "value": "ABC734"
      },
      {
        "type": "custom",
        "value": "Satellite installation service"
      },
      {
        "type": "external_identifier_scanning",
        "value": "A1010[0-9]{10}z"
      }
    ]
  },
  "current_state": "created",
  "delivery_type": "standard",
  "packages": [
    {
      "weight": 5,
      "height": 20,
      "width": 10,
      "length": 30,
      "quantity": 1,
      "identifier": "4C23D52C63BF89F3",
      "size": "L",
      "description": "A fish",
      "non_rotatable": false
    }
  ]
}

Response 201

HideShow

The endpoint orders_notification_api_url should respond with status 201.

Headers

Content-Type: application/json

Order notification update
PUT`/orders_notification_api_url`

If your company:

has Third party system as distribution method. You can check it in your courier company dashboard page
had provided us orders_notification_api_url

then we will make notification PUT request to given orders_notification_api_url in case order changes state to picked_up, delivered or cancelled.

Request is made over SSL.
If your company has ssl_verify_peer set to false than SSL peer verification is switched off

Attribute name	Type	Description
id	`string`	Order identifier
uuid	`string`	Order uuid. IMPORTANT! This property is deprecated and will be removed by the end of July 2016
current_state	`string`	Order current state
webhook_url	`string`	Url under which there is information about the order (More )

Example URI

PUT https://sandbox.tiramizoo.com/courier_company_api/orders_notification_api_url

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "HYJKCK",
  "uuid": "f1d94598-a5df-4a9a-a1d3-070386a2e1bb",
  "webhook_url": "https://sandbox.tiramizoo.com/courier_company_api/v1/orders/HYJKCK?api_token=fb0fd657fa37999f786e03dc536df69a",
  "current_state": "delivered"
}

Response 200

HideShow

The endpoint orders_notification_api_url should respond with status 200.

Headers

Content-Type: application/json

Courier Offers ¶

Create or accept offer ¶

Create or accept offer
POST`/v1/courier_offers`

Attribute name	Type	Required	Description	Available types:
api_token	`string`	`X`	Authorization token
courier_uuid	`string`	`X`	Courier uuid
delivery_id	`string`	`X`	Order identifier
delivery_uuid	`string`		Order uuid. IMPORTANT! This property is deprecated and will be removed by the end of July 2016
state	`string`	For offer creation param `state` is not required. For offer acceptance param `state` is required with value `accepted`	Offer state	created accepted

Example URI

POST https://sandbox.tiramizoo.com/courier_company_api/v1/courier_offers

Request

HideShow

Offer acceptance if param "state": "accepted".
Offer creation if there is no param "state".

Headers

Content-Type: application/json

Body

{
  "api_token": "awv7yhhfkk",
  "courier_uuid": "a77d952a-6732-4745-a206-4fb3ae95092b",
  "delivery_id": "JVN5EM",
  "delivery_uuid": "0195468d-764b-4925-9366-69634e012324",
  "state": "created"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "api_token": {
      "type": "string",
      "description": "Authorization token"
    },
    "courier_uuid": {
      "type": "string",
      "description": "Courier uuid"
    },
    "delivery_id": {
      "type": "string",
      "description": "Order identifier"
    },
    "delivery_uuid": {
      "type": "string",
      "description": "Order uuid. IMPORTANT! This property is deprecated and will be removed by the end of July 2016"
    },
    "state": {
      "type": "string",
      "enum": [
        "created",
        "accepted"
      ],
      "description": "Offer state"
    }
  },
  "required": [
    "api_token",
    "courier_uuid",
    "delivery_id"
  ]
}

Response 201

HideShow

For offer creation returned "state": "created".
For offer acceptance returned "state": "accepted".

Headers

Content-Type: application/json

Body

{
  "id": 835,
  "courier_id": 999,
  "courier_company_offer_id": 9999,
  "state": "created",
  "created_at": "2018-04-02T10:22:59+02:00",
  "updated_at": "2018-04-02T10:22:59+02:00",
  "delivery_id": 7608,
  "uuid": "bbac485b-eba0-4c16-b4e9-c8264350cbaf"
}

Delete offer ¶

Delete offer
DELETE`/v1/courier_offers/{id}{?api_token}`

id parameter is uuid courier offer property.
You can obtain this value from response CREATE OR ACCEPT OFFER

Example URI

DELETE https://sandbox.tiramizoo.com/courier_company_api/v1/courier_offers/0195468d-764b-4925-9366-69634e01b4c3?api_token=awv7yhhfkk

URI Parameters

HideShow

id: string (required) Example: 0195468d-764b-4925-9366-69634e01b4c3
Courier offer uuid
api_token: string (required) Example: awv7yhhfkk
Authorization token

Request

HideShow

Headers

Content-Type: application/json

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": "true"
}

Order Events ¶

Create event ¶

Create event
POST`/v1/order_events`

Attribute name	Type	Required	Description	Available types:
api_token	`string`	`X`	Authorization token
id	`string`	`X`	Order identifier
delivery_uuid	`string`		Order uuid IMPORTANT! This property is deprecated and will be removed by the end of July 2016
recorded_at	`string`		Date time. If none is provided current time stamp will be taken.
retry_at	`string`		Date time when event should be retried
service_time	`number`	`X`	Time in minutes, how long the event last
type	`string`	`X`	Event type	Pickup failed events: package_was_not_ready sender_wants_to_cancel sender_was_not_at_home wrong_package_size Delivery failed events: abort_delivery not_enough_money_for_payment package_is_damaged package_was_delivered_too_late package_was_not_accepted package_was_not_ordered recipient_was_not_at_home Universal (pickup and delivery) failed events: name_not_found_on_doorbell no_attempt_due_to_being_late address_not_found failed_due_to_business_closed
additional_service_time_reason	`string`	Mandatory in case `service_time` is greater than 5 minutes.	Additional service time reason	On pickup: goods_could_not_be_found handover_took_longer_as_planned place_was_not_specified_correctly contact_was_not_available contact_was_busy courier_was_ignored On delivery: contact_could_not_be_found unloading_longer_than_expected_due_bulky_goods recipient_was_contacted_by_phone hotline_had_to_be_contacted_for_clarification

Example URI

POST https://sandbox.tiramizoo.com/courier_company_api/v1/order_events

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "api_token": "awv7yhhfkk",
  "id": "K6BYDF",
  "delivery_uuid": "a1e05df7-db0d-4312-895a-5f3b4b718b6a",
  "recorded_at": "2018-04-02 08:00:00Z",
  "retry_at": "2018-04-03 15:18:42Z",
  "service_time": 10,
  "type": "package_was_not_ready",
  "additional_service_time_reason": "goods_could_not_be_found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "api_token": {
      "type": "string",
      "description": "Authorization token"
    },
    "id": {
      "type": "string",
      "description": "Order identifier"
    },
    "delivery_uuid": {
      "type": "string",
      "description": "Order uuid. IMPORTANT! This property is deprecated and will be removed by the end of July 2016"
    },
    "recorded_at": {
      "type": "string",
      "description": "Date time, if none is provided current time stamp will be taken"
    },
    "retry_at": {
      "type": "string",
      "description": "Date time when event should be retried"
    },
    "service_time": {
      "type": "number",
      "description": "Time in minutes, how long the event lasted"
    },
    "type": {
      "type": "string",
      "enum": [
        "package_was_not_ready",
        "sender_wants_to_cancel",
        "sender_was_not_at_home",
        "wrong_package_size",
        "abort_delivery",
        "address_not_found",
        "failed_due_to_business_closed",
        "name_not_found_on_doorbell",
        "no_attempt_due_to_being_late",
        "not_enough_money_for_payment",
        "package_is_damaged",
        "package_was_delivered_too_late",
        "package_was_not_accepted",
        "package_was_not_ordered",
        "recipient_was_not_at_home"
      ],
      "description": "Event type"
    },
    "additional_service_time_reason": {
      "type": "string",
      "enum": [
        "goods_could_not_be_found",
        "handover_took_longer_as_planned",
        "place_was_not_specified_correctly",
        "contact_was_not_available",
        "contact_was_busy",
        "courier_was_ignored",
        "contact_could_not_be_found",
        "unloading_longer_than_expected_due_bulky_goods",
        "recipient_was_contacted_by_phone",
        "hotline_had_to_be_contacted_for_clarification"
      ],
      "description": "Mandatory in case `service_time` is greater than 5 minutes."
    }
  },
  "required": [
    "api_token",
    "id",
    "service_time",
    "type"
  ]
}

Response 201

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "H1G0DG",
  "uuid": "c6653984-5e32-4acc-981c-d1ffff2ede99",
  "current_state": "pickup_failed"
}

Orders ¶

Obtain courier company orders ¶

Obtain courier company orders
GET`/v1/orders{?api_token,from,page,per_page}`

Example URI

GET https://sandbox.tiramizoo.com/courier_company_api/v1/orders?api_token=awv7yhhfkk&from=2012-01-07 15:18:42Z&page=1&per_page=100

URI Parameters

HideShow

api_token: string (required) Example: awv7yhhfkk
Authorization token
from: string (optional) Example: 2012-01-07 15:18:42Z
Date since when fetch orders
page: string (optional) Example: 1
Number of page results
per_page: string (optional) Example: 100
Number of orders per page (default 200, maximum 200)

Request

HideShow

Headers

Content-Type: application/json

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "orders": [
    {
      "identifier": "KTLB7I",
      "uuid": "6c515318-857f-4cea-a811-bcd08ab53d3a",
      "state": "created",
      "created_at": "2012-04-16T05:00:00+02:00",
      "from": {
        "name": "--- Hidden ---",
        "address_line": "Im Dol 2",
        "city": "Berlin",
        "postal_code": "14195",
        "country_code": "de",
        "phone_number": "--- Hidden ---",
        "after": "2012-04-16T07:00:00+02:00",
        "before": "2012-04-16T07:30:00+02:00",
        "information": "--- Hidden ---",
        "requirements": []
      },
      "to": {
        "name": "--- Hidden ---",
        "address_line": "Im Dol 48",
        "city": "Berlin",
        "postal_code": "14195",
        "country_code": "de",
        "phone_number": "--- Hidden ---",
        "after": "2012-04-16T07:30:00+02:00",
        "before": "2012-04-16T09:00:00+02:00",
        "information": "--- Hidden ---",
        "requirements": []
      },
      "packages": [
        {
          "weight": 5,
          "height": 20,
          "width": 10,
          "length": 30,
          "size": "L",
          "description": "--- Hidden ---",
          "identifier": "--- Hidden ---"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "total_pages": 1,
      "per_page": 100
    }
  }
}

Order ¶

Show order
GET`/v1/orders/{id}{?api_token}`

id parameter is identifier property of an order.
You can obtain this value in response OBTAIN COURIER COMPANY ORDERS

The response depends on offer acceptance.
Please check example responses for details.

Example URI

GET https://sandbox.tiramizoo.com/courier_company_api/v1/orders/K6BYDF?api_token=awv7yhhfkk

URI Parameters

HideShow

api_token: string (required) Example: awv7yhhfkk
Authorization token
id: string (required) Example: K6BYDF
Order identifier
IMPORTANT! Order uuid as id is deprecated and will be not supported by the end of July 2016

Request

HideShow

Headers

Content-Type: application/json

Response 200

HideShow

Response when offer was accepted.

Headers

Content-Type: application/json

Body

{
  "identifier": "KDQ5RU",
  "external_id": "Q97GZZ",
  "uuid": "c4aa7b51-dad7-4849-82c9-4f618cb2407d",
  "state": "dispatched",
  "created_at": "2012-04-16T05:00:00+02:00",
  "description": "rubber chicken and chunky bacon",
  "courier_information": "go go go; now now now",
  "from": {
    "name": "I.P. Freely",
    "phone_number": "30049223333",
    "email": null,
    "address_line": "Im Dol 2",
    "city": "Berlin",
    "postal_code": "14195",
    "country_code": "de",
    "after": "2012-04-16T07:00:00+02:00",
    "before": "2012-04-16T07:30:00+02:00",
    "requirements": []
  },
  "to": {
    "name": "Mike Rotch",
    "phone_number": "30049224444",
    "email": null,
    "address_line": "Im Dol 48",
    "city": "Berlin",
    "postal_code": "14195",
    "country_code": "de",
    "after": "2012-04-16T07:30:00+02:00",
    "before": "2012-04-16T09:00:00+02:00",
    "requirements": []
  },
  "courier": {
    "name": "Elisha Quigley",
    "email": "courier_1@example.com",
    "phone_number": "+48 666 666 661"
  },
  "from_signature": null,
  "to_signature": null,
  "return_signature": null,
  "packages": [
    {
      "weight": 5,
      "height": 20,
      "width": 10,
      "length": 30,
      "quantity": 1,
      "identifier": "40407E3C3FB89060",
      "size": "L",
      "description": "A fish",
      "non_rotatable": false
    }
  ]
}

Request

HideShow

Headers

Content-Type: application/json

Response 200

HideShow

Response when offer was not yet accepted.

Headers

Content-Type: application/json

Body

{
  "identifier": "EFTOJ2",
  "uuid": "036a6126-3e0f-4a07-bbc7-9b8aa2e1b815",
  "state": "created",
  "created_at": "2012-04-16T05:00:00+02:00",
  "from": {
    "name": "--- Hidden ---",
    "address_line": "Im Dol 2",
    "city": "Berlin",
    "postal_code": "14195",
    "country_code": "de",
    "phone_number": "--- Hidden ---",
    "after": "2012-04-16T07:00:00+02:00",
    "before": "2012-04-16T07:30:00+02:00",
    "information": "--- Hidden ---",
    "requirements": []
  },
  "to": {
    "name": "--- Hidden ---",
    "address_line": "Im Dol 48",
    "city": "Berlin",
    "postal_code": "14195",
    "country_code": "de",
    "phone_number": "--- Hidden ---",
    "after": "2012-04-16T07:30:00+02:00",
    "before": "2012-04-16T09:00:00+02:00",
    "information": "--- Hidden ---",
    "requirements": []
  },
  "packages": [
    {
      "weight": 5,
      "height": 20,
      "width": 10,
      "length": 30,
      "size": "L",
      "description": "--- Hidden ---",
      "identifier": "--- Hidden ---"
    }
  ]
}

Update order
PUT`/v1/orders/{id}`

id parameter is identifier property of an order.
You can obtain this value in response OBTAIN COURIER COMPANY ORDERS

The response depends on offer acceptance.
Please check example responses for details.

Order state transitions

From state	To state (current_state)	Signature required?	Service time required?	Delivered to required?	Additional_service_time_reason required?
distributed	dispatched
dispatched	picked_up	`*`	`X`		`**`
picked_up	delivered	`*`	`X`	`X`	`**`
delivery_failed	returned	`*`	`X`		`**`

* - Mandatory in case order’s requirements contain {"type": "signature"}

** - Mandatory in case service_time is greater than 5 minutes

Attribute name	Type	Required	Description	Available types:
api_token	`string`	`X`	Authorization token
id	`string`	`X`	Order identifier
current_state	`string`	`X`	New state to which order goes	canceled dispatched picked_up pickup_failed delivered delivery_failed returned
recorded_at	`string`	`X`	Date time
service_time	`number`	Mandatory with current_state: `picked_up`, `pickup_failed`, `delivered`, `delivery_failed`, `returned`.	Time in minutes, how long the event last
additional_service_time_reason	`string`	Mandatory in case `service_time` is greater than `5 minutes`.	Additional service time reason	With current_state = `picked_up` / `pickup_failed`: goods_could_not_be_found handover_took_longer_as_planned place_was_not_specified_correctly contact_was_not_available contact_was_busy courier_was_ignored With current_state = `delivered` / `delivery_failed`: contact_could_not_be_found unloading_longer_than_expected_due_bulky_goods recipient_was_contacted_by_phone hotline_had_to_be_contacted_for_clarification With current_state = `returned`: courier_was_ignored reception_was_refused receiving_department_was_busy
delivered_to	`string`	Mandatory in case current_state is `delivered`	Specify to whom was order delivered	neighbour recipient housemate safe_place
signature:	`object`	Mandatory in case order require signature	Signature
name	`string`		Recipient / sender name
data_uri	`string`		Image (png, jpg, jpeg, gif). Image encoded using Data URI scheme. File max size 100 kb
packages:	`array`		Packages
identifier	`string`		Identifier of the package
state	`string`		State to which the package is being transitioned to	pending (initial state) picked_up not_picked_up delivered not_delivered returned
external_id	`string`		ID of the package assigned by sender/courier company

Example URI

PUT https://sandbox.tiramizoo.com/courier_company_api/v1/orders/K6BYDF

URI Parameters

HideShow

id: string (required) Example: K6BYDF
Order identifier.
IMPORTANT! Order uuid as id is deprecated and will be not supported by the end of July 2016

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "api_token": "awv7yhhfki",
  "id": "K6BYDF",
  "current_state": "dispatched",
  "recorded_at": "2015-01-07 15:18:42Z",
  "service_time": 10,
  "delivered_to": "neighbour",
  "signature": {
    "name": "Otto Muller",
    "data_uri": "R0lGODlhER0lGODlhE"
  },
  "packages": [
    {
      "identifier": "24B2BC0E445D477E",
      "state": "pending",
      "external_id": "1040980011325307"
    }
  ],
  "additional_service_time_reason": "goods_could_not_be_found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "api_token": {
      "type": "string",
      "description": "Authorization token"
    },
    "id": {
      "type": "string",
      "description": "Identifier of accepted order IMPORTANT! Order uuid as id is deprecated and will be not supported by the end of July 2016"
    },
    "current_state": {
      "type": "string",
      "enum": [
        "dispatched",
        "picked_up",
        "delivered",
        "returned"
      ],
      "description": "New state to which order goes"
    },
    "recorded_at": {
      "type": "string",
      "description": "Date time"
    },
    "service_time": {
      "type": "number",
      "description": "service time"
    },
    "delivered_to": {
      "type": "string",
      "enum": [
        "neighbour",
        "recipient",
        "housemate",
        "safe_place"
      ],
      "description": "to whom order was delivered."
    },
    "signature": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "name of recipient / sender"
        },
        "data_uri": {
          "type": "string",
          "description": "image encoded using Data URI scheme. Supported formats: jpg, png, jpeg, gif. File max size 100 kb."
        }
      },
      "description": "signature (if required)"
    },
    "packages": {
      "type": "array"
    },
    "additional_service_time_reason": {
      "type": "string",
      "enum": [
        "goods_could_not_be_found",
        "handover_took_longer_as_planned",
        "place_was_not_specified_correctly",
        "contact_was_not_available",
        "contact_was_busy",
        "courier_was_ignored",
        "contact_could_not_be_found",
        "unloading_longer_than_expected_due_bulky_goods",
        "recipient_was_contacted_by_phone",
        "hotline_had_to_be_contacted_for_clarification",
        "courier_was_ignored",
        "reception_was_refused",
        "receiving_department_was_busy"
      ],
      "description": "mandatory in case current_state = `picked_up` / `pickup_failed` / `delivered` / `delivery_failed` / `returned` and `service_time` is greater than 5"
    }
  },
  "required": [
    "api_token",
    "id",
    "current_state",
    "recorded_at"
  ]
}

Response 200

HideShow

Response when offer was accepted.

Headers

Content-Type: application/json

Body

{
  "identifier": "GPFU5S",
  "external_id": "GPPGDW",
  "uuid": "c5c2aa1a-80c5-4310-aca6-5d24f905a037",
  "state": "delivered",
  "created_at": "2012-04-16T05:00:00+02:00",
  "description": "rubber chicken and chunky bacon",
  "courier_information": "go go go; now now now",
  "from": {
    "name": "I.P. Freely",
    "phone_number": "30049223333",
    "email": null,
    "address_line": "Im Dol 2",
    "city": "Berlin",
    "postal_code": "14195",
    "country_code": "de",
    "after": "2012-04-16T07:00:00+02:00",
    "before": "2012-04-16T07:30:00+02:00",
    "requirements": []
  },
  "to": {
    "name": "Mike Rotch",
    "phone_number": "30049224444",
    "email": null,
    "address_line": "Im Dol 48",
    "city": "Berlin",
    "postal_code": "14195",
    "country_code": "de",
    "after": "2012-04-16T07:30:00+02:00",
    "before": "2012-04-16T09:00:00+02:00",
    "requirements": []
  },
  "courier": null,
  "from_signature": null,
  "to_signature": {
    "url": "https://sandbox.tiramizoo.com/courier_api/v1/signatures/c48718ea-153c-4ecb-aaa1-745c7ecc7311.png",
    "name": "Otto Muller"
  },
  "return_signature": null,
  "packages": [
    {
      "weight": 5,
      "height": 20,
      "width": 10,
      "length": 30,
      "quantity": 1,
      "identifier": "9515E1F0BF710287",
      "size": "L",
      "description": "A fish",
      "non_rotatable": false
    }
  ]
}

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "api_token": "awv7yhhfkk",
  "id": "K6BYDF",
  "current_state": "dispatched",
  "recorded_at": "2015-01-07 15:18:42Z",
  "service_time": 10,
  "delivered_to": "neighbour",
  "signature": {
    "name": "Otto Muller",
    "data_uri": "R0lGODlhER0lGODlhE"
  },
  "additional_service_time_reason": "goods_could_not_be_found"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "api_token": {
      "type": "string",
      "description": "Authorization token"
    },
    "id": {
      "type": "string",
      "description": "Identifier of accepted order IMPORTANT! Order uuid as id is deprecated and will be not supported by the end of July 2016"
    },
    "current_state": {
      "type": "string",
      "enum": [
        "dispatched",
        "picked_up",
        "pickup_failed",
        "delivered",
        "delivery_failed",
        "returned",
        "canceled"
      ],
      "description": "New state to which order goes"
    },
    "recorded_at": {
      "type": "string",
      "description": "Date time"
    },
    "service_time": {
      "type": "number",
      "description": "service time"
    },
    "delivered_to": {
      "type": "string",
      "enum": [
        "neighbour",
        "recipient",
        "housemate",
        "safe_place"
      ],
      "description": "to whom order was delivered."
    },
    "signature": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "name of recipient / sender"
        },
        "data_uri": {
          "type": "string",
          "description": "image encoded using Data URI scheme. Supported formats: jpg, png, jpeg, gif. File max size 100 kb."
        }
      },
      "description": "signature (if required)"
    },
    "additional_service_time_reason": {
      "type": "string",
      "enum": [
        "goods_could_not_be_found",
        "handover_took_longer_as_planned",
        "place_was_not_specified_correctly",
        "contact_was_not_available",
        "contact_was_busy",
        "courier_was_ignored",
        "contact_could_not_be_found",
        "unloading_longer_than_expected_due_bulky_goods",
        "recipient_was_contacted_by_phone",
        "hotline_had_to_be_contacted_for_clarification",
        "courier_was_ignored",
        "reception_was_refused",
        "receiving_department_was_busy"
      ],
      "description": "mandatory in case current_state = `picked_up` / `pickup_failed` / `delivered` / `delivery_failed` / `returned` and `service_time` is greater than 5"
    }
  },
  "required": [
    "api_token",
    "id",
    "current_state",
    "recorded_at"
  ]
}

Response 200

HideShow

Response when offer was not yet accepted.

Headers

Content-Type: application/json

Body

{
  "identifier": "X7DR0M",
  "uuid": "de8c3b09-3894-4adb-8ef2-da3efab20e74",
  "state": "created",
  "created_at": "2012-04-16T05:00:00+02:00",
  "from": {
    "name": "--- Hidden ---",
    "address_line": "Im Dol 2",
    "city": "Berlin",
    "postal_code": "14195",
    "country_code": "de",
    "phone_number": "--- Hidden ---",
    "after": "2012-04-16T07:00:00+02:00",
    "before": "2012-04-16T07:30:00+02:00",
    "information": "--- Hidden ---",
    "requirements": []
  },
  "to": {
    "name": "--- Hidden ---",
    "address_line": "Im Dol 48",
    "city": "Berlin",
    "postal_code": "14195",
    "country_code": "de",
    "phone_number": "--- Hidden ---",
    "after": "2012-04-16T07:30:00+02:00",
    "before": "2012-04-16T09:00:00+02:00",
    "information": "--- Hidden ---",
    "requirements": []
  },
  "packages": [
    {
      "weight": 5,
      "height": 20,
      "width": 10,
      "length": 30,
      "size": "L",
      "description": "--- Hidden ---",
      "identifier": "--- Hidden ---"
    },
    {
      "weight": 5,
      "height": 20,
      "width": 10,
      "length": 30,
      "size": "L",
      "description": "--- Hidden ---",
      "identifier": "--- Hidden ---"
    }
  ]
}

Response 422

HideShow

Signature params are missing	State transition invalid
returned if signature required	returned if delivery new state is incorrect

Headers

Content-Type: application/json

Couriers ¶

Obtain couriers ¶

Obtain couriers
GET`/v1/couriers{?api_token,page,per_page}`

Example URI

GET https://sandbox.tiramizoo.com/courier_company_api/v1/couriers?api_token=awv7yhhfkk&page=1&per_page=200

URI Parameters

HideShow

page: string (optional) Example: 1
Page number
per_page: string (optional) Example: 200
Couriers per page (default: 200, maximum: 200)
api_token: string (required) Example: awv7yhhfkk
Authorization token

Request

HideShow

Headers

Content-Type: application/json

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "couriers": [
      {
        "uuid": "45feacc9-613b-428d-8a1b-82cfd18baa8d",
        "name": "courier",
        "email": "courier@tiramizoo.com",
        "phone_number": "4912141241",
        "language_code": "de",
        "available_vehicle_types": [
          {
            "name": "bike",
            "kind": "bike",
            "max_length": 50,
            "max_width": 30,
            "max_height": 30,
            "max_weight": 5,
            "identifier": "bike",
            "active": false
          },
          {
            "name": "van",
            "kind": "car",
            "max_length": 350,
            "max_width": 150,
            "max_height": 180,
            "max_weight": 1000,
            "identifier": "van",
            "active": true
          }
        ],
        "suspended": false,
        DEPRECATED "vehicle_type": "van",
        DEPRECATED "vehicle_max_length": 350,
        DEPRECATED "vehicle_max_width": 150,
        DEPRECATED "vehicle_max_height": 180,
        DEPRECATED "vehicle_max_weight": 1000
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "total_pages": 1,
        "per_page": 200
      }
    }
  }

Add courier ¶

Add courier
POST`/v1/couriers`

Attribute name	Type	Required	Description	Available types:
api_token	`string`	`X`	Authorization token
name	`string`	`X`	New courier name
email	`string`	`X`	New courier email
phone_number	`string`	`X`	New courier phone number
language_code	`string`	`X`	Language code which courier uses	en de fr ph pl
vehicle_type_identifier	`string`	`X`	Vehicle which courier uses	bike scooter cargobike car caddy van large_van
password	`string`	`X`	Password required for courier administaration panel. Must be at least 8 characters long
password_confirmation	`string`	`X`	Confirmation, must match `password` field
time_zone	`string`	`X`	Courier time zone	Europe/Berlin Europe/London Asia/Manila

Example URI

POST https://sandbox.tiramizoo.com/courier_company_api/v1/couriers

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "api_token": "awv7yhhfkk",
  "name": "New_courier_name",
  "email": "new@email.com",
  "phone_number": "4988877766",
  "language_code": "de",
  "vehicle_type_identifier": "bike",
  "password": "notvisible",
  "password_confirmation": "notvisible",
  "time_zone": "Europe/Berlin"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "api_token": {
      "type": "string",
      "description": "Authorization token"
    },
    "name": {
      "type": "string",
      "description": "New name for courier"
    },
    "email": {
      "type": "string",
      "description": "New email for courier"
    },
    "phone_number": {
      "type": "string",
      "description": "New phone number for courier"
    },
    "language_code": {
      "type": "string",
      "description": "Language code which courier uses"
    },
    "vehicle_type_identifier": {
      "type": "string",
      "enum": [
        "bike",
        "scooter",
        "cargobike",
        "car",
        "caddy",
        "van",
        "large_van"
      ],
      "description": "Vehicle which courier uses"
    },
    "password": {
      "type": "string",
      "description": "Password required for [courier administaration panel](https://www.tiramizoo.com/courier/sign_in). Must be at least 8 characters long"
    },
    "password_confirmation": {
      "type": "string",
      "description": "Confirmation, must match `password` field"
    },
    "time_zone": {
      "type": "string",
      "enum": [
        "Europe/Berlin",
        "Europe/London",
        "Asia/Manila"
      ],
      "description": "Time zone in which courier works. Supported time zones are:"
    }
  },
  "required": [
    "api_token",
    "name",
    "email",
    "phone_number",
    "language_code",
    "vehicle_type_identifier",
    "password",
    "password_confirmation"
  ]
}

Response 201

HideShow

Headers

Content-Type: application/json

Body

{
    "uuid": "0fb5a6e8-3ed6-4fdf-a72a-a265211ef769",
    "name": "New_courier_name",
    "email": "new@email.com",
    "phone_number": "4988877766",
    "language_code": "de",
    "available_vehicle_types": [
      {
        "name": "bike",
        "kind": "bike",
        "max_length": 50,
        "max_width": 30,
        "max_height": 30,
        "max_weight": 5,
        "identifier": "bike",
        "active": true
      },
      {
        "name": "van",
        "kind": "car",
        "max_length": 350,
        "max_width": 150,
        "max_height": 180,
        "max_weight": 1000,
        "identifier": "van",
        "active": false
      }
    ],
    "suspended": false,
    DEPRECATED "vehicle_type": "bike",
    DEPRECATED "vehicle_max_length": 50,
    DEPRECATED "vehicle_max_width": 30,
    DEPRECATED "vehicle_max_height": 30,
    DEPRECATED "vehicle_max_weight": 5
  }

Courier ¶

Show courier
GET`/v1/couriers/{id}{?api_token}`

id parameter is uuid property of an courier.
You can obtain this value in response OBTAIN COURIERS

Example URI

GET https://sandbox.tiramizoo.com/courier_company_api/v1/couriers/45feacc9-613b-428d-8a1b-82cfd18baa8d?api_token=awv7yhhfkk

URI Parameters

HideShow

id: string (required) Example: 45feacc9-613b-428d-8a1b-82cfd18baa8d
Courier identifier
api_token: string (required) Example: awv7yhhfkk
Authorization token

Request

HideShow

Headers

Content-Type: application/json

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "uuid": "45feacc9-613b-428d-8a1b-82cfd18baa8d",
    "name": "courier",
    "email": "courier@tiramizoo.com",
    "phone_number": "4912141241",
    "language_code": "de",
    "available_vehicle_types": [
      {
        "name": "bike",
        "kind": "bike",
        "max_length": 50,
        "max_width": 30,
        "max_height": 30,
        "max_weight": 5,
        "identifier": "bike",
        "active": false
      },
      {
        "name": "van",
        "kind": "car",
        "max_length": 350,
        "max_width": 150,
        "max_height": 180,
        "max_weight": 1000,
        "identifier": "van",
        "active": true
      }
    ],
    "suspended": false,
    DEPRECATED "vehicle_type": "van",
    DEPRECATED "vehicle_max_length": 350,
    DEPRECATED "vehicle_max_width": 150,
    DEPRECATED "vehicle_max_height": 180,
    DEPRECATED "vehicle_max_weight": 1000
  }

Update courier
PUT`/v1/couriers/{id}`

id parameter is uuid property of an courier.
You can obtain this value in response OBTAIN COURIERS

Attribute name	Type	Required	Description	Available types:
api_token	`string`	`X`	Authorization token
name	`string`		New courier name
email	`string`		New courier email
phone_number	`string`		New courier phone number
language_code	`string`		Language code which courier uses	en de fr ph pl
vehicle_type_identifier	`string`		Vehicle which courier uses	bike scooter cargobike car caddy van large_van
password	`string`		Password required for courier administaration panel. Must be at least 8 characters long
password_confirmation	`string`		Confirmation, must match `password` field

Example URI

PUT https://sandbox.tiramizoo.com/courier_company_api/v1/couriers/45feacc9-613b-428d-8a1b-82cfd18baa8d

URI Parameters

HideShow

id: string (required) Example: 45feacc9-613b-428d-8a1b-82cfd18baa8d
Courier identifier

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "api_token": "awv7yhhfkk",
  "id": "45feacc9-613b-428d-8a1b-82cfd18baa8d",
  "name": "New_courier_name",
  "email": "new@email.com",
  "phone_number": "4988877766",
  "language_code": "de",
  "vehicle_type_identifier": "bike",
  "password": "secret",
  "password_confirmation": "secret"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "api_token": {
      "type": "string",
      "description": "Authorization token"
    },
    "id": {
      "type": "string",
      "description": "Courier identifier"
    },
    "name": {
      "type": "string",
      "description": "New name for courier"
    },
    "email": {
      "type": "string",
      "description": "New email for courier"
    },
    "phone_number": {
      "type": "string",
      "description": "New phone number for courier"
    },
    "language_code": {
      "type": "string",
      "description": "Language code which courier uses"
    },
    "vehicle_type_identifier": {
      "type": "string",
      "enum": [
        "bike",
        "scooter",
        "cargobike",
        "car",
        "caddy",
        "van",
        "large_van"
      ],
      "description": "Vehicle which courier uses"
    },
    "password": {
      "type": "string",
      "description": "Password required for [courier administration panel](https://www.tiramizoo.com/courier/sign_in). Must be at least 8 characters long"
    },
    "password_confirmation": {
      "type": "string",
      "description": "Confirmation, must match `password` field"
    }
  },
  "required": [
    "api_token",
    "id"
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "uuid": "45feacc9-613b-428d-8a1b-82cfd18baa8d",
    "name": "New_courier_name",
    "email": "new@email.com",
    "phone_number": "4988877766",
    "language_code": "de",
    "available_vehicle_types": [
      {
        "name": "bike",
        "kind": "bike",
        "max_length": 50,
        "max_width": 30,
        "max_height": 30,
        "max_weight": 5,
        "identifier": "bike",
        "active": false
      },
      {
        "name": "van",
        "kind": "car",
        "max_length": 350,
        "max_width": 150,
        "max_height": 180,
        "max_weight": 1000,
        "identifier": "van",
        "active": true
      }
    ],
    "suspended": false,
    DEPRECATED "vehicle_type": "van",
    DEPRECATED "vehicle_max_length": 350,
    DEPRECATED "vehicle_max_width": 150,
    DEPRECATED "vehicle_max_height": 180,
    DEPRECATED "vehicle_max_weight": 1000
  }

Delete courier
DELETE`/v1/couriers/{id}{?api_token}`

id parameter is uuid courier property.
You can obtain this value from response OBTAIN COURIERS

Example URI

DELETE https://sandbox.tiramizoo.com/courier_company_api/v1/couriers/45feacc9-613b-428d-8a1b-82cfd18baa8d?api_token=awv7yhhfkk

URI Parameters

HideShow

id: string (required) Example: 45feacc9-613b-428d-8a1b-82cfd18baa8d
Courier identifier
api_token: string (required) Example: awv7yhhfkk
Authorization token

Request

HideShow

Headers

Content-Type: application/json

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": "true"
}

External Offers Management ¶

Notification offer request ¶

Notification offer requestPOST/offers_notification_api_url

Example URI

Headers

Body

Headers

Order notification ¶

Order notification requestPOST/orders_notification_api_url

Example URI

Headers

Body

Headers

Order notification updatePUT/orders_notification_api_url

Example URI

Headers

Body

Headers

Courier Offers ¶

Create or accept offer ¶

Create or accept offerPOST/v1/courier_offers

Example URI

Headers

Body

Schema

Headers

Body

Delete offer ¶

Delete offerDELETE/v1/courier_offers/{id}{?api_token}

Example URI

Headers

Headers

Body

Order Events ¶

Create event ¶

Create eventPOST/v1/order_events

Example URI

Headers

Body

Schema

Headers

Body

Orders ¶

Obtain courier company orders ¶

Obtain courier company ordersGET/v1/orders{?api_token,from,page,per_page}

Example URI

Headers

Headers

Body

Order ¶

Show orderGET/v1/orders/{id}{?api_token}

Example URI

Headers

Headers

Body

Headers

Headers

Body

Update orderPUT/v1/orders/{id}

Example URI

Headers

Body

Schema

Headers

Body

Headers

Body

Schema

Headers

Body

Headers

Couriers ¶

Obtain couriers ¶

Obtain couriersGET/v1/couriers{?api_token,page,per_page}

Example URI

Headers

Headers

Body

Add courier ¶

Add courierPOST/v1/couriers

Notification offer request
POST`/offers_notification_api_url`

Order notification request
POST`/orders_notification_api_url`

Order notification update
PUT`/orders_notification_api_url`

Create or accept offer
POST`/v1/courier_offers`

Delete offer
DELETE`/v1/courier_offers/{id}{?api_token}`

Create event
POST`/v1/order_events`

Obtain courier company orders
GET`/v1/orders{?api_token,from,page,per_page}`

Show order
GET`/v1/orders/{id}{?api_token}`

Update order
PUT`/v1/orders/{id}`

Obtain couriers
GET`/v1/couriers{?api_token,page,per_page}`

Add courier
POST`/v1/couriers`

Show courier
GET`/v1/couriers/{id}{?api_token}`

Update courier
PUT`/v1/couriers/{id}`

Delete courier
DELETE`/v1/couriers/{id}{?api_token}`