Back to top

Courier API

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

Activation

Check registration code

Check registration code
POST/v1/activation/check_registration_code

Allows to check if registration code is valid.

Attribute name Type Required Description
email string X Courier email
registration_code string X Registration code

Example URI

POST https://sandbox.tiramizoo.com/courier_api/v1/activation/check_registration_code
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "test@courier.com",
  "registration_code": "8r4g632dh7"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "registration_code": {
      "type": "string"
    }
  },
  "required": [
    "email",
    "registration_code"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json

Activate

Activate
POST/v1/activation/activate

Attribute name Type Required Description
email string X Courier email
registration_code string X Registration code
password string X Min 8 characters
password_confirmation string X

Example URI

POST https://sandbox.tiramizoo.com/courier_api/v1/activation/activate
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "test@courier.com",
  "registration_code": "8r4g632dh7",
  "password": "test1234",
  "password_confirmation": "test1234"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "registration_code": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "password_confirmation": {
      "type": "string"
    }
  },
  "required": [
    "email",
    "registration_code",
    "password",
    "password_confirmation"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json

Authorization

Authorization

Reset Auth Token
POST/v1/auth

Reset auth_token.

Set push_token. push_device, app_version.

Attribute name Type Required Description
email string X Courier email
password string X Courier password
At least 8 characters long
push_token string Courier push token
push_device string Courier device
app_version string App version in use

Example URI

POST https://sandbox.tiramizoo.com/courier_api/v1/auth
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "test_courier_1@tiramizoo.com",
  "password": "invisible",
  "push_token": "123432323456767678988765--kodfkdorhfudhrh",
  "push_device": "android",
  "app_version": "1.0.79"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Courier email"
    },
    "password": {
      "type": "string",
      "description": "Courier password. At least 8 characters long"
    },
    "push_token": {
      "type": "string",
      "description": "Courier push token"
    },
    "push_device": {
      "type": "string",
      "description": "Courier device"
    },
    "app_version": {
      "type": "string",
      "description": "App version in use"
    }
  },
  "required": [
    "email",
    "password"
  ]
}
Response  201
HideShow

Authorization is successful.
Use provided auth_token for further requests.

Headers
Content-Type: application/json
Body
{
  "auth_token": "5c187650a94db91a8a505a367f036153",
  "push_token": "123432323456767678988765--kodfkdorhfudhrh",
  "name": "Jannette Farrell",
  "timezone": "Europe/Berlin",
  "force_hqp": false,
  "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
    }
  ],
  "profile_picture_url": "http://test.host/assets/avatar_placeholder-6d0b56cc361ac9f40d85e229feb7685b9b51554b3e159acd21b05876f7a693b7.png",
  "home_address": null,
  "home_address_lat": null,
  "home_address_lng": null,
  "packages_by_tour_access": false
}
Response  401
HideShow

Credentials are invalid.
Please check email and password.

Update Device Push Token
PUT/v1/auth

Protected resource.
Authorization required via auth_token.

Attribute name Type Required Description
auth_token string X Current courier auth token
push_token string X Courier new push token

Example URI

PUT https://sandbox.tiramizoo.com/courier_api/v1/auth
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "bf545b8e453536ee431648d86711243b",
  "push_token": "fd208a7e27f440968b1d08a3f1800600"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "auth_token": {
      "type": "string",
      "description": "Current Auth Token"
    },
    "push_token": {
      "type": "string",
      "description": "New Push Token"
    }
  },
  "required": [
    "auth_token",
    "push_token"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "eefe9990e70a9553b02492dbddeb86ae",
  "push_token": "new_generated_push_token_jiafdsfh",
  "name": "Nikita Schuster",
  "timezone": "Europe/Berlin",
  "force_hqp": false,
  "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
    }
  ],
  "profile_picture_url": "http://test.host/assets/avatar_placeholder-6d0b56cc361ac9f40d85e229feb7685b9b51554b3e159acd21b05876f7a693b7.png",
  "home_address": null,
  "home_address_lat": null,
  "home_address_lng": null,
  "packages_by_tour_access": false
}
Response  401
HideShow

Provided auth_token is invalid.

Reset Tokens
DELETE/v1/auth

Protected resource.
Authorization required via auth_token.

Clear auth_token, push_token, push_device

Attribute name Type Required Description
auth_token string X Authentication token

Example URI

DELETE https://sandbox.tiramizoo.com/courier_api/v1/auth
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "bf545b8e453536ee431648d86711243b"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "auth_token": {
      "type": "string",
      "description": "Authentication token"
    }
  },
  "required": [
    "auth_token"
  ]
}
Response  200
HideShow

auth_token, push_token, push_device have been cleared.

Headers
Content-Type: application/json
Response  401
HideShow

Provided auth_token is invalid.

Reset password
POST/v1/auth/password_reset

Resetting password instruction will be sent to given email.

Attribute name Type Required Description
email string X Courier email

Example URI

POST https://sandbox.tiramizoo.com/courier_api/v1/auth/password_reset
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "email": "test@courier.com"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    }
  },
  "required": [
    "email"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json

Switch organization

Switch organization
POST/v1/auth/switch_organization

Protected resource.
Authorization required via auth_token.

Log in to another courier account which has been linked to the current courier in another organization.

Attribute name Type Required Description
auth_token string X Authentication token
organization_id string ID of an organization (deprecated)
organization_identifier string X identifier of an organization

Example URI

POST https://sandbox.tiramizoo.com/courier_api/v1/auth/switch_organization
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "bf545b8e453536ee431648d86711243b",
  "organization_identifier": "tiramizoo"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "auth_token": {
      "type": "string",
      "description": "Current Auth Token"
    },
    "organization_identifier": {
      "type": "string",
      "description": "Organization identifier to switch to"
    }
  },
  "required": [
    "auth_token",
    "organization_identifier"
  ]
}
Response  201
HideShow

Switching the organization is successful.
Use provided auth_token and current_organization.host for further requests.

Headers
Content-Type: application/json
Body
{
  "auth_token": "5c187650a94db91a8a505a367f036153",
  "push_token": "123432323456767678988765--kodfkdorhfudhrh",
  "name": "Jannette Farrell",
  "timezone": "Europe/Berlin",
  "force_hqp": false,
  "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
    }
  ],
  "profile_picture_url": "http://test.host/assets/avatar_placeholder-6d0b56cc361ac9f40d85e229feb7685b9b51554b3e159acd21b05876f7a693b7.png",
  "home_address": null,
  "home_address_lat": null,
  "home_address_lng": null,
  "packages_by_tour_access": false
}
Response  401
HideShow

Provided auth_token is invalid.

Response  404
HideShow

Organization to switch to has not been found.

Couriers

Protected resource.
Authorization required via auth_token.

Update courier

Update courier
PUT/v1/courier

Attribute name Type Required Description Available types:
auth_token string X Authentication token
vehicle_type_identifier string Vehicle type
  • bike
  • scooter
  • cargobike
  • car
  • caddy
  • van
  • large_van
time_zone string Courier time zone
  • Europe/Berlin
  • Europe/London
  • Asia/Manila
profile_picture_data_uri string Image (png, jpg, jpeg, gif).
Encoded using Data URI scheme.
File max size 5 MB
remove_profile_picture boolean Set this field to true to delete profile picture
home_address string Must be provided along with lat, lng
home_address_lat number
home_address_lng number

Example URI

PUT https://sandbox.tiramizoo.com/courier_api/v1/courier
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "bf545b8e453536ee431648d86711243b",
  "vehicle_type": "bike",
  "timezone": "Europe/Berlin",
  "profile_picture_data_uri": "data:image/png;base64,TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5",
  "remove_profile_picture": false,
  "home_address": "Wilhelm-Hale-Str. 50, 80639 Munich, Germany",
  "home_address_lat": 48.14903,
  "home_address_lng": 11.54085
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "auth_token": {
      "type": "string",
      "description": "authentication token"
    },
    "vehicle_type": {
      "type": "string",
      "enum": [
        "bike",
        "scooter",
        "cargobike",
        "car",
        "caddy",
        "van",
        "large_van"
      ],
      "description": "Vehicle type. Available types are:"
    },
    "timezone": {
      "type": "string",
      "enum": [
        "Europe/Berlin",
        "Europe/London",
        "Asia/Manila"
      ],
      "description": "Time zone in which courier works. Supported time zones are:"
    },
    "profile_picture_data_uri": {
      "type": "string",
      "description": "Image encoded using Data URI scheme. Supported formats: jpg, png, jpeg, gif. File max size 5 MB"
    },
    "remove_profile_picture": {
      "type": "boolean",
      "description": "Allows to delete profile picture"
    },
    "home_address": {
      "type": "string"
    },
    "home_address_lat": {
      "type": "number"
    },
    "home_address_lng": {
      "type": "number"
    }
  },
  "required": [
    "auth_token"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "fb560839122d0754408a0efd5a85b61c",
  "push_token": null,
  "name": "Nida Hartmann",
  "timezone": "Asia/Manila",
  "force_hqp": false,
  "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
    }
  ],
  "profile_picture_url": "http://test.host/assets/avatar_placeholder-6d0b56cc361ac9f40d85e229feb7685b9b51554b3e159acd21b05876f7a693b7.png",
  "home_address": null,
  "home_address_lat": null,
  "home_address_lng": null,
  "packages_by_tour_access": false
}

Tours

Manage courier’s tours

Protected resources.
Authorization required via auth_token.

Obtain all recent courier stops grouped into tours

Obtain all recent courier stops grouped into tours
GET/v1/tours{?auth_token}

There are 3 types of a tour - tour, adhoc, and placeholder.

  • tour depicts a real tour that was calculated by the system. It contains list of stops ordered in an optimized manner. A map can - and should - be drawn out of consecutive_stops_locations.

  • adhoc is a list of point-2-point deliveries, each stop in this group represents a separate “tour”, which means that the map generated out of consecutive_stops_locations doesn’t make much sense, because each stop can be from a different day. That’s why the time_window comes empty as well.

  • placeholder represents a tour that MIGHT happen for the courier, because the courier told us they will be available if we needed them. time_window is broad to indicate when the courier might be occupied, stops and consecutive_stops_locations come in empty - it is a placeholder after all.

Example URI

GET https://sandbox.tiramizoo.com/courier_api/v1/tours?auth_token=bf545b8e453536ee431648d86711243b
URI Parameters
HideShow
auth_token
string (required) Example: bf545b8e453536ee431648d86711243b

Authentication token

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "stops": [
      {
        "uuid": "a6907b3a-d211-4f86-8ed4-252c14fcecf5",
        "address_line": "34516 Howell Junction",
        "postal_code": "33251-0466",
        "city": "Abbottfurt",
        "starts_at": "2012-04-16T08:05:00+02:00",
        "ends_at": "2012-04-16T08:10:00+02:00",
        "name": "Kuhn-Koch",
        "lat": 10.2511,
        "lng": 43.998,
        "require_signature": false,
        "pickups_require_signature": false,
        "pickups_require_photo_proof": false,
        "require_real_service_time": true,
        "require_tail_lift": false,
        "complete": false,
        "change": null,
        "change_details": null,
        "report_only_in_time_window": true,
        "applicable_events": [
          {
            "type": "failed_due_to_business_closed",
            "jobs": [
              {
                "uuid": "37edc2e7-476b-4488-9e16-636e54ebcb2d",
                "photo_proof": false,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": true,
            "creates_return_stop": true
          },
          {
            "type": "address_not_found",
            "jobs": [
              {
                "uuid": "37edc2e7-476b-4488-9e16-636e54ebcb2d",
                "photo_proof": false,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": true,
            "creates_return_stop": true
          },
          {
            "type": "name_not_found_on_doorbell",
            "jobs": [
              {
                "uuid": "37edc2e7-476b-4488-9e16-636e54ebcb2d",
                "photo_proof": true,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": true,
            "creates_return_stop": true
          },
          {
            "type": "no_attempt_due_to_being_late",
            "jobs": [
              {
                "uuid": "37edc2e7-476b-4488-9e16-636e54ebcb2d",
                "photo_proof": false,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": true,
            "creates_return_stop": true
          },
          {
            "type": "wrong_package_size",
            "jobs": [
              {
                "uuid": "37edc2e7-476b-4488-9e16-636e54ebcb2d",
                "photo_proof": true,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": false,
            "creates_return_stop": true
          },
          {
            "type": "package_was_not_ready",
            "jobs": [
              {
                "uuid": "37edc2e7-476b-4488-9e16-636e54ebcb2d",
                "photo_proof": false,
                "sign": true
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": false,
            "creates_return_stop": true
          },
          {
            "type": "sender_wants_to_cancel",
            "jobs": [
              {
                "uuid": "37edc2e7-476b-4488-9e16-636e54ebcb2d",
                "photo_proof": false,
                "sign": true
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": false,
            "creates_return_stop": true
          },
          {
            "type": "sender_was_not_at_home",
            "jobs": [
              {
                "uuid": "37edc2e7-476b-4488-9e16-636e54ebcb2d",
                "photo_proof": false,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": true,
            "creates_return_stop": true
          }
        ],
        "service_time": 5,
        "done": false,
        "time_window": "08:05 - 08:10 16.04.2012",
        "jobs": [
          {
            "uuid": "37edc2e7-476b-4488-9e16-636e54ebcb2d",
            "require_signature": false,
            "require_real_service_time": true,
            "state": "created",
            "require_tail_lift": false,
            "type": "pickup",
            "packages": [
              {
                "identifier": "20596FBCBDD7F53E",
                "description": "A fish",
                "length": 30,
                "weight": 5,
                "height": 20,
                "width": 10,
                "size": "L",
                "order_identifier": "W6I2FS",
                "non_rotatable": false,
                "fragile_goods": false,
                "protect_from_water": false,
                "external_id": null,
                "state": "pending",
                "actions": [
                  "hand_over",
                  "not_hand_over"
                ]
              },
              {
                "identifier": "A56B4971EE81932E",
                "description": "A fish",
                "length": 30,
                "weight": 5,
                "height": 20,
                "width": 10,
                "size": "L",
                "order_identifier": "W6I2FS",
                "non_rotatable": false,
                "fragile_goods": false,
                "protect_from_water": false,
                "external_id": null,
                "state": "pending",
                "actions": [
                  "hand_over",
                  "not_hand_over"
                ]
              }
            ],
            "order_identifier": "W6I2FS",
            "external_order_id": "KMY2XL",
            "courier_information": "go go go; now now now",
            "hazard_index": 0,
            "distance": 2,
            "events": [],
            "pickup": {
              "name": "I.P. Freely",
              "address_line": "Im Dol 2",
              "postal_code": "14195",
              "city": "Berlin",
              "phone_number": "30049223333",
              "after": "2012-04-16T07:00:00+02:00",
              "before": "2012-04-16T07:30:00+02:00",
              "information": "go go go",
              "requirements": [
                {
                  "type": "custom",
                  "value": "ensure boxes are well packed!",
                  "message": "ensure boxes are well packed!"
                },
                {
                  "type": "security_code",
                  "value": "123XSDF",
                  "message": "Authenticate with security code: 123XSDF"
                }
              ],
              "can_cancel_package_pickup": true,
              "allow_partial_pick_up": true
            },
            "delivery": {
              "name": "Mike Rotch",
              "address_line": "Im Dol 48",
              "postal_code": "14195",
              "city": "Berlin",
              "phone_number": "30049224444",
              "after": "2012-04-16T08:50:00+02:00",
              "before": "2012-04-16T09:00:00+02:00",
              "information": "now now now",
              "requirements": [
                {
                  "type": "age",
                  "value": 21,
                  "message": "Verify recipient age to be at least 21 years old"
                }
              ],
              "allow_partial_delivery": false
            },
            "return": {
              "service_times": {
                "1": 6
              },
              "location_service_time": 0,
              "additional_service_time": 0
            }
          },
          {
            "uuid": "eeb37d8f-d2ad-483d-8c7d-27dd2a510e2c",
            "require_signature": false,
            "require_real_service_time": false,
            "state": "created",
            "require_tail_lift": false,
            "type": "custom"
          }
        ],
        "available_additional_service_time_reasons": [
          {
            "type": "goods_could_not_be_found",
            "job_uuids": [
              "37edc2e7-476b-4488-9e16-636e54ebcb2d"
            ]
          },
          {
            "type": "handover_took_longer_as_planned",
            "job_uuids": [
              "37edc2e7-476b-4488-9e16-636e54ebcb2d"
            ]
          },
          {
            "type": "place_was_not_specified_correctly",
            "job_uuids": [
              "37edc2e7-476b-4488-9e16-636e54ebcb2d"
            ]
          },
          {
            "type": "contact_was_not_available",
            "job_uuids": [
              "37edc2e7-476b-4488-9e16-636e54ebcb2d"
            ]
          },
          {
            "type": "contact_was_busy",
            "job_uuids": [
              "37edc2e7-476b-4488-9e16-636e54ebcb2d"
            ]
          },
          {
            "type": "courier_was_ignored",
            "job_uuids": [
              "37edc2e7-476b-4488-9e16-636e54ebcb2d"
            ]
          }
        ],
        "service_time_options": [
          5,
          10,
          15,
          20,
          30,
          45,
          60,
          90,
          120
        ],
        "can_not_be_served_before": "2012-04-16T07:00:00+02:00",
        "available_delivered_to_options": [
          "recipient",
          "neighbour",
          "housemate",
          "safe_place"
        ],
        "safe_place_options": [
          "at_the_apartments_door",
          "on_the_doorstep",
          "mailbox",
          "garage",
          "other"
        ],
        "delivered_to_options_with_required_signature": [
          "housemate",
          "neighbour",
          "recipient"
        ],
        "delivered_to_options_with_required_photo_proof": [],
        "applicable_delivered_to_options": {
          "recipient": {
            "photo_proof": false,
            "signature": true
          },
          "neighbour": {
            "photo_proof": false,
            "signature": true
          },
          "housemate": {
            "photo_proof": false,
            "signature": true
          },
          "safe_place": {
            "at_the_apartments_door": {
              "photo_proof": false,
              "signature": false
            },
            "on_the_doorstep": {
              "photo_proof": false,
              "signature": false
            },
            "mailbox": {
              "photo_proof": false,
              "signature": false
            },
            "garage": {
              "photo_proof": false,
              "signature": false
            },
            "other": {
              "photo_proof": false,
              "signature": false
            }
          }
        },
        "mandatory_delivered_to_process": false,
        "allow_one_click_selection": false,
        "information": null
      },
      {
        "uuid": "49100a11-77fc-4781-96ff-edf455a7f572",
        "address_line": "5209 Darci Shoal",
        "postal_code": "87164",
        "city": "Stoltenbergland",
        "starts_at": "2012-04-16T11:29:00+02:00",
        "ends_at": "2012-04-16T11:34:00+02:00",
        "name": "Barton Inc",
        "lat": 10.2511,
        "lng": 43.998,
        "require_signature": false,
        "pickups_require_signature": false,
        "pickups_require_photo_proof": false,
        "require_real_service_time": true,
        "require_tail_lift": false,
        "complete": false,
        "change": null,
        "change_details": null,
        "report_only_in_time_window": true,
        "applicable_events": [
          {
            "type": "recipient_was_not_at_home",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": false,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": true,
            "creates_return_stop": true
          },
          {
            "type": "failed_due_to_business_closed",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": false,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": true,
            "creates_return_stop": true
          },
          {
            "type": "address_not_found",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": false,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": true,
            "creates_return_stop": true
          },
          {
            "type": "name_not_found_on_doorbell",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": true,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": true,
            "creates_return_stop": true
          },
          {
            "type": "no_attempt_due_to_being_late",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": false,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": true,
            "creates_return_stop": true
          },
          {
            "type": "package_was_not_accepted",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": false,
                "sign": true
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": false,
            "creates_return_stop": true
          },
          {
            "type": "no_access_to_building",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": false,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": false,
            "creates_return_stop": true
          },
          {
            "type": "abort_delivery",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": false,
                "sign": false
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": false,
            "creates_return_stop": true
          },
          {
            "type": "package_was_not_ordered",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": false,
                "sign": true
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": false,
            "creates_return_stop": true
          },
          {
            "type": "package_is_damaged",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": false,
                "sign": true
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": false,
            "creates_return_stop": true
          },
          {
            "type": "not_enough_money_for_payment",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": false,
                "sign": true
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": false,
            "creates_return_stop": true
          },
          {
            "type": "package_was_delivered_too_late",
            "jobs": [
              {
                "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
                "photo_proof": false,
                "sign": true
              }
            ],
            "retry": false,
            "retry_count": 0,
            "common": false,
            "creates_return_stop": true
          }
        ],
        "service_time": 5,
        "done": false,
        "time_window": "11:29 - 11:34 16.04.2012",
        "jobs": [
          {
            "uuid": "9ddc713e-4aef-4f42-8c7c-392b2abec50b",
            "require_signature": false,
            "require_real_service_time": true,
            "state": "created",
            "require_tail_lift": false,
            "type": "delivery",
            "packages": [
              {
                "identifier": "20596FBCBDD7F53E",
                "description": "A fish",
                "length": 30,
                "weight": 5,
                "height": 20,
                "width": 10,
                "size": "L",
                "order_identifier": "W6I2FS",
                "non_rotatable": false,
                "fragile_goods": false,
                "protect_from_water": false,
                "external_id": null,
                "state": "pending",
                "actions": []
              },
              {
                "identifier": "A56B4971EE81932E",
                "description": "A fish",
                "length": 30,
                "weight": 5,
                "height": 20,
                "width": 10,
                "size": "L",
                "order_identifier": "W6I2FS",
                "non_rotatable": false,
                "fragile_goods": false,
                "protect_from_water": false,
                "external_id": null,
                "state": "pending",
                "actions": []
              }
            ],
            "order_identifier": "W6I2FS",
            "external_order_id": "KMY2XL",
            "courier_information": "go go go; now now now",
            "hazard_index": 0,
            "distance": 2,
            "events": [],
            "pickup": {
              "name": "I.P. Freely",
              "address_line": "Im Dol 2",
              "postal_code": "14195",
              "city": "Berlin",
              "phone_number": "30049223333",
              "after": "2012-04-16T07:00:00+02:00",
              "before": "2012-04-16T07:30:00+02:00",
              "information": "go go go",
              "requirements": [
                {
                  "type": "custom",
                  "value": "ensure boxes are well packed!",
                  "message": "ensure boxes are well packed!"
                },
                {
                  "type": "security_code",
                  "value": "123XSDF",
                  "message": "Authenticate with security code: 123XSDF"
                }
              ],
              "can_cancel_package_pickup": true,
              "allow_partial_pick_up": true
            },
            "delivery": {
              "name": "Mike Rotch",
              "address_line": "Im Dol 48",
              "postal_code": "14195",
              "city": "Berlin",
              "phone_number": "30049224444",
              "after": "2012-04-16T08:50:00+02:00",
              "before": "2012-04-16T09:00:00+02:00",
              "information": "now now now",
              "requirements": [
                {
                  "type": "age",
                  "value": 21,
                  "message": "Verify recipient age to be at least 21 years old"
                }
              ],
              "allow_partial_delivery": false
            },
            "return": {
              "service_times": {
                "1": 6
              },
              "location_service_time": 0,
              "additional_service_time": 0
            }
          }
        ],
        "available_additional_service_time_reasons": [
          {
            "type": "contact_could_not_be_found",
            "job_uuids": [
              "9ddc713e-4aef-4f42-8c7c-392b2abec50b"
            ]
          },
          {
            "type": "unloading_longer_than_expected_due_bulky_goods",
            "job_uuids": [
              "9ddc713e-4aef-4f42-8c7c-392b2abec50b"
            ]
          },
          {
            "type": "recipient_was_contacted_by_phone",
            "job_uuids": [
              "9ddc713e-4aef-4f42-8c7c-392b2abec50b"
            ]
          },
          {
            "type": "hotline_had_to_be_contacted_for_clarification",
            "job_uuids": [
              "9ddc713e-4aef-4f42-8c7c-392b2abec50b"
            ]
          }
        ],
        "service_time_options": [
          5,
          10,
          15,
          20,
          30,
          45,
          60,
          90,
          120
        ],
        "can_not_be_served_before": null,
        "available_delivered_to_options": [
          "recipient",
          "neighbour",
          "housemate",
          "safe_place"
        ],
        "safe_place_options": [
          "at_the_apartments_door",
          "on_the_doorstep",
          "mailbox",
          "garage",
          "other"
        ],
        "delivered_to_options_with_required_signature": [
          "housemate",
          "neighbour",
          "recipient"
        ],
        "delivered_to_options_with_required_photo_proof": [],
        "applicable_delivered_to_options": {
          "recipient": {
            "photo_proof": false,
            "signature": true
          },
          "neighbour": {
            "photo_proof": false,
            "signature": true
          },
          "housemate": {
            "photo_proof": false,
            "signature": true
          },
          "safe_place": {
            "at_the_apartments_door": {
              "photo_proof": false,
              "signature": false
            },
            "on_the_doorstep": {
              "photo_proof": false,
              "signature": false
            },
            "mailbox": {
              "photo_proof": false,
              "signature": false
            },
            "garage": {
              "photo_proof": false,
              "signature": false
            },
            "other": {
              "photo_proof": false,
              "signature": false
            }
          }
        },
        "mandatory_delivered_to_process": false,
        "allow_one_click_selection": false,
        "information": null
      }
    ],
    "type": "adhoc",
    "consecutive_stops_locations": [
      [
        10.2511,
        43.998
      ],
      [
        10.2511,
        43.998
      ]
    ],
    "name": "On demand stops",
    "time_window": "08:05 - 11:34 16.04.2012",
    "distance": null,
    "duration": "3h 29min",
    "position": null,
    "total_stops_count": 2,
    "done_stops_count": 0,
    "identifier": null,
    "starts_at": "2012-04-16T08:05:00+02:00",
    "ends_at": "2012-04-16T11:34:00+02:00"
  }
]

Stops

Manage stops in scope of tour

Protected resources.
Authorization required via auth_token.

Update stop

Update stop
PUT/v1/stops/{uuid}

Attribute name Type Required Description Available types:
auth_token string X Authentication token
jobs: array X Jobs list on given stop
uuid string X Job uuid
id number Job id (deprecated)
done boolean X Job done/undone
packages: array X
identifier string X Package identifier
pickup_state string X State to which the package is being transitioned.
  • picked_up
  • not_picked_up
  • pending
external_id string Mandatory in case order pickup requirements
include scanning of external label.
Must meet the value scanning requirements		 External label package identifier
recorded_at string X Date time of courier's action
delivered_to string X Specify to whom was order delivered
  • neighbour
  • recipient
  • housemate
  • safe_place
delivered_to_extra_info string Specify to which safe place order was delivered
photo_proof: object Mandatory in case delivered_to
is listed in delivered_to_options_with_required_photo_proof 		Photo proof
note string Explanation message
data_uris array Array of images encoded using Data URI scheme.
Allowed image types: png, jpg, jpeg, gif.
File max size 700 kb.
signature: object Mandatory in case job require signature Signature
name string Recipient / sender name
data_uri string Image (png, jpg, jpeg, gif).
Encoded using Data URI scheme.
File max size 100 kb.
service_time number X Service time
additional_service_time_reason string Mandatory in case service_time is greater
than service time included.
Service time included means
service_time attribute from response v1/stops 		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
On return:
  • courier_was_ignored
  • reception_was_refused
  • receiving_department_was_busy

Example URI

PUT https://sandbox.tiramizoo.com/courier_api/v1/stops/67a58538-a5ce-4de7-9a57-825487a9ba63
URI Parameters
HideShow
uuid
string (required) Example: 67a58538-a5ce-4de7-9a57-825487a9ba63

Stop uuid

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "bf545b8e453536ee431648d86711243b",
  "jobs": [
    {
      "uuid": "1d16702c-19ab-4b37-9293-3fe24cfd03e4",
      "done": true,
      "packages": [
        {
          "identifier": "FCB8349CA1858BBA",
          "external_id": "ABCD"
        }
      ]
    }
  ],
  "recorded_at": "2012-04-16 09:05",
  "delivered_to: safe_place": "neighbour",
  "delivered_to_extra_info: when delivered to safe_place, it should contain which specific place it was": "Hello, world!",
  "signature": {
    "name": "Otto Normalverbraucher",
    "data_uri": "TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5"
  },
  "service_time": 10,
  "photo_proof": {
    "note": "Next to big tree",
    "data_uris": [
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkBAMAAACC...REfRXH4tWFZGswQ2yAAAAAElFTkSuQmCC"
    ]
  },
  "additional_service_time_reason": "goods_could_not_be_found"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "auth_token": {
      "type": "string",
      "description": "Authentication token"
    },
    "jobs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "description": "Job uuid"
          },
          "done": {
            "type": "boolean",
            "description": "Job done/undone"
          },
          "packages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "identifier": {
                  "type": "string",
                  "description": "Identifier of package"
                },
                "external_id": {
                  "type": "string",
                  "description": "External label package identifier"
                }
              },
              "required": [
                "identifier"
              ]
            },
            "description": "Mandatory on pickup"
          }
        },
        "required": [
          "uuid",
          "done",
          "packages"
        ]
      },
      "description": "Jobs list on given stop"
    },
    "recorded_at": {
      "type": "string",
      "description": "Date time of courier's action"
    },
    "delivered_to: safe_place": {
      "type": "string",
      "enum": [
        "neighbour",
        "recipient",
        "housemate",
        "safe_place"
      ],
      "description": "To whom was order delivered"
    },
    "delivered_to_extra_info: when delivered to safe_place, it should contain which specific place it was": {
      "type": "string"
    },
    "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 (required if job require signature)"
    },
    "service_time": {
      "type": "number",
      "description": "Service time"
    },
    "photo_proof": {
      "type": "object",
      "properties": {
        "note": {
          "type": "string",
          "description": "Explanation message"
        },
        "data_uris": {
          "type": "array",
          "description": "Images array encoded using Data URI scheme."
        }
      },
      "description": "Photo_proof (required if type has `photo_proof = true`)"
    },
    "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 `service_time` is greater than service time included.Service time included means service time from response GET v1/stops."
    }
  },
  "required": [
    "auth_token",
    "recorded_at",
    "service_time"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "uuid": "1f89e365-a040-4c6f-82e6-fbf230650493",
  "address_line": "59051 Laticia Club",
  "postal_code": "64421",
  "city": "New Leontine",
  "starts_at": "2012-04-16T08:05:00+02:00",
  "ends_at": "2012-04-16T08:10:00+02:00",
  "name": "Senger and Sons",
  "lat": 10.2511,
  "lng": 43.998,
  "require_signature": false,
  "pickups_require_signature": false,
  "pickups_require_photo_proof": false,
  "require_real_service_time": true,
  "require_tail_lift": false,
  "complete": false,
  "change": null,
  "change_details": null,
  "report_only_in_time_window": true,
  "applicable_events": [],
  "service_time": 5,
  "done": false,
  "time_window": "08:05 - 08:10 16.04.2012",
  "jobs": [
    {
      "uuid": "4a0c5e70-3bff-4698-9188-8dadb6a5486c",
      "require_signature": false,
      "require_real_service_time": true,
      "state": "success",
      "require_tail_lift": false,
      "type": "delivery",
      "packages": [
        {
          "identifier": "9D860544838B8E10",
          "description": "A fish",
          "length": 30,
          "weight": 5,
          "height": 20,
          "width": 10,
          "size": "L",
          "order_identifier": "MZ2PHU",
          "non_rotatable": false,
          "fragile_goods": false,
          "protect_from_water": false,
          "external_id": null,
          "state": "delivered",
          "actions": []
        },
        {
          "identifier": "5A3E058E4BB22080",
          "description": "A fish",
          "length": 30,
          "weight": 5,
          "height": 20,
          "width": 10,
          "size": "L",
          "order_identifier": "MZ2PHU",
          "non_rotatable": false,
          "fragile_goods": false,
          "protect_from_water": false,
          "external_id": null,
          "state": "delivered",
          "actions": []
        }
      ],
      "order_identifier": "MZ2PHU",
      "external_order_id": "XQ73FM",
      "courier_information": "go go go; now now now",
      "hazard_index": 0,
      "distance": 2,
      "events": [],
      "pickup": {
        "name": "I.P. Freely",
        "address_line": "Im Dol 2",
        "postal_code": "14195",
        "city": "Berlin",
        "phone_number": "30049223333",
        "after": "2012-04-16T08:10:00+02:00",
        "before": "2012-04-16T08:20:00+02:00",
        "information": "go go go",
        "requirements": [],
        "can_cancel_package_pickup": false,
        "allow_partial_pick_up": false
      },
      "delivery": {
        "name": "Mike Rotch",
        "address_line": "Im Dol 48",
        "postal_code": "14195",
        "city": "Berlin",
        "phone_number": "30049224444",
        "after": "2012-04-16T08:10:00+02:00",
        "before": "2012-04-16T08:20:00+02:00",
        "information": "now now now",
        "requirements": [],
        "allow_partial_delivery": false
      },
      "return": {
        "service_times": {
          "1": 6
        },
        "location_service_time": 0,
        "additional_service_time": 0
      }
    },
    {
      "uuid": "34524505-ff8d-4b95-95d3-6d38a478b57f",
      "require_signature": false,
      "require_real_service_time": false,
      "state": "created",
      "require_tail_lift": false,
      "type": "custom"
    }
  ],
  "available_additional_service_time_reasons": [],
  "service_time_options": [
    5,
    10,
    15,
    20,
    30,
    45,
    60,
    90,
    120
  ],
  "can_not_be_served_before": null,
  "available_delivered_to_options": [
    "recipient",
    "neighbour",
    "housemate",
    "safe_place"
  ],
  "safe_place_options": [
    "at_the_apartments_door",
    "on_the_doorstep",
    "mailbox",
    "garage",
    "other"
  ],
  "delivered_to_options_with_required_signature": [
    "housemate",
    "neighbour",
    "recipient"
  ],
  "delivered_to_options_with_required_photo_proof": [],
  "applicable_delivered_to_options": {
    "recipient": {
      "photo_proof": false,
      "signature": true
    },
    "neighbour": {
      "photo_proof": false,
      "signature": true
    },
    "housemate": {
      "photo_proof": false,
      "signature": true
    },
    "safe_place": {
      "at_the_apartments_door": {
        "photo_proof": false,
        "signature": false
      },
      "on_the_doorstep": {
        "photo_proof": false,
        "signature": false
      },
      "mailbox": {
        "photo_proof": false,
        "signature": false
      },
      "garage": {
        "photo_proof": false,
        "signature": false
      },
      "other": {
        "photo_proof": false,
        "signature": false
      }
    }
  },
  "mandatory_delivered_to_process": false,
  "allow_one_click_selection": false,
  "information": null
}
Response  422
HideShow
Signature params are missing Stop can not be completed. Make sure that the pickup is marked correctly.
Returned if job require signature Returned if delivery new state is incorrect
Headers
Content-Type: application/json
Body
{
  "uuid": "1f89e365-a040-4c6f-82e6-fbf230650493",
  "address_line": "59051 Laticia Club",
  "postal_code": "64421",
  "city": "New Leontine",
  "starts_at": "2012-04-16T08:05:00+02:00",
  "ends_at": "2012-04-16T08:10:00+02:00",
  "name": "Senger and Sons",
  "lat": 10.2511,
  "lng": 43.998,
  "require_signature": false,
  "pickups_require_signature": false,
  "pickups_require_photo_proof": false,
  "require_real_service_time": true,
  "require_tail_lift": false,
  "complete": false,
  "change": null,
  "change_details": null,
  "report_only_in_time_window": true,
  "applicable_events": [],
  "service_time": 5,
  "done": false,
  "time_window": "08:05 - 08:10 16.04.2012",
  "jobs": [
    {
      "uuid": "4a0c5e70-3bff-4698-9188-8dadb6a5486c",
      "require_signature": false,
      "require_real_service_time": true,
      "state": "success",
      "require_tail_lift": false,
      "type": "delivery",
      "packages": [
        {
          "identifier": "9D860544838B8E10",
          "description": "A fish",
          "length": 30,
          "weight": 5,
          "height": 20,
          "width": 10,
          "size": "L",
          "order_identifier": "MZ2PHU",
          "non_rotatable": false,
          "fragile_goods": false,
          "protect_from_water": false,
          "external_id": null,
          "state": "delivered",
          "actions": []
        },
        {
          "identifier": "5A3E058E4BB22080",
          "description": "A fish",
          "length": 30,
          "weight": 5,
          "height": 20,
          "width": 10,
          "size": "L",
          "order_identifier": "MZ2PHU",
          "non_rotatable": false,
          "fragile_goods": false,
          "protect_from_water": false,
          "external_id": null,
          "state": "delivered",
          "actions": []
        }
      ],
      "order_identifier": "MZ2PHU",
      "external_order_id": "XQ73FM",
      "courier_information": "go go go; now now now",
      "hazard_index": 0,
      "distance": 2,
      "events": [],
      "pickup": {
        "name": "I.P. Freely",
        "address_line": "Im Dol 2",
        "postal_code": "14195",
        "city": "Berlin",
        "phone_number": "30049223333",
        "after": "2012-04-16T08:10:00+02:00",
        "before": "2012-04-16T08:20:00+02:00",
        "information": "go go go",
        "requirements": [],
        "can_cancel_package_pickup": false,
        "allow_partial_pick_up": false
      },
      "delivery": {
        "name": "Mike Rotch",
        "address_line": "Im Dol 48",
        "postal_code": "14195",
        "city": "Berlin",
        "phone_number": "30049224444",
        "after": "2012-04-16T08:10:00+02:00",
        "before": "2012-04-16T08:20:00+02:00",
        "information": "now now now",
        "requirements": [],
        "allow_partial_delivery": false
      },
      "return": {
        "service_times": {
          "1": 6
        },
        "location_service_time": 0,
        "additional_service_time": 0
      }
    },
    {
      "uuid": "34524505-ff8d-4b95-95d3-6d38a478b57f",
      "require_signature": false,
      "require_real_service_time": false,
      "state": "created",
      "require_tail_lift": false,
      "type": "custom"
    }
  ],
  "available_additional_service_time_reasons": [],
  "service_time_options": [
    5,
    10,
    15,
    20,
    30,
    45,
    60,
    90,
    120
  ],
  "can_not_be_served_before": null,
  "available_delivered_to_options": [
    "recipient",
    "neighbour",
    "housemate",
    "safe_place"
  ],
  "safe_place_options": [
    "at_the_apartments_door",
    "on_the_doorstep",
    "mailbox",
    "garage",
    "other"
  ],
  "delivered_to_options_with_required_signature": [
    "housemate",
    "neighbour",
    "recipient"
  ],
  "delivered_to_options_with_required_photo_proof": [],
  "applicable_delivered_to_options": {
    "recipient": {
      "photo_proof": false,
      "signature": true
    },
    "neighbour": {
      "photo_proof": false,
      "signature": true
    },
    "housemate": {
      "photo_proof": false,
      "signature": true
    },
    "safe_place": {
      "at_the_apartments_door": {
        "photo_proof": false,
        "signature": false
      },
      "on_the_doorstep": {
        "photo_proof": false,
        "signature": false
      },
      "mailbox": {
        "photo_proof": false,
        "signature": false
      },
      "garage": {
        "photo_proof": false,
        "signature": false
      },
      "other": {
        "photo_proof": false,
        "signature": false
      }
    }
  },
  "mandatory_delivered_to_process": false,
  "allow_one_click_selection": false,
  "information": null
}

Return Stop

Deliver packages to return stop.

Protected resources.
Authorization required via auth_token.

Deliver packages to return stop

Deliver packages to return stop
PUT/v1/return_stop

Attribute name Type Required Description Available types:
auth_token string X Authentication token
packages: array X
identifier string X Package identifier
external_id string External label package identifier
trigger_type string
recorded_at string X Date time of courier's action
delivered_to string X Specify to whom was order delivered
  • neighbour
  • recipient
  • housemate
  • safe_place
delivered_to_extra_info string Specify to which safe place order was delivered
photo_proof: object Mandatory in case delivered_to
is listed in delivered_to_options_with_required_photo_proof 		Photo proof
note string Explanation message
data_uris array Array of images encoded using Data URI scheme.
Allowed image types: png, jpg, jpeg, gif.
File max size 700 kb.
signature: object Mandatory in case job require signature Signature
name string Recipient / sender name
data_uri string Image (png, jpg, jpeg, gif).
Encoded using Data URI scheme.
File max size 100 kb.
service_time number X Service time
additional_service_time_reason string Mandatory in case service_time is greater
than service time included.
Service time included means
service_time attribute from response v1/stops 		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
On return:
  • courier_was_ignored
  • reception_was_refused
  • receiving_department_was_busy

Example URI

PUT https://sandbox.tiramizoo.com/courier_api/v1/return_stop
Request  simple message
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "f5b20522ee11d31c09fd0ac46ab4e759",
  "recorded_at": "2012-04-16T08:00:00+02:00",
  "service_time": 5,
  "packages": [
    {
      "identifier": "3F965356F287DE4C"
    }
  ]
}
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "bf545b8e453536ee431648d86711243b",
  "packages": [
    {
      "identifier": "FCB8349CA1858BBA",
      "external_id": "id123",
      "trigger_type": "Hello, world!"
    }
  ],
  "recorded_at": "2012-04-16 09:05",
  "delivered_to": "neighbour",
  "delivered_to_extra_info": "Hello, world!",
  "signature": {
    "name": "Otto Normalverbraucher",
    "data_uri": "TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5"
  },
  "service_time": 10,
  "photo_proof": {
    "note": "Next to big tree",
    "data_uris": [
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkBAMAAACC...REfRXH4tWFZGswQ2yAAAAAElFTkSuQmCC"
    ]
  },
  "additional_service_time_reason": "goods_could_not_be_found"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "auth_token": {
      "type": "string",
      "description": "Authentication token"
    },
    "packages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "identifier": {
            "type": "string",
            "description": "Package identifier"
          },
          "external_id": {
            "type": "string",
            "description": "External label package identifier"
          },
          "trigger_type": {
            "type": "string"
          }
        },
        "required": [
          "identifier"
        ]
      },
      "description": "Packages list delivered to return stop"
    },
    "recorded_at": {
      "type": "string",
      "description": "Date time of courier's action"
    },
    "delivered_to": {
      "type": "string",
      "enum": [
        "neighbour",
        "recipient",
        "housemate",
        "safe_place"
      ],
      "description": "To whom was order delivered"
    },
    "delivered_to_extra_info": {
      "type": "string",
      "description": "when delivered to safe_place, it should contain which specific place it was"
    },
    "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 (required if job require signature)"
    },
    "service_time": {
      "type": "number",
      "description": "Service time"
    },
    "photo_proof": {
      "type": "object",
      "properties": {
        "note": {
          "type": "string",
          "description": "Explanation message"
        },
        "data_uris": {
          "type": "array",
          "description": "Images array encoded using Data URI scheme."
        }
      },
      "description": "Photo_proof (required if type has `photo_proof = true`)"
    },
    "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 `service_time` is greater than service time included.Service time included means service time from response GET v1/stops."
    }
  },
  "required": [
    "auth_token",
    "recorded_at",
    "delivered_to",
    "service_time"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "uuid": "0f7d7662-4882-48f7-9166-2abcce556348",
  "address_line": "7040 Williamson Manor",
  "postal_code": "10316-8453",
  "city": "New Blondell",
  "starts_at": "2012-04-16T11:01:00+02:00",
  "ends_at": "2012-04-16T11:06:00+02:00",
  "name": "Franecki-Donnelly",
  "lat": 10.231,
  "lng": 43.001,
  "require_signature": false,
  "pickups_require_signature": false,
  "pickups_require_photo_proof": false,
  "require_real_service_time": true,
  "require_tail_lift": false,
  "complete": false,
  "change": null,
  "change_details": null,
  "report_only_in_time_window": true,
  "applicable_events": [],
  "service_time": 5,
  "done": false,
  "time_window": "11:01 - 11:06 16.04.2012",
  "jobs": [
    {
      "uuid": "521a43f4-4c3c-40bc-aeff-9561907b8b2c",
      "require_signature": false,
      "require_real_service_time": true,
      "state": "success",
      "require_tail_lift": false,
      "type": "delivery",
      "packages": [
        {
          "identifier": "4792F4E28C2AC8ED",
          "description": "A fish",
          "length": 30,
          "weight": 5,
          "height": 20,
          "width": 10,
          "size": "L",
          "order_identifier": "R8JSFO",
          "non_rotatable": false,
          "fragile_goods": false,
          "protect_from_water": false,
          "external_id": null,
          "state": "returned",
          "actions": []
        }
      ],
      "order_identifier": "R8JSFO",
      "external_order_id": "X2MSII",
      "courier_information": "go go go; now now now",
      "hazard_index": 0,
      "distance": 2,
      "events": [],
      "pickup": {
        "name": "I.P. Freely",
        "address_line": "Im Dol 2",
        "postal_code": "14195",
        "city": "Berlin",
        "phone_number": "30049223333",
        "after": "2012-04-16T07:00:00+02:00",
        "before": "2012-04-16T07:30:00+02:00",
        "information": "go go go",
        "requirements": [],
        "can_cancel_package_pickup": false,
        "allow_partial_pick_up": false
      },
      "delivery": {
        "name": "Mike Rotch",
        "address_line": "Im Dol 48",
        "postal_code": "14195",
        "city": "Berlin",
        "phone_number": "30049224444",
        "after": "2012-04-16T07:30:00+02:00",
        "before": "2012-04-16T09:00:00+02:00",
        "information": "now now now",
        "requirements": [],
        "allow_partial_delivery": false
      },
      "return": {
        "service_times": {
          "1": 6
        },
        "location_service_time": 0,
        "additional_service_time": 0
      }
    }
  ],
  "available_additional_service_time_reasons": [],
  "service_time_options": [
    5,
    10,
    15,
    20,
    30,
    45,
    60,
    90,
    120
  ],
  "can_not_be_served_before": null,
  "available_delivered_to_options": [
    "recipient",
    "neighbour",
    "housemate",
    "safe_place"
  ],
  "safe_place_options": [
    "at_the_apartments_door",
    "on_the_doorstep",
    "mailbox",
    "garage",
    "other"
  ],
  "delivered_to_options_with_required_signature": [
    "housemate",
    "neighbour",
    "recipient"
  ],
  "delivered_to_options_with_required_photo_proof": [],
  "applicable_delivered_to_options": {
    "recipient": {
      "photo_proof": false,
      "signature": true
    },
    "neighbour": {
      "photo_proof": false,
      "signature": true
    },
    "housemate": {
      "photo_proof": false,
      "signature": true
    },
    "safe_place": {
      "at_the_apartments_door": {
        "photo_proof": false,
        "signature": false
      },
      "on_the_doorstep": {
        "photo_proof": false,
        "signature": false
      },
      "mailbox": {
        "photo_proof": false,
        "signature": false
      },
      "garage": {
        "photo_proof": false,
        "signature": false
      },
      "other": {
        "photo_proof": false,
        "signature": false
      }
    }
  },
  "mandatory_delivered_to_process": false,
  "allow_one_click_selection": false,
  "information": null
}

Stops Updates

Resource responsible for acceptance of not maintained yet stops

Protected resources.
Authorization required via auth_token.

Obtain all stops with pending offers

Obtain all stops with pending offers
GET/v1/stops_updates{?auth_token}

Example URI

GET https://sandbox.tiramizoo.com/courier_api/v1/stops_updates?auth_token=bf545b8e453536ee431648d86711243b
URI Parameters
HideShow
auth_token
string (required) Example: bf545b8e453536ee431648d86711243b

Authentication token

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "uuid": "daa650aa-4be1-4051-b9d5-329222b24e35",
    "order_identifier": "X15MES",
    "courier_company_name": "Company 36",
    "packages": [
      {
        "length": 30,
        "weight": 5,
        "height": 20,
        "width": 10,
        "size": "L",
        "order_identifier": "X15MES",
        "description": "--- Hidden ---",
        "identifier": "--- Hidden ---"
      }
    ],
    "courier_information": "go go go; now now now",
    "hazard_index": 0,
    "distance": 2,
    "pickup": {
      "name": "--- Hidden ---",
      "address_line": "Im Dol 2",
      "postal_code": "14195",
      "city": "Berlin",
      "phone_number": "--- Hidden ---",
      "after": "2012-04-16T07:00:00+02:00",
      "before": "2012-04-16T07:30:00+02:00",
      "information": "--- Hidden ---",
      "requirements": []
    },
    "delivery": {
      "name": "--- Hidden ---",
      "address_line": "Im Dol 48",
      "postal_code": "14195",
      "city": "Berlin",
      "phone_number": "--- Hidden ---",
      "after": "2012-04-16T07:30:00+02:00",
      "before": "2012-04-16T09:00:00+02:00",
      "information": "--- Hidden ---",
      "requirements": []
    }
  }
]

Show offer

Show offer
GET/v1/stops_updates/{id}{?auth_token}

Example URI

GET https://sandbox.tiramizoo.com/courier_api/v1/stops_updates/f56bc59fbb2adh67swoa7gv7?auth_token=bf545b8e453536ee431648d86711243b
URI Parameters
HideShow
id
number (required) Example: f56bc59fbb2adh67swoa7gv7

Pending offer uuid

auth_token
string (required) Example: bf545b8e453536ee431648d86711243b

Authentication token

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "courier_company_name": "Company 40",
  "courier_offer_uuid": "7eed6f14-7b14-4e37-add1-4af149468972",
  "stops": [
    {
      "uuid": null,
      "address_line": "Im Dol 2",
      "postal_code": "14195",
      "city": "Berlin",
      "starts_at": "2012-04-15T23:48:00+02:00",
      "ends_at": "2012-04-15T23:54:00+02:00",
      "lat": 10.231,
      "lng": 43.001,
      "require_signature": false,
      "require_real_service_time": true,
      "complete": false,
      "change": "created",
      "change_details": null,
      "available_events": [
        {
          "type": "wrong_package_size",
          "retry": false,
          "retry_count": 0,
          "photo_proof": true,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": false
        },
        {
          "type": "package_was_not_ready",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": true,
          "job_uuids": [
            null
          ],
          "common": false
        },
        {
          "type": "sender_wants_to_cancel",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": true,
          "job_uuids": [
            null
          ],
          "common": false
        },
        {
          "type": "sender_was_not_at_home",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": true
        },
        {
          "type": "address_not_found",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": true
        },
        {
          "type": "name_not_found_on_doorbell",
          "retry": false,
          "retry_count": 0,
          "photo_proof": true,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": true
        },
        {
          "type": "no_attempt_due_to_being_late",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": true
        },
        {
          "type": "failed_due_to_business_closed",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": true
        }
      ],
      "service_time": 6,
      "done": false,
      "time_window": "07:00 - 07:30 16.04.2012",
      "available_additional_service_time_reasons": [
        {
          "type": "goods_could_not_be_found",
          "job_uuids": [
            null
          ]
        },
        {
          "type": "handover_took_longer_as_planned",
          "job_uuids": [
            null
          ]
        },
        {
          "type": "place_was_not_specified_correctly",
          "job_uuids": [
            null
          ]
        },
        {
          "type": "contact_was_not_available",
          "job_uuids": [
            null
          ]
        },
        {
          "type": "contact_was_busy",
          "job_uuids": [
            null
          ]
        },
        {
          "type": "courier_was_ignored",
          "job_uuids": [
            null
          ]
        }
      ],
      "jobs": [
        {
          "id": null,
          "type": "pickup",
          "require_signature": false,
          "require_real_service_time": true,
          "state": "created",
          "packages": [
            {
              "length": 30,
              "weight": 5,
              "height": 20,
              "width": 10,
              "size": "L",
              "order_identifier": "NHA5NW",
              "description": "--- Hidden ---",
              "identifier": "--- Hidden ---"
            }
          ],
          "order_identifier": "NHA5NW",
          "courier_information": "go go go; now now now",
          "hazard_index": 0,
          "distance": 2,
          "pickup": {
            "name": "--- Hidden ---",
            "address_line": "Im Dol 2",
            "postal_code": "14195",
            "city": "Berlin",
            "phone_number": "--- Hidden ---",
            "after": "2012-04-16T07:00:00+02:00",
            "before": "2012-04-16T07:30:00+02:00",
            "information": "--- Hidden ---",
            "requirements": []
          },
          "delivery": {
            "name": "--- Hidden ---",
            "address_line": "Im Dol 48",
            "postal_code": "14195",
            "city": "Berlin",
            "phone_number": "--- Hidden ---",
            "after": "2012-04-16T07:30:00+02:00",
            "before": "2012-04-16T09:00:00+02:00",
            "information": "--- Hidden ---",
            "requirements": []
          }
        }
      ]
    },
    {
      "uuid": null,
      "address_line": "Im Dol 48",
      "postal_code": "14195",
      "city": "Berlin",
      "starts_at": "2012-04-16T08:54:00+02:00",
      "ends_at": "2012-04-16T09:00:00+02:00",
      "lat": 10.2511,
      "lng": 43.998,
      "require_signature": false,
      "require_real_service_time": true,
      "complete": false,
      "change": "created",
      "change_details": null,
      "available_events": [
        {
          "type": "abort_delivery",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": false
        },
        {
          "type": "package_is_damaged",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": true,
          "job_uuids": [
            null
          ],
          "common": false
        },
        {
          "type": "no_access_to_building",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": false
        },
        {
          "type": "package_was_not_ordered",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": true,
          "job_uuids": [
            null
          ],
          "common": false
        },
        {
          "type": "package_was_not_accepted",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": true,
          "job_uuids": [
            null
          ],
          "common": false
        },
        {
          "type": "recipient_was_not_at_home",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": true
        },
        {
          "type": "not_enough_money_for_payment",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": true,
          "job_uuids": [
            null
          ],
          "common": false
        },
        {
          "type": "package_was_delivered_too_late",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": true,
          "job_uuids": [
            null
          ],
          "common": false
        },
        {
          "type": "address_not_found",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": true
        },
        {
          "type": "name_not_found_on_doorbell",
          "retry": false,
          "retry_count": 0,
          "photo_proof": true,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": true
        },
        {
          "type": "no_attempt_due_to_being_late",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": true
        },
        {
          "type": "failed_due_to_business_closed",
          "retry": false,
          "retry_count": 0,
          "photo_proof": false,
          "sign": false,
          "job_uuids": [
            null
          ],
          "common": true
        }
      ],
      "service_time": 6,
      "done": false,
      "time_window": "07:30 - 09:00 16.04.2012",
      "available_additional_service_time_reasons": [
        {
          "type": "contact_could_not_be_found",
          "job_uuids": [
            null
          ]
        },
        {
          "type": "unloading_longer_than_expected_due_bulky_goods",
          "job_uuids": [
            null
          ]
        },
        {
          "type": "recipient_was_contacted_by_phone",
          "job_uuids": [
            null
          ]
        },
        {
          "type": "hotline_had_to_be_contacted_for_clarification",
          "job_uuids": [
            null
          ]
        }
      ],
      "jobs": [
        {
          "id": null,
          "type": "delivery",
          "require_signature": false,
          "require_real_service_time": true,
          "state": "created",
          "packages": [
            {
              "length": 30,
              "weight": 5,
              "height": 20,
              "width": 10,
              "size": "L",
              "order_identifier": "NHA5NW",
              "description": "--- Hidden ---",
              "identifier": "--- Hidden ---"
            }
          ],
          "order_identifier": "NHA5NW",
          "courier_information": "go go go; now now now",
          "hazard_index": 0,
          "distance": 2,
          "pickup": {
            "name": "--- Hidden ---",
            "address_line": "Im Dol 2",
            "postal_code": "14195",
            "city": "Berlin",
            "phone_number": "--- Hidden ---",
            "after": "2012-04-16T07:00:00+02:00",
            "before": "2012-04-16T07:30:00+02:00",
            "information": "--- Hidden ---",
            "requirements": []
          },
          "delivery": {
            "name": "--- Hidden ---",
            "address_line": "Im Dol 48",
            "postal_code": "14195",
            "city": "Berlin",
            "phone_number": "--- Hidden ---",
            "after": "2012-04-16T07:30:00+02:00",
            "before": "2012-04-16T09:00:00+02:00",
            "information": "--- Hidden ---",
            "requirements": []
          }
        }
      ]
    }
  ]
}

Count offers

Count offers
GET/v1/stops_updates/count{?auth_token}

Example URI

GET https://sandbox.tiramizoo.com/courier_api/v1/stops_updates/count?auth_token=bf545b8e453536ee431648d86711243b
URI Parameters
HideShow
auth_token
string (required) Example: bf545b8e453536ee431648d86711243b

Authentication token

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "count": 0
}

Accept pending offer

Accept pending offer
PUT/v1/stops_updates/{id}

Attribute name Type Required Description
auth_token string X Authentication token
id number X Pending offer uuid

Example URI

PUT https://sandbox.tiramizoo.com/courier_api/v1/stops_updates/f56bc59fbb2adh67swoa7gv7
URI Parameters
HideShow
id
number (required) Example: f56bc59fbb2adh67swoa7gv7

Pending offer uuid

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "bf545b8e453536ee431648d86711243b"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "auth_token": {
      "type": "string",
      "description": "Authentication token"
    }
  },
  "required": [
    "auth_token"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "courier_company_name": "Company 5",
  "courier_offer_uuid": "4b6b820d-b0c7-4bc0-b804-004b53abb017",
  "stops": [
    {
      "uuid": "aa680d1c-f025-4b9f-8554-443dbe9a45da",
      "address_line": "Im Dol 2",
      "postal_code": "14195",
      "city": "Berlin",
      "starts_at": "2012-04-15T23:48:00+02:00",
      "ends_at": "2012-04-15T23:54:00+02:00",
      "name": "I.P. Freely",
      "lat": 10.231,
      "lng": 43.001,
      "require_signature": false,
      "pickups_require_signature": false,
      "pickups_require_photo_proof": false,
      "require_real_service_time": true,
      "require_tail_lift": false,
      "complete": false,
      "change": null,
      "change_details": null,
      "report_only_in_time_window": true,
      "applicable_events": [
        {
          "type": "failed_due_to_business_closed",
          "jobs": [
            {
              "uuid": "5f4430e0-c992-43e7-834d-39c3079d54e1",
              "photo_proof": false,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": true,
          "creates_return_stop": true
        },
        {
          "type": "address_not_found",
          "jobs": [
            {
              "uuid": "5f4430e0-c992-43e7-834d-39c3079d54e1",
              "photo_proof": false,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": true,
          "creates_return_stop": true
        },
        {
          "type": "name_not_found_on_doorbell",
          "jobs": [
            {
              "uuid": "5f4430e0-c992-43e7-834d-39c3079d54e1",
              "photo_proof": true,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": true,
          "creates_return_stop": true
        },
        {
          "type": "no_attempt_due_to_being_late",
          "jobs": [
            {
              "uuid": "5f4430e0-c992-43e7-834d-39c3079d54e1",
              "photo_proof": false,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": true,
          "creates_return_stop": true
        },
        {
          "type": "wrong_package_size",
          "jobs": [
            {
              "uuid": "5f4430e0-c992-43e7-834d-39c3079d54e1",
              "photo_proof": true,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": false,
          "creates_return_stop": true
        },
        {
          "type": "package_was_not_ready",
          "jobs": [
            {
              "uuid": "5f4430e0-c992-43e7-834d-39c3079d54e1",
              "photo_proof": false,
              "sign": true
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": false,
          "creates_return_stop": true
        },
        {
          "type": "sender_wants_to_cancel",
          "jobs": [
            {
              "uuid": "5f4430e0-c992-43e7-834d-39c3079d54e1",
              "photo_proof": false,
              "sign": true
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": false,
          "creates_return_stop": true
        },
        {
          "type": "sender_was_not_at_home",
          "jobs": [
            {
              "uuid": "5f4430e0-c992-43e7-834d-39c3079d54e1",
              "photo_proof": false,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": true,
          "creates_return_stop": true
        }
      ],
      "service_time": 6,
      "done": false,
      "time_window": "07:00 - 07:30 16.04.2012",
      "jobs": [
        {
          "uuid": "5f4430e0-c992-43e7-834d-39c3079d54e1",
          "require_signature": false,
          "require_real_service_time": true,
          "state": "created",
          "require_tail_lift": false,
          "type": "pickup",
          "packages": [
            {
              "identifier": "95A5186ECBDB7351",
              "description": "A fish",
              "length": 30,
              "weight": 5,
              "height": 20,
              "width": 10,
              "size": "L",
              "order_identifier": "T33K9B",
              "non_rotatable": false,
              "fragile_goods": false,
              "protect_from_water": false,
              "external_id": null,
              "state": "pending",
              "actions": [
                "hand_over"
              ]
            }
          ],
          "order_identifier": "T33K9B",
          "external_order_id": "JQIVUE",
          "courier_information": "go go go; now now now",
          "hazard_index": 0,
          "distance": 2,
          "events": [],
          "pickup": {
            "name": "I.P. Freely",
            "address_line": "Im Dol 2",
            "postal_code": "14195",
            "city": "Berlin",
            "phone_number": "30049223333",
            "after": "2012-04-16T07:00:00+02:00",
            "before": "2012-04-16T07:30:00+02:00",
            "information": "go go go",
            "requirements": [],
            "can_cancel_package_pickup": false,
            "allow_partial_pick_up": false
          },
          "delivery": {
            "name": "Mike Rotch",
            "address_line": "Im Dol 48",
            "postal_code": "14195",
            "city": "Berlin",
            "phone_number": "30049224444",
            "after": "2012-04-16T07:30:00+02:00",
            "before": "2012-04-16T09:00:00+02:00",
            "information": "now now now",
            "requirements": [],
            "allow_partial_delivery": false
          },
          "return": {
            "service_times": {
              "1": 6
            },
            "location_service_time": 0,
            "additional_service_time": 0
          }
        }
      ],
      "available_additional_service_time_reasons": [
        {
          "type": "goods_could_not_be_found",
          "job_uuids": [
            "5f4430e0-c992-43e7-834d-39c3079d54e1"
          ]
        },
        {
          "type": "handover_took_longer_as_planned",
          "job_uuids": [
            "5f4430e0-c992-43e7-834d-39c3079d54e1"
          ]
        },
        {
          "type": "place_was_not_specified_correctly",
          "job_uuids": [
            "5f4430e0-c992-43e7-834d-39c3079d54e1"
          ]
        },
        {
          "type": "contact_was_not_available",
          "job_uuids": [
            "5f4430e0-c992-43e7-834d-39c3079d54e1"
          ]
        },
        {
          "type": "contact_was_busy",
          "job_uuids": [
            "5f4430e0-c992-43e7-834d-39c3079d54e1"
          ]
        },
        {
          "type": "courier_was_ignored",
          "job_uuids": [
            "5f4430e0-c992-43e7-834d-39c3079d54e1"
          ]
        }
      ],
      "service_time_options": [
        6,
        15,
        20,
        30,
        45,
        60,
        90,
        120
      ],
      "can_not_be_served_before": "2012-04-16T07:00:00+02:00",
      "available_delivered_to_options": [
        "recipient",
        "neighbour",
        "housemate",
        "safe_place"
      ],
      "safe_place_options": [
        "at_the_apartments_door",
        "on_the_doorstep",
        "mailbox",
        "garage",
        "other"
      ],
      "delivered_to_options_with_required_signature": [
        "housemate",
        "neighbour",
        "recipient"
      ],
      "delivered_to_options_with_required_photo_proof": [],
      "applicable_delivered_to_options": {
        "recipient": {
          "photo_proof": false,
          "signature": true
        },
        "neighbour": {
          "photo_proof": false,
          "signature": true
        },
        "housemate": {
          "photo_proof": false,
          "signature": true
        },
        "safe_place": {
          "at_the_apartments_door": {
            "photo_proof": false,
            "signature": false
          },
          "on_the_doorstep": {
            "photo_proof": false,
            "signature": false
          },
          "mailbox": {
            "photo_proof": false,
            "signature": false
          },
          "garage": {
            "photo_proof": false,
            "signature": false
          },
          "other": {
            "photo_proof": false,
            "signature": false
          }
        }
      },
      "mandatory_delivered_to_process": false,
      "allow_one_click_selection": false,
      "information": null
    },
    {
      "uuid": "3c94e9e2-c0ac-46eb-9241-c74c4f995676",
      "address_line": "Im Dol 48",
      "postal_code": "14195",
      "city": "Berlin",
      "starts_at": "2012-04-16T08:54:00+02:00",
      "ends_at": "2012-04-16T09:00:00+02:00",
      "name": "Mike Rotch",
      "lat": 10.2511,
      "lng": 43.998,
      "require_signature": false,
      "pickups_require_signature": false,
      "pickups_require_photo_proof": false,
      "require_real_service_time": true,
      "require_tail_lift": false,
      "complete": false,
      "change": null,
      "change_details": null,
      "report_only_in_time_window": true,
      "applicable_events": [
        {
          "type": "recipient_was_not_at_home",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": false,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": true,
          "creates_return_stop": true
        },
        {
          "type": "failed_due_to_business_closed",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": false,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": true,
          "creates_return_stop": true
        },
        {
          "type": "address_not_found",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": false,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": true,
          "creates_return_stop": true
        },
        {
          "type": "name_not_found_on_doorbell",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": true,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": true,
          "creates_return_stop": true
        },
        {
          "type": "no_attempt_due_to_being_late",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": false,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": true,
          "creates_return_stop": true
        },
        {
          "type": "package_was_not_accepted",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": false,
              "sign": true
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": false,
          "creates_return_stop": true
        },
        {
          "type": "no_access_to_building",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": false,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": false,
          "creates_return_stop": true
        },
        {
          "type": "abort_delivery",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": false,
              "sign": false
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": false,
          "creates_return_stop": true
        },
        {
          "type": "package_was_not_ordered",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": false,
              "sign": true
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": false,
          "creates_return_stop": true
        },
        {
          "type": "package_is_damaged",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": false,
              "sign": true
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": false,
          "creates_return_stop": true
        },
        {
          "type": "not_enough_money_for_payment",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": false,
              "sign": true
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": false,
          "creates_return_stop": true
        },
        {
          "type": "package_was_delivered_too_late",
          "jobs": [
            {
              "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
              "photo_proof": false,
              "sign": true
            }
          ],
          "retry": false,
          "retry_count": 0,
          "common": false,
          "creates_return_stop": true
        }
      ],
      "service_time": 6,
      "done": false,
      "time_window": "07:30 - 09:00 16.04.2012",
      "jobs": [
        {
          "uuid": "b22b5372-6911-4d5f-bf57-0469f8d8c3ac",
          "require_signature": false,
          "require_real_service_time": true,
          "state": "created",
          "require_tail_lift": false,
          "type": "delivery",
          "packages": [
            {
              "identifier": "95A5186ECBDB7351",
              "description": "A fish",
              "length": 30,
              "weight": 5,
              "height": 20,
              "width": 10,
              "size": "L",
              "order_identifier": "T33K9B",
              "non_rotatable": false,
              "fragile_goods": false,
              "protect_from_water": false,
              "external_id": null,
              "state": "pending",
              "actions": []
            }
          ],
          "order_identifier": "T33K9B",
          "external_order_id": "JQIVUE",
          "courier_information": "go go go; now now now",
          "hazard_index": 0,
          "distance": 2,
          "events": [],
          "pickup": {
            "name": "I.P. Freely",
            "address_line": "Im Dol 2",
            "postal_code": "14195",
            "city": "Berlin",
            "phone_number": "30049223333",
            "after": "2012-04-16T07:00:00+02:00",
            "before": "2012-04-16T07:30:00+02:00",
            "information": "go go go",
            "requirements": [],
            "can_cancel_package_pickup": false,
            "allow_partial_pick_up": false
          },
          "delivery": {
            "name": "Mike Rotch",
            "address_line": "Im Dol 48",
            "postal_code": "14195",
            "city": "Berlin",
            "phone_number": "30049224444",
            "after": "2012-04-16T07:30:00+02:00",
            "before": "2012-04-16T09:00:00+02:00",
            "information": "now now now",
            "requirements": [],
            "allow_partial_delivery": false
          },
          "return": {
            "service_times": {
              "1": 6
            },
            "location_service_time": 0,
            "additional_service_time": 0
          }
        }
      ],
      "available_additional_service_time_reasons": [
        {
          "type": "contact_could_not_be_found",
          "job_uuids": [
            "b22b5372-6911-4d5f-bf57-0469f8d8c3ac"
          ]
        },
        {
          "type": "unloading_longer_than_expected_due_bulky_goods",
          "job_uuids": [
            "b22b5372-6911-4d5f-bf57-0469f8d8c3ac"
          ]
        },
        {
          "type": "recipient_was_contacted_by_phone",
          "job_uuids": [
            "b22b5372-6911-4d5f-bf57-0469f8d8c3ac"
          ]
        },
        {
          "type": "hotline_had_to_be_contacted_for_clarification",
          "job_uuids": [
            "b22b5372-6911-4d5f-bf57-0469f8d8c3ac"
          ]
        }
      ],
      "service_time_options": [
        6,
        15,
        20,
        30,
        45,
        60,
        90,
        120
      ],
      "can_not_be_served_before": null,
      "available_delivered_to_options": [
        "recipient",
        "neighbour",
        "housemate",
        "safe_place"
      ],
      "safe_place_options": [
        "at_the_apartments_door",
        "on_the_doorstep",
        "mailbox",
        "garage",
        "other"
      ],
      "delivered_to_options_with_required_signature": [
        "housemate",
        "neighbour",
        "recipient"
      ],
      "delivered_to_options_with_required_photo_proof": [],
      "applicable_delivered_to_options": {
        "recipient": {
          "photo_proof": false,
          "signature": true
        },
        "neighbour": {
          "photo_proof": false,
          "signature": true
        },
        "housemate": {
          "photo_proof": false,
          "signature": true
        },
        "safe_place": {
          "at_the_apartments_door": {
            "photo_proof": false,
            "signature": false
          },
          "on_the_doorstep": {
            "photo_proof": false,
            "signature": false
          },
          "mailbox": {
            "photo_proof": false,
            "signature": false
          },
          "garage": {
            "photo_proof": false,
            "signature": false
          },
          "other": {
            "photo_proof": false,
            "signature": false
          }
        }
      },
      "mandatory_delivered_to_process": false,
      "allow_one_click_selection": false,
      "information": null
    }
  ]
}

Signatures

Show signature

Show signature
GET/v1/signatures/{id}.png

Example URI

GET https://sandbox.tiramizoo.com/courier_api/v1/signatures/ed25b451-43d6-427f-845d-e0d5914e5965.png
URI Parameters
HideShow
id
string (required) Example: ed25b451-43d6-427f-845d-e0d5914e5965

Signature uuid

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow

Respond with image file

Delivery events

Protected resource.
Authorization required via auth_token.

Create delivery event

Create delivery event
POST/v1/delivery_events

Attribute name Type Required Description Available types:
auth_token string X Authentication token
job_uuids array X Array of job uuids
job_ids array Array of job ids (deprecated)
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
  • recipient_was_not_at_home
  • not_enough_money_for_payment
  • package_is_damaged
  • package_was_delivered_too_late
  • package_was_not_accepted
  • package_was_not_ordered
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
retry_at string Date time when job should be retried
recorded_at string Date time when event had place.
If not param present current time is used.
photo_proof: object Mandatory in case job require photo proof Photo proof
note string Explanation message
data_uri string Deprecated
Image (png, jpg, jpeg, gif).
Encoded using Data URI scheme.
File max size 700 kb.
data_uris array Array of images encoded using Data URI scheme.
Allowed image types: png, jpg, jpeg, gif.
File max size 700 kb.
signature: object Mandatory in case job require signature Signature
name string Recipient / sender name
data_uri string Image (png, jpg, jpeg, gif).
Encoded using Data URI scheme.
File max size 100 kb.
service_time number Service time in minutes
additional_service_time_reason string Mandatory in case service_time is greater
than service time included.
Service time included means
service_time attribute from response v1/stops 		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_api/v1/delivery_events
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "bf545b8e453536ee431648d86711243b",
  "job_uuids": [
    "1d16702c-19ab-4b37-9293-3fe24cfd03e4",
    "333bea5e-d4b1-4f7b-ab29-a62f4b27be7c"
  ],
  "type": "package_was_not_ready",
  "retry_at": "2015-01-08 15:18:42",
  "recorded_at": "2015-01-07 15:18:42",
  "signature": {
    "name": "Otto Normalverbraucher",
    "data_uri": "TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5"
  },
  "photo_proof": {
    "note": "the left corner is damaged",
    "data_uris": [
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkBAMAAACC...REfRXH4tWFZGswQ2yAAAAAElFTkSuQmCC"
    ]
  },
  "service_time": 30,
  "additional_service_time_reason": "goods_could_not_be_found"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "auth_token": {
      "type": "string",
      "description": "Authentication token"
    },
    "job_uuids": {
      "type": "array",
      "description": "Array of job uuids"
    },
    "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"
    },
    "retry_at": {
      "type": "string",
      "description": "Date time when job should be retried"
    },
    "recorded_at": {
      "type": "string",
      "description": "Date time when event had place (if not param present current time is used)"
    },
    "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 (required if job require signature)"
    },
    "photo_proof": {
      "type": "object",
      "properties": {
        "note": {
          "type": "string",
          "description": "Explanation message"
        },
        "data_uris": {
          "type": "array",
          "description": "Images array encoded using Data URI scheme."
        }
      },
      "description": "Photo_proof (required if type is `name_not_found_on_doorbell` or `wrong_package_size`))"
    },
    "service_time": {
      "type": "number"
    },
    "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 service time included.Service time included means service time from response GET v1/stops."
    }
  },
  "required": [
    "auth_token",
    "job_uuids",
    "type"
  ]
}
Response  201

Statuses

Record courier GPS information

Protected resource.
Authorization required via auth_token.

Create status

Create status
POST/v1/statuses

Attribute name Type Required Description
auth_token string X Authentication token
location: object X GPS location data
latitude number X Current position latitude
longitude number X Current position longitude
vehicle string Courier vehicle information
recorded_at string Date time
device_id string Identification number of courier's device
event string

Example URI

POST https://sandbox.tiramizoo.com/courier_api/v1/statuses
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "bf545b8e453536ee431648d86711243b",
  "vehicle": "bmw 500",
  "recorded_at": "2014-5-3 17:00",
  "event": "delivery_failed",
  "device_id": "352523",
  "location": {
    "latitude": 12.12,
    "longitude": 11.11
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "auth_token": {
      "type": "string",
      "description": "Authentication token"
    },
    "vehicle": {
      "type": "string",
      "description": "Courier vehicle information"
    },
    "recorded_at": {
      "type": "string",
      "description": "date of event"
    },
    "event": {
      "type": "string",
      "description": "event type"
    },
    "device_id": {
      "type": "string",
      "description": "device identification number"
    },
    "location": {
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number",
          "description": "Current position latitude"
        },
        "longitude": {
          "type": "number",
          "description": "Current position longitude"
        }
      },
      "required": [
        "latitude",
        "longitude"
      ],
      "description": "GPS location data"
    }
  },
  "required": [
    "auth_token",
    "location"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json

Performance

Show performance of a courier

Show performance of a courier
GET/v1/performance

Example URI

GET https://sandbox.tiramizoo.com/courier_api/v1/performance
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "auth_token": "bf545b8e453536ee431648d86711243b"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "auth_token": {
      "type": "string",
      "description": "Authentication token"
    }
  },
  "required": [
    "auth_token"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  // Object with the stats, API sends data in order
  // i.e. today, current month, remaining 11 months.
  // If period doesn't have any data the stats are not being sent
  {
    // "today", "current_month", lowercased month names
    "label": "today",
    "number_of_tours": 1,
    "deliveries": {
      // "good", "neutral", or "bad"
      "rating": "good",
      "ratio": 0.98
    },
    "pickups": {
      "rating": "neutral",
      "ratio": 0.94
    },
    "hit_rate": {
      "rating": "bad",
      "ratio": 0.93
    }
  }
]

Saas Organization

Show contact details of a Saas Organization

Show contact details of a Saas Organization
GET/v1/saas_organization

Example URI

GET https://sandbox.tiramizoo.com/courier_api/v1/saas_organization
Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Body
{
    "organization_email": 'support@tiramizoo.com',
    "organization_phone_number": '+49.89 21556870',
    "organization_return_additional_service_time_reasons": ["courier_was_ignored", "reception_was_refused", "receiving_department_was_busy"]
}

Generated by aglio on 11 Oct 2023