From 576304ab9d3c738969c9ae886abcd806c8ded7a4 Mon Sep 17 00:00:00 2001 From: partizaans Date: Fri, 5 Aug 2022 15:27:52 +0430 Subject: [PATCH 01/11] Document issue-related endpoints --- slate/source/index.html.md | 834 +++++++++++++++++++++++++++---------- 1 file changed, 606 insertions(+), 228 deletions(-) diff --git a/slate/source/index.html.md b/slate/source/index.html.md index 3c7d74b..93a82b8 100644 --- a/slate/source/index.html.md +++ b/slate/source/index.html.md @@ -43,7 +43,6 @@ Your token is our only way to make sure requests are coming from you, so keep it Authenticate process is further discussed in the Authentication - # Definitions ### Client @@ -61,14 +60,14 @@ Our clients may also indicate that they wish the courier to return to the source #### Trip states Each trip can be in only one the following states at any given time -Name | Description ----- | ----------- -assign_queue | Trip is created but no courier has been assigned to it yet -pickup | Trip is assigned to a courier and the courier is on his way to pickup packages from the source -dropoff | Trip is picked up by the courier and he is on his way to deliver the packages -delivered | All of the packages of the trip are delivered (and if trip was a round trip, courier has returned to the source) -canceled_by_miare | Trip is canceled by our support staff. This only happens with source's aggrement or due to a violation of terms of service -canceled_by_client | Trip is canceled by client (either from the web panel or Third Party API) +| Name | Description | +|--------------------|----------------------------------------------------------------------------------------------------------------------------| +| assign_queue | Trip is created but no courier has been assigned to it yet | +| pickup | Trip is assigned to a courier and the courier is on his way to pickup packages from the source | +| dropoff | Trip is picked up by the courier and he is on his way to deliver the packages | +| delivered | All of the packages of the trip are delivered (and if trip was a round trip, courier has returned to the source) | +| canceled_by_miare | Trip is canceled by our support staff. This only happens with source's aggrement or due to a violation of terms of service | +| canceled_by_client | Trip is canceled by client (either from the web panel or Third Party API) | ### Course A destination and a package to be delivered at that destination. Each trip can have one or more courses. @@ -88,12 +87,12 @@ The current state of the shifts can be considered constant, and any change will Start and end time of shifts area as follows: -name | start | end ----- | ----- | --- -morning | 08:15 | 11:00 -noon | 11:00 | 17:30 -night | 17:30 | 23:30 -midnight | 23:30 | 03:00 +| name | start | end | +|----------|-------|-------| +| morning | 08:15 | 11:00 | + | noon | 11:00 | 17:30 | + | night | 17:30 | 23:30 | + | midnight | 23:30 | 03:00 | ### Concurrency The maximum number of **active** trips in each **area** during each **shift** for a client. @@ -104,6 +103,9 @@ Canceling a trip (by client) or ending it will free up a concurrency limit (by m Only trips in the assign_queue, pickup, dropoff, and delivered states are considered active and contribute to the concurrency limit of the client. +### Issue +A problem that is reported or detected on a trip. + # Servers Miare has two sets of servers. @@ -331,29 +333,28 @@ requests.post( ### Body -Value | Type | Description ------ | ---- | ----------- -**pickup** | object | The source of the trip -pickup.**name** | string | The human readable name of the pickup -pickup.**phone_number** | string | The phone number associated with the source which will be used by courier and support staffs in order to contact to pickup if necessary -pickup.**address** | string | The human readable address of the source, preferably down to every necessary detail for a human to find the source quickly -pickup.**image** | string [uri] | A valid URL which points to an image file which should be the logo of the pickup. This image will be used in both support panel, and courier’s application. Make sure that the URL is both reachable and is configured to allow CORS requests -pickup.**location** | object | The exact location of the pickup -pickup.location.**latitude** | number [double] | The latitude of the pickup location -pickup.location.**longitude** | number [double] | The longitude of the pickup location -pickup.**deadline** | string [date-time] | The time that you expect the courier to arrive at the pickup, so optimally it should be the time package content is ready and packaged. **Can't be in the past** -**courses** | array | List of destinations of the trips -courses.**bill_number** | string | An string field left for you to store sort of a human readable bill number in it which will be used as a reference point among our support team, you and the pickup staffs -courses.**name** | string | Name of the dropp-off -courses.**phone_number** | string | The phone number associated with the drop-off which will be used by courier and support staffs in order to contact to them if necessary -coureses.**address** | string | The human readable drop-off address, preferably down to every necessary detail for a human to find it quickly -courses.location | object **(Optional)** | The exact location of the pickup. If there is no provided drop-off location, the courier will find the location based on the address and accounting calculations will be based on that location -courses.location.**latitude** | number [double] | The latitude of the drop-off location -courses.location.**longitude** | number [double] | The longitude of the drop-off location -courses.manifest_items | array **(Optional)** | The contents of the package to be delivered to the drop-off -courses.manifest_items.**name** | string | Human readable name of the content which will be verified by courier -courses.manifest_items.**quantity** | string | The quanitiy of the item - +| Value | Type | Description | +|-------------------------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **pickup** | object | The source of the trip | +| pickup.**name** | string | The human readable name of the pickup | +| pickup.**phone_number** | string | The phone number associated with the source which will be used by courier and support staffs in order to contact to pickup if necessary | +| pickup.**address** | string | The human readable address of the source, preferably down to every necessary detail for a human to find the source quickly | +| pickup.**image** | string [uri] | A valid URL which points to an image file which should be the logo of the pickup. This image will be used in both support panel, and courier’s application. Make sure that the URL is both reachable and is configured to allow CORS requests | +| pickup.**location** | object | The exact location of the pickup | +| pickup.location.**latitude** | number [double] | The latitude of the pickup location | +| pickup.location.**longitude** | number [double] | The longitude of the pickup location | +| pickup.**deadline** | string [date-time] | The time that you expect the courier to arrive at the pickup, so optimally it should be the time package content is ready and packaged. **Can't be in the past** | +| **courses** | array | List of destinations of the trips | +| courses.**bill_number** | string | An string field left for you to store sort of a human readable bill number in it which will be used as a reference point among our support team, you and the pickup staffs | +| courses.**name** | string | Name of the dropp-off | +| courses.**phone_number** | string | The phone number associated with the drop-off which will be used by courier and support staffs in order to contact to them if necessary | +| coureses.**address** | string | The human readable drop-off address, preferably down to every necessary detail for a human to find it quickly | +| courses.location | object **(Optional)** | The exact location of the pickup. If there is no provided drop-off location, the courier will find the location based on the address and accounting calculations will be based on that location | +| courses.location.**latitude** | number [double] | The latitude of the drop-off location | +| courses.location.**longitude** | number [double] | The longitude of the drop-off location | +| courses.manifest_items | array **(Optional)** | The contents of the package to be delivered to the drop-off | +| courses.manifest_items.**name** | string | Human readable name of the content which will be verified by courier | +| courses.manifest_items.**quantity** | string | The quanitiy of the item | ### Response @@ -417,68 +418,66 @@ courses.manifest_items.**quantity** | string | The quanitiy of the item } } ], - "tracking_url": "https://www.staging.mia.re/p/trip_watching/#!/7484f5305e", + "tracking_url": "https://www.staging.mia.re/p/trip_watching/#!/7484f5305e" } ``` -Value | Type | Description ------ |------| ----------- -**id** | string | Universally unique identifier of this trip -**created_at** | string [date-time] | The exact time this trip was created on our servers -**assigned_at** | string [date-time] **(nullable)** | The assign datetime of the time this trip was assigned to its courier. Will be **null** if trip is not assigned to a courier yet -**picked_up_at** | string [date-time] **(nullable)** | The datetime that the courier of the trip picked up its content from the source. Will be **null** if courier is not assigned or is not picked up packages just yet -**state** | string | The current state of the trip. Is one of the following values: "assign_queue" "pickup" "dropoff" "delivered" "canceled_by_miare" "canceled_by_client". You can find a description about each of these states [here](#trip) -**pickup** | object | The source of the trip -pickup.**name** | string | The human readable name of the pickup -pickup.**phone_number** | string | The phone number associated with the source which will be used by courier and support staffs in order to contact to pickup if necessary -pickup.**address** | string | The human readable address of the source, preferably down to every necessary detail for a human to find the source quickly -pickup.**image** | string [uri] | A valid URL which points to an image file which should be the logo of the pickup. This image will be used in both support panel, and courier’s application. Make sure that the URL is both reachable and is configured to allow CORS requests -pickup.**location** | object | The exact location of the pickup -pickup.location.**latitude** | number [double] | The latitude of the pickup location -pickup.location.**longitude** | number [double] | The longitude of the pickup location -pickup.**deadline** | string [date-time] | The time that you expect the courier to arrive at the pickup, so optimally it should be the time package content is ready and packaged. **Can't be in the past** -**courses** | array | List of destinations of the trips -courses.**id** | string | Universally unique identifier of this course -course.**trip_id** | string | Universally unique identifier of the trip that this course belongs to it -courses.**bill_number** | string | An string field left for you to store sort of a human readable bill number in it which will be used as a reference point among our support team, you and the pickup staffs -courses.**name** | string | Name of the dropp-off -courses.**phone_number** | string | The phone number associated with the drop-off which will be used by courier and support staffs in order to contact to them if necessary -coureses.**address** | string | The human readable drop-off address, preferably down to every necessary detail for a human to find it quickly -courses.location | object **(nullable)** | The exact location of the pickup. If there is no provided drop-off location, the courier will find the location based on the address and accounting calculations will be based on that location -courses.location.**latitude** | number [double] | The latitude of the drop-off location -courses.location.**longitude** | number [double] | The longitude of the drop-off location -courses.manifest_items | array **(nullable)** | The contents of the package to be delivered to the drop-off -courses.manifest_items.**name** | string | Human readable name of the content which will be verified by courier -courses.manifest_items.**quantity** | string | The quanitiy of the item -course.**tracking_url** | string [uri] | The URL of a webpage in which the end customer can track the exact state and location of his/her package while it's being delivered -course.**dropped_off_at** | string [date-time] **(nullable)** | The exact time this course we delivered to the customer. It will be **null** if the course is not delivered yet -course.**payment** | object | The payment information of the course -course.payment.**payment_type** | string | They selected method for this course's payment. At this moment the only available method for API users is `cash` -course.payment.**price** | string | The price of the package content (**not** to be confused with delivery cost). At this moment the only available value for API users is 0 -**area** | object | The detected area of the trip (based on pickup.location) -area.**id** | string | The identifier of this trip's area -area.**name** | string | Human readable name of this trip's area -**delivery_cost** | integer **(nullable)** | The final cost of a Trip Delivery. It will be **null** until trip is not delivered -courier | object **(nullable)** | Courier of this trip. Will be **null** if trip is not assigned to a courier yet -courier.**name** | string | Name of the courier -courier.**phone_number** | string | Phone number of the courier -courier.**image** | string [uri] | The URL of courier's profile picture -courier.**location** | object | Last known location of the courier -courier.location.**latitude** | number [double] | Latitude of the last known location of the courier -courier.location.**longitude** | number [double] | Longitude of the last known location of the courier -courier.**location_updated_at** | string [date-time] | Datetime of the last location of the courier - +| Value | Type | Description | +|-------------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **id** | string | Universally unique identifier of this trip | +| **created_at** | string [date-time] | The exact time this trip was created on our servers | +| **assigned_at** | string [date-time] **(nullable)** | The assign datetime of the time this trip was assigned to its courier. Will be **null** if trip is not assigned to a courier yet | +| **picked_up_at** | string [date-time] **(nullable)** | The datetime that the courier of the trip picked up its content from the source. Will be **null** if courier is not assigned or is not picked up packages just yet | +| **state** | string | The current state of the trip. Is one of the following values: "assign_queue" "pickup" "dropoff" "delivered" "canceled_by_miare" "canceled_by_client". You can find a description about each of these states [here](#trip) | +| **pickup** | object | The source of the trip | +| pickup.**name** | string | The human readable name of the pickup | +| pickup.**phone_number** | string | The phone number associated with the source which will be used by courier and support staffs in order to contact to pickup if necessary | +| pickup.**address** | string | The human readable address of the source, preferably down to every necessary detail for a human to find the source quickly | +| pickup.**image** | string [uri] | A valid URL which points to an image file which should be the logo of the pickup. This image will be used in both support panel, and courier’s application. Make sure that the URL is both reachable and is configured to allow CORS requests | +| pickup.**location** | object | The exact location of the pickup | +| pickup.location.**latitude** | number [double] | The latitude of the pickup location | +| pickup.location.**longitude** | number [double] | The longitude of the pickup location | +| pickup.**deadline** | string [date-time] | The time that you expect the courier to arrive at the pickup, so optimally it should be the time package content is ready and packaged. **Can't be in the past** | +| **courses** | array | List of destinations of the trips | +| courses.**id** | string | Universally unique identifier of this course | +| course.**trip_id** | string | Universally unique identifier of the trip that this course belongs to it | +| courses.**bill_number** | string | An string field left for you to store sort of a human readable bill number in it which will be used as a reference point among our support team, you and the pickup staffs | +| courses.**name** | string | Name of the dropp-off | +| courses.**phone_number** | string | The phone number associated with the drop-off which will be used by courier and support staffs in order to contact to them if necessary | +| coureses.**address** | string | The human readable drop-off address, preferably down to every necessary detail for a human to find it quickly | +| courses.location | object **(nullable)** | The exact location of the pickup. If there is no provided drop-off location, the courier will find the location based on the address and accounting calculations will be based on that location | +| courses.location.**latitude** | number [double] | The latitude of the drop-off location | +| courses.location.**longitude** | number [double] | The longitude of the drop-off location | +| courses.manifest_items | array **(nullable)** | The contents of the package to be delivered to the drop-off | +| courses.manifest_items.**name** | string | Human readable name of the content which will be verified by courier | +| courses.manifest_items.**quantity** | string | The quanitiy of the item | +| course.**tracking_url** | string [uri] | The URL of a webpage in which the end customer can track the exact state and location of his/her package while it's being delivered | +| course.**dropped_off_at** | string [date-time] **(nullable)** | The exact time this course we delivered to the customer. It will be **null** if the course is not delivered yet | +| course.**payment** | object | The payment information of the course | +| course.payment.**payment_type** | string | They selected method for this course's payment. At this moment the only available method for API users is `cash` | +| course.payment.**price** | string | The price of the package content (**not** to be confused with delivery cost). At this moment the only available value for API users is 0 | +| **area** | object | The detected area of the trip (based on pickup.location) | +| area.**id** | string | The identifier of this trip's area | +| area.**name** | string | Human readable name of this trip's area | +| **delivery_cost** | integer **(nullable)** | The final cost of a Trip Delivery. It will be **null** until trip is not delivered | +| courier | object **(nullable)** | Courier of this trip. Will be **null** if trip is not assigned to a courier yet | +| courier.**name** | string | Name of the courier | +| courier.**phone_number** | string | Phone number of the courier | +| courier.**image** | string [uri] | The URL of courier's profile picture | +| courier.**location** | object | Last known location of the courier | +| courier.location.**latitude** | number [double] | Latitude of the last known location of the courier | +| courier.location.**longitude** | number [double] | Longitude of the last known location of the courier | +| courier.**location_updated_at** | string [date-time] | Datetime of the last location of the courier | ### Errors -Code | Description ----- | ----------- -not_authenticated | Token is missing or invalid -parse_error | The request body is not a valid JSON string (has syntax error) -invalid_request_body | Request body does not follow the valid format -concurrency_limit | Client does not have enough concurrency in the area of the pickup location in the shift specified by deadline -service_level_order | Based on the current enviromental state, your service level is too low to receive services from Miare. Service limitation error mostly happens due to whether conditions or special occasions. In order to increase your service level or if you need more details about this limitation please contant sales team. - +| Code | Description | +|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| not_authenticated | Token is missing or invalid | +| parse_error | The request body is not a valid JSON string (has syntax error) | +| invalid_request_body | Request body does not follow the valid format | +| concurrency_limit | Client does not have enough concurrency in the area of the pickup location in the shift specified by deadline | +| service_level_order | Based on the current enviromental state, your service level is too low to receive services from Miare. Service limitation error mostly happens due to whether conditions or special occasions. In order to increase your service level or if you need more details about this limitation please contant sales team. | ## Cancel Trip @@ -516,9 +515,9 @@ requests.post( ### Path parameters -Name | Type | Description ------ | ---- | ----------- -trip_id | string | The ID of the trip to cancel +| Name | Type | Description | +|---------|--------|------------------------------| +| trip_id | string | The ID of the trip to cancel |