Suggestions Reference¶
We give suggestions, and we indicate the cost and the price, so the client can choose to propose it to the consumer based on the business rules
What are Suggestions?
A suggestion is a proposed timeslot for an Event to be planned. The suggestion includes cost and price. Based on your business rules you can now make a decision whether you want to pick it or not.
When suggestions are generated for the events?
For an event to receive suggestions, it has to be at planned state.
Then, it is possible to request for suggestions, it is really important to send the query param: current_state=new. In this way, the suggestions are going to be 100% up to date with the entire plan.
Suggestions Entity Reference¶
| Name | Format | Description | Required | Example |
|---|---|---|---|---|
| id | GUID | Unique suggestion reference that is generated by the system | N/A | 122222f0-5e73-447c-9022-07ec409921c6 |
| timeslot | Array of Strings | An array containing two dates times | N/A | ["2017-11-13T12:00:00Z","2017-11-13T17:30:00Z"] |
| created | Date-time | The Date-time in which the Suggestion was created | N/A | 2017-11-13T14:30:00Z |
| modified | Date-time | The Date-time in which the Suggestion was modified last time | N/A | 2017-11-13T14:30:00Z |
| cost | Float | The cost of this suggestion timeslot in the case it is approved, which is the sum of distance, time and vehicle costs | N/A | 3601.0 |
| price | Float | This value is deprecated in API v2 | N/A | 210.2 |
| event | GUID | The Event Guid where the Suggestion belongs to | N/A | 2227b2f0-5e73-447c-9022-07ec409921c6 |
| bucket_id | GUID | The Bucket Guid where the Suggestion belongs to | N/A | c7e5ec8c-3ab8-41b6-b91b-0a215ed25321 |
| current_state | String | The name of the current suggestion state | N/A | new |
| old_state | String | The name of the previous suggestion state | N/A | empty |
| state_reason | String | The cause of the current state, useful to troubleshoot when the entity reaches an error state | N/A | approving/suggestion/391a3fe7-6dc8-4c4f-9d2a-1cb84ac55e31/nopicks |
States¶
New¶
The suggestion is brand new, it is ready to be approved as a delivery timeslost.
Approving¶
This is an internal state. The suggestion is currently in the process of being approved. When this process finishes, the suggestion will move to Approved or Errored.
Approved¶
The suggestions are approved, so this suggestion is the one used to define the timeslot in which the delivery will happen.
Declined¶
At this state, the suggestion is not valid anymore. The reasons to decline a suggestion are:
- The event the suggestion belongs to is cancelled or errored.
- New suggestions were generated for the same event.
- Another suggestion is approved for the same event.
Errored¶
An error has happened in some of the processes related to this suggestion and was cancelled due to error or there was an error in the suggestion generation itself. See more about potential errors here.
Examples¶
Find the examples here.