Introduzione
La piattaforma PonyU è pensata per essere integrata e per offrire servizi ad altre piattaforme, per cui tutte le capability sono esposte in forma di RESTful service. La piattaforma PonyU realizza quindi un'infrastruttura SaaS che mette a disposizione un insieme di servizi che posso essere fruiti under the hood da una piattaforma terza, realizzando così un sistema collaborativo rebrandable (white label) B2B.
In generale tutti i RESTful service esposti rispettano il livello 2 del Richardson Maturity Model, ovvero:
esistono URI diverse per risorse diverse
i verbi http hanno semantica sulle risorse
gli status http fanno parte della RESTful api
Tutti i servizi consumano e producono JSON e usano i verbi http con la semantica riportata in tabella.
HTTP Verb
CRUD
Entire Collection (e.g. /customers)
Specific Item (e.g. /customers/{id})
POST
Create
201 (Created), 'Location' header with link to /customers/{id} containing new ID.
404 (Not Found), 409 (Conflict) if resource already exists.
GET
Read
200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists.
404 (Not Found), 409 (Conflict) if resource already exists.
PUT
Update
404 (Not Found), unless you want to update/replace every resource in the entire collection.
200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
PATCH
Partial Update
404 (Not Found), unless you want to update/replace every resource in the entire collection.
200 (OK). 404 (Not Found), if ID not found or invalid.
DELETE
Delete
404 (Not Found), unless you want to delete the whole collection - not often desirable.
200 (OK). 404 (Not Found), if ID not found or invalid.
Autenticazione # With shell, you can just pass the correct header with each request
curl 'api_endpoint_here' \
-H 'api_key: THE_API_KEY'
Tutte le API sono protette mediante un meccanismo di autenticazione basato su api key.
L'api key deve essere passata su tutte le richieste tramite l'header http api_key
come mostrato nell'esempio
THE_API_KEY
deve essere sostituito con l'api key fornita.
Scalabilità, affidabilità e resilienza
La piattaforma PonyU è interamente deployata in cloud, questo garantisce funzionalità di disponibilità elevata, ripristino di emergenza e backup, ridondanze a livello di macchina virtuale, data center e area, creazione automatica di repliche all'aumento del carico.
Notifiche
L'intero processo di delivery, dalla creazione dell'ordine alla consegna, prevede l'invio di notifiche agli stakeholder del processo. Le notifiche sono altamente configurabili e possono essere inviate su diversi canali: Push, SMS, e-mail.
API Creazione spedizione (DEPRECATO) curl -X POST 'https://api.ponyu.it/ponyu/v2/secured/shipments' \
-H 'api_key: THE_API_KEY' \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-d '{
"customerOrderId":1234,
"orderId":"C2234S74F",
"order":{
"note":"consegnate il prima possibile",
"pickupDueDate":"2020-06-22T13:00:00+02:00",
"requestedDeliveryRangeStartDate":"2020-06-22T13:15:00+02:00",
"requestedDeliveryRangeEndDate":"2020-06-22T13:25:00+02:00",
"promptAsap":true,
"orderAssembly":true,
"immediateReturn":false
},
"senderInfo":{
"email":"mario.rossi@email.com",
"name":"Mario Rossi",
"address":"Via della Moscova 1",
"addressInfo":"primo piano",
"city":"Milano",
"postcode":"20121",
"country":"Italia",
"phoneNumber":"3337654321"
},
"customerInfo":{
"email":"giuseppe.verdi@email.com",
"name":"Giuseppe Verdi",
"address":"Via della Moscova 34",
"addressInfo":"Citofonare 1004",
"city":"Milano",
"postcode":"20121",
"country":"Italia",
"phoneNumber":"3331234567"
},
"orderItems":[
{
"item":{
"name":"Aglianico del Vulture DOC 2017 Jéroboam - Elena Fucci (Cassetta di legno)",
"price":180.0,
"barcode":"1234",
"shelfPosition":"A12/3",
"imageUrl":"https://catalogovini.it/image.jpg"
},
"quantity":1
}
],
"shipmentPacks": [
{
"name": "pacco 1",
"barcode": "1234567890",
"weight": 10,
"size": 1
}
],
"paymentInfo":{
"cashOnDelivery":true,
"deliveryCharge":2.9,
"total":180.0
}
}'
Il comando qui sopra restituisce una risposta simile a questa:
{
"Id" : 12300123 ,
"Message" : "Order Created" ,
"OrderId" : "C2234S74F" ,
"TrackingCode" : "TRX1234" ,
"Timestamp" : "1599066584582" ,
"ConfirmedPickupDueDate" : "2020-06-22T13:00:00+02:00" ,
"ConfirmedRequestedDeliveryRangeStartDate" : "2020-06-22T13:15:00+02:00" ,
"ConfirmedRequestedDeliveryRangeEndDate" : "2020-06-22T13:25:00+02:00" ,
"ConfirmedRequestedDeliveryDate" : "2020-06-22T13:25:00+02:00"
}
Esempio di risposta di errore 400 in caso di capacità esaurita:
{
"Timestamp" : "1599066584582" ,
"Errors" :[
{
"code" : "no_available_ts" ,
"message" : "The requested pickup due date exceeds the next available pickup"
}
],
"OrderId" : "C2234S74F"
}
DEPRECATO IN FAVORE DI Creazione spedizione
Questo endpoint crea una spedizione.
HTTP Request
POST /v2/secured/shipments
Request Body
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
customerOrderId
no
long
-
id fisico sulla piattaforma del partner
orderId
sì
string
lunghezza massima 255
codice dell'ordine
order
sì
OrderRange
-
dettagli dell'ordine
senderInfo
sì
SenderInfo
-
informazioni del mittente
customerInfo
sì
CustomerInfo
-
informazioni del destinatario
orderItems
no
< OrderItem > array
-
lista di elementi che compongono l'ordine
shipmentPacks
no
< ShipmentPackTO > array
-
lista dei colli che compongono la spedizione
paymentInfo
sì
PaymentInfo
-
dettagli sul pagamento
Response
Attributo
Tipo
Descrizione
Id
long
id della spedizione sulla piattaforma PonyU
Message
string
messaggio descrittivo dell'operazione
OrderId
string
id dell'ordine dato in input
TrackingCode
string
tracking code della spedizione
Timestamp
string
timestamp dell'operazione
ConfirmedPickupDueDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
orario di ritiro
ConfirmedRequestedDeliveryDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
orario di consegna
ConfirmedRequestedDeliveryRangeStartDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
inizio della fascia di consegna richiesta
ConfirmedRequestedDeliveryRangeEndDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
fine della fascia di consegna richiesta
Errors
< Error > array
lista di errori, presente solo in caso di errore
Response status
Http Status
Error Code
Descrizione
201
-
Risorsa creata
400
bad_request
Errore relativo ad una richiesta errata
400
order_into_the_past
La richiesta ha la data di delivery nel passato
400
no_available_ts
La pickup due date non è (più) disponibile
400
full_delivery_range
Capacità esaurita, non c’è più disponibilità per la creazione delle spedizioni
400
bad_address
L'ordine contiene un indirizzo che non può essere processato e/o non è stato riconosciuto
500
-
Errore generico interno
Creazione spedizione curl -X POST 'https://api.ponyu.it/ponyu/v3/secured/shipments' \
-H 'api_key: THE_API_KEY' \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-d '{
"customerOrderId":1234,
"orderId":"C2234S74F",
"order":{
"note":"consegnate il prima possibile",
"pickupDueDate":"2020-06-22T13:00:00+02:00",
"requestedDeliveryRangeStartDate":"2020-06-22T13:15:00+02:00",
"requestedDeliveryRangeEndDate":"2020-06-22T13:25:00+02:00",
"promptAsap":true,
"orderAssembly":true,
"immediateReturn":false
},
"senderInfo":{
"email":"mario.rossi@email.com",
"name":"Mario Rossi",
"address":"Via della Moscova 1",
"addressInfo":"primo piano",
"city":"Milano",
"postcode":"20121",
"country":"Italia",
"phoneNumber":"3337654321"
},
"customerInfo":{
"email":"giuseppe.verdi@email.com",
"name":"Giuseppe Verdi",
"address":"Via della Moscova 34",
"addressInfo":"Citofonare 1004",
"city":"Milano",
"postcode":"20121",
"country":"Italia",
"phoneNumber":"3331234567"
},
"orderItems":[
{
"item":{
"name":"Aglianico del Vulture DOC 2017 Jéroboam - Elena Fucci (Cassetta di legno)",
"price":180.0,
"barcode":"1234",
"shelfPosition":"A12/3",
"imageUrl":"https://catalogovini.it/image.jpg"
},
"quantity":1
}
],
"shipmentPacks": [
{
"name": "pacco 1",
"barcode": "1234567890",
"weight": 10,
"size": 1
}
],
"paymentInfo":{
"cashOnDelivery":true,
"deliveryCharge":2.9,
"total":180.0
}
}'
Il comando qui sopra restituisce una risposta simile a questa:
{
"id" : 133941312 ,
"distance" : 3.08 ,
"timestamp" : "2022-05-11T10:57:22+02:00" ,
"message" : "Order Created" ,
"orderId" : "C2234S74F" ,
"confirmedPickupDueDate" : "2022-05-11T22:05:00+02:00" ,
"confirmedRequestedDeliveryDate" : "2022-05-11T22:30:00+02:00" ,
"confirmedRequestedDeliveryRangeStartDate" : "2022-05-11T22:20:00+02:00" ,
"confirmedRequestedDeliveryRangeEndDate" : "2022-05-11T22:30:00+02:00" ,
"shipmentPacks" : [
{
"name" : "pacco 1" ,
"barcode" : "1234567890" ,
"weight" : 10 ,
"size" : 1
}
]
}
Esempio di risposta di errore 400 in caso di capacità esaurita:
{
"timestamp" : "2022-05-11T10:42:52+02:00" ,
"message" : "Time slot no more available" ,
"errors" : [
{
"code" : "no_available_ts" ,
"message" : "The requested pickup due date exceeds the next available pickup"
}
],
"orderId" : "C2234S74F"
}
Questo endpoint crea una spedizione.
HTTP Request
POST /v3/secured/shipments
Request Body
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
customerOrderId
no
long
-
id fisico sulla piattaforma del partner
orderId
sì
string
lunghezza massima 255
codice dell'ordine
order
sì
OrderRange
-
dettagli dell'ordine
senderInfo
sì
SenderInfo
-
informazioni del mittente
customerInfo
sì
CustomerInfo
-
informazioni del destinatario
orderItems
no
< OrderItem > array
-
lista di elementi che compongono l'ordine
shipmentPacks
no
< ShipmentPackTO > array
-
lista dei colli che compongono la spedizione
paymentInfo
sì
PaymentInfo
-
dettagli sul pagamento
reservationId
no
string
-
id della prenotazione. I valori della prenotazione di pickupDate, deliveryDate start e deliveryDate end, sovrascrivono gli stessi presenti in OrderRange (Se la prenotazione esiste e non è scaduta)
Response
Attributo
Tipo
Descrizione
id
long
id della spedizione sulla piattaforma PonyU
message
string
messaggio descrittivo dell'operazione
orderId
string
id dell'ordine dato in input
trackingCode
string
tracking code della spedizione
timestamp
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
timestamp dell'operazione
confirmedPickupDueDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ss
orario di ritiro
confirmedRequestedDeliveryDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
orario di consegna
confirmedRequestedDeliveryRangeStartDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
inizio della fascia di consegna richiesta
confirmedRequestedDeliveryRangeEndDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
fine della fascia di consegna richiesta
shipmentPacks
< ShipmentPackTO > array
lista dei colli che compongono la spedizione. Nel caso in cui sia attiva la LDV digitale, il barcode sarà generato in automatico
errors
< Error > array
lista di errori, presente solo in caso di errore
Response status
Http Status
Error Code
Descrizione
201
-
Risorsa creata
400
bad_request
Errore relativo ad una richiesta errata
400
order_into_the_past
La richiesta ha la data di delivery nel passato
400
no_available_ts
La pickup due date non è (più) disponibile
400
full_delivery_range
Capacità esaurita, non c’è più disponibilità per la creazione delle spedizioni
400
bad_address
L'ordine contiene un indirizzo che non può essere processato e/o non è stato riconosciuto
400
invalid_delivery_slot_reservation
La prenotazione della fascia di consegna non è valida
500
-
Errore generico interno
Prossimo orario disponibile per il ritiro (DEPRECATO) curl -X GET 'https://api.ponyu.it/ponyu/v2/secured/next-available-pickup?latitude=41.7400043&longitude=14.6950002' \
-H 'api_key: THE_API_KEY' \
-H 'accept: application/json'
Il comando qui sopra restituisce una risposta simile a questa:
{
"zoneName" : "Roma" ,
"value" : "2020-06-22T13:00:00+02:00"
}
DEPRECATO IN FAVORE DI Prossimi orari disponibili per il ritiro e la consegna
Questo endpoint restituisce il prossimo orario disponibile per il pickup.
HTTP Request
GET /v2/secured/next-available-pickup?latitude={latitude}&longitude={longitude}
Query parameters
Attributo
Obbligatorio
Tipo
Descrizione
latitude
sì
double
latitudine del punto di ritiro
longitude
sì
double
longitudine del punto di ritiro
Response
Attributo
Tipo
Constraint
Descrizione
zoneName
string
lunghezza massima 255
il nome della zona a cui afferiscono le coordinate
value
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
il prossimo orario di pickup disponibile
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
-
Richiesta non valida
500
-
Errore generico interno
Prossimi orari disponibili per il ritiro e la consegna curl -X GET 'https://api.ponyu.it/ponyu/v1/secured/next-available-delivery-slots?latitude=45.468053&longitude=9.195386&date=2022-05-10' \
-H 'api_key: THE_API_KEY' \
-H 'accept: application/json'
Il comando qui sopra restituisce una risposta simile a questa:
{
"zone" : "Milano Sud" ,
"nap" : "2022-05-11T12:30:00+02:00" ,
"nadStart" : "2022-05-11T12:45:00+02:00" ,
"nadEnd" : "2022-05-11T12:55:00+02:00" ,
"timeSlots" : [
{
"pickupDate" : "2022-05-11T12:30:00+02:00" ,
"deliveryDateStart" : "2022-05-11T12:45:00+02:00" ,
"deliveryDateEnd" : "2022-05-11T12:55:00+02:00"
},
{
"pickupDate" : "2022-05-11T12:40:00+02:00" ,
"deliveryDateStart" : "2022-05-11T12:55:00+02:00" ,
"deliveryDateEnd" : "2022-05-11T13:05:00+02:00"
},
{
"pickupDate" : "2022-05-11T12:50:00+02:00" ,
"deliveryDateStart" : "2022-05-11T13:05:00+02:00" ,
"deliveryDateEnd" : "2022-05-11T13:15:00+02:00"
},
{
"pickupDate" : "2022-05-11T14:00:00+02:00" ,
"deliveryDateStart" : "2022-05-11T14:15:00+02:00" ,
"deliveryDateEnd" : "2022-05-11T14:25:00+02:00"
},
{
"pickupDate" : "2022-05-11T14:10:00+02:00" ,
"deliveryDateStart" : "2022-05-11T14:25:00+02:00" ,
"deliveryDateEnd" : "2022-05-11T14:35:00+02:00"
},
{
"pickupDate" : "2022-05-11T14:20:00+02:00" ,
"deliveryDateStart" : "2022-05-11T14:35:00+02:00" ,
"deliveryDateEnd" : "2022-05-11T14:45:00+02:00"
}
]
}
Questo endpoint restituisce i prossimi orari disponibili per il pickup e la delivery.
HTTP Request
GET /v1/secured/next-available-delivery-slots?latitude={latitude}&longitude={longitude}&date={date}
Query parameters
Attributo
Obbligatorio
Tipo
Descrizione
latitude
sì
double
latitudine del punto di ritiro
longitude
sì
double
longitudine del punto di ritiro
date
no
string (date-time) formato yyyy-MM-dd
il giorno per il quale vengono richieste le disponibiltà degli orari di consegna, se non specificato è inteso il giorno corrente
Response
Attributo
Tipo
Constraint
Descrizione
zone
string
lunghezza massima 255
il nome della zona a cui afferiscono le coordinate
nap
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
il prossimo orario di pickup disponibile (nap = next available pickup)
nadStart
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
il prossimo orario di inizio fascia di delivery disponibile (nadStart = next available delivery Start)
nadEnd
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
il prossimo orario di fine fascia di delivery disponibile (nadEnd = next available delivery End)
timeSlots
< DeliverySlotTO > array
-
lista dei prossimi orari disponibili per il pickup e la delivery
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
-
Richiesta non valida
500
-
Errore generico interno
Prossimi orari disponibili per il ritiro e la consegna (Raggruppati per tipologia) curl -X GET 'https://api.ponyu.it/ponyu/v1/secured/delivery-slots?senderLatitude=45.468053&senderLongitude=9.195386&receiverLatitude=45.468053&receiverLongitude=9.195386&date=2022-05-10&days=5' \
-H 'api_key: THE_API_KEY' \
-H 'accept: application/json'
Il comando qui sopra restituisce una risposta simile a questa:
[
{
"type" : "INSTANT" ,
"name" :[
{
"locale" : "it_IT" ,
"value" : "PonyU Instant"
},
{
"locale" : "en_US" ,
"value" : "PonyU Instant"
}
],
"description" :[
{
"locale" : "it_IT" ,
"value" : "Consegna in 90 minuti"
},
{
"locale" : "en_US" ,
"value" : "Delivery in 90 minutes"
}
],
"timeSlots" :[
{
"pickupDate" : "2022-07-11T12:30:00+02:00" ,
"deliveryDateStart" : "2022-07-11T12:45:00+02:00" ,
"deliveryDateEnd" : "2022-07-11T12:55:00+02:00"
}
]
},
{
"type" : "STANDARD" ,
"name" :[
{
"locale" : "it_IT" ,
"value" : "PonyU Standard"
},
{
"locale" : "en_US" ,
"value" : "PonyU Standard"
}
],
"description" :[
{
"locale" : "it_IT" ,
"value" : "Consegna in 4 ore"
},
{
"locale" : "en_US" ,
"value" : "Delivery in 4 ore"
}
],
"timeSlots" :[
{
"pickupDate" : "2022-07-11T09:00:00+02:00" ,
"deliveryDateStart" : "2022-07-11T09:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-11T13:00:00+02:00"
},
{
"pickupDate" : "2022-07-11T16:00:00+02:00" ,
"deliveryDateStart" : "2022-07-11T16:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-11T20:00:00+02:00"
}
]
},
{
"type" : "PREMIUM" ,
"name" :[
{
"locale" : "it_IT" ,
"value" : "PonyU Premium"
},
{
"locale" : "en_US" ,
"value" : "PonyU Premium"
}
],
"description" :[
{
"locale" : "it_IT" ,
"value" : "Consegna in 2 ore"
},
{
"locale" : "en_US" ,
"value" : "Delivery in 2 ore"
}
],
"timeSlots" :[
{
"pickupDate" : "2022-07-11T09:00:00+02:00" ,
"deliveryDateStart" : "2022-07-11T09:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-11T11:00:00+02:00"
},
{
"pickupDate" : "2022-07-11T11:00:00+02:00" ,
"deliveryDateStart" : "2022-07-11T11:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-11T13:00:00+02:00"
},
{
"pickupDate" : "2022-07-11T16:00:00+02:00" ,
"deliveryDateStart" : "2022-07-11T16:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-11T18:00:00+02:00"
},
{
"pickupDate" : "2022-07-11T18:00:00+02:00" ,
"deliveryDateStart" : "2022-07-11T18:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-11T20:00:00+02:00"
}
]
},
{
"type" : "NEXT" ,
"name" :[
{
"locale" : "it_IT" ,
"value" : "PonyU Next"
},
{
"locale" : "en_US" ,
"value" : "PonyU Next"
}
],
"description" :[
{
"locale" : "it_IT" ,
"value" : "Programma il giorno di consegna"
},
{
"locale" : "en_US" ,
"value" : "Schedule the delivery day"
}
],
"timeSlots" :[
{
"pickupDate" : "2022-07-12T09:00:00+02:00" ,
"deliveryDateStart" : "2022-07-12T09:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-12T13:00:00+02:00"
},
{
"pickupDate" : "2022-07-12T16:00:00+02:00" ,
"deliveryDateStart" : "2022-07-12T16:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-12T20:00:00+02:00"
},
{
"pickupDate" : "2022-07-13T09:00:00+02:00" ,
"deliveryDateStart" : "2022-07-13T09:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-13T13:00:00+02:00"
},
{
"pickupDate" : "2022-07-13T16:00:00+02:00" ,
"deliveryDateStart" : "2022-07-13T16:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-13T20:00:00+02:00"
},
{
"pickupDate" : "2022-07-14T09:00:00+02:00" ,
"deliveryDateStart" : "2022-07-14T09:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-14T13:00:00+02:00"
},
{
"pickupDate" : "2022-07-14T16:00:00+02:00" ,
"deliveryDateStart" : "2022-07-14T16:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-14T20:00:00+02:00"
},
{
"pickupDate" : "2022-07-15T09:00:00+02:00" ,
"deliveryDateStart" : "2022-07-15T09:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-15T13:00:00+02:00"
},
{
"pickupDate" : "2022-07-15T16:00:00+02:00" ,
"deliveryDateStart" : "2022-07-15T16:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-15T20:00:00+02:00"
},
{
"pickupDate" : "2022-07-16T09:00:00+02:00" ,
"deliveryDateStart" : "2022-07-16T09:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-16T13:00:00+02:00"
},
{
"pickupDate" : "2022-07-16T16:00:00+02:00" ,
"deliveryDateStart" : "2022-07-16T16:00:00+02:00" ,
"deliveryDateEnd" : "2022-07-16T20:00:00+02:00"
}
]
}
]
Questo endpoint restituisce i prossimi orari disponibili per il pickup e la delivery.
HTTP Request
GET /v1/secured/delivery-slots?senderLatitude={senderLatitude}&senderLongitude={senderLongitude}&receiverLatitude={receiverLatitude}&receiverLongitude={receiverLongitude}&date={date}&days=5
Query parameters
Attributo
Obbligatorio
Tipo
Descrizione
senderLatitude
sì
double
latitudine del punto di ritiro
senderLongitude
sì
double
longitudine del punto di ritiro
receiverLatitude
sì
double
latitudine del punto di consegna
receiverLongitude
sì
double
longitudine del punto di consegna
date
no
string (date-time) formato yyyy-MM-dd
il giorno per il quale si richiedono le disponibiltà degli orari di consegna, se non specificato è inteso il giorno corrente
days
no
integer
numero di giorni per i quali si richiedono le disponibiltà degli orari di consegna
Response
Attributo
Tipo
Constraint
Descrizione
type
string
lunghezza massima 255
tipologia della proposta di consegna
name
< LocalizedValueTO > array
lunghezza massima 255
nome della proposta di consegna
description
< LocalizedValueTO > array
lunghezza massima 255
descrizione della proposta di consegna
timeSlots
< DeliverySlotTO > array
-
lista dei prossimi orari disponibili per il pickup e la delivery
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
-
Richiesta non valida
500
-
Errore generico interno
Prenotazione fascia di consegna curl -X POST 'https://api.ponyu.it/ponyu/v1/secured/delivery-slot-reservation' \
-H 'api_key: THE_API_KEY' \
-H 'accept: application/json'
-d '{
"latitude":45.468053,
"longitude":9.195386,
"pickupDate":"2022-07-16T16:00:00+02:00",
"deliveryDateStart":"2022-07-16T16:00:00+02:00",
"deliveryDateEnd":"2022-07-16T20:00:00+02:00",
"instant": true
}'
Il comando qui sopra restituisce una risposta simile a questa:
{
"reservationId" : "9cc96ed4-144c-4ad7-a9e0-80f0dfb47d01-1661355232655" ,
"reservationExpiresAt" : "2022-07-15T12:30:00+02:00" ,
"reservationExpiresIn" : 30
}
Questo endpoint prenota una fascia di consegna.
HTTP Request
POST /v1/secured/delivery-slot-reservation
Request Body
Attributo
Obbligatorio
Tipo
Descrizione
latitude
sì
double
latitudine del punto di ritiro
longitude
sì
double
longitudine del punto di ritiro
pickupDate
sì
string (date-time) formato yyyy-MM-dd'T'HH:mm:ss
data di ritiro della fascia da prenotare
deliveryDateStart
sì
string (date-time) formato yyyy-MM-dd'T'HH:mm:ss
inizo della fascia di consegna da prenotare
deliveryDateEnd
sì
string (date-time) formato yyyy-MM-dd'T'HH:mm:ss
fine della fascia di consegna da prenotare
instant
no
boolean
con il valore true viene identificato lo slot come di tipo instant
Response
Attributo
Tipo
Descrizione
reservationId
string
id della prenotazione
reservationExpiresAt
string (date-time) formato yyyy-MM-dd'T'HH:mm:ss
data di scadenza della prenotazione
reservationExpiresIn
long
minuti entro i quali la prenotazione scadrà
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
-
Fascia di consegna non prenotabile o errata
500
-
Errore generico interno
Rinnovo della prenotazione della fascia di consegna curl -X POST 'https://api.ponyu.it/ponyu/v1/secured/delivery-slot-reservation/9cc96ed4-144c-4ad7-a9e0-80f0dfb47d01-1661355232655/renew' \
-H 'api_key: THE_API_KEY' \
-H 'accept: application/json'
Il comando qui sopra restituisce una risposta simile a questa:
{
"reservationId" : "9cc96ed4-144c-4ad7-a9e0-80f0dfb47d01-1661355232655" ,
"reservationExpiresAt" : "2022-05-11T10:57:22+02:00" ,
"reservationExpiresIn" : 30
}
Questo endpoint rinnova la prenotazione di una fascia di consegna.
HTTP Request
POST /v1/secured/delivery-slot-reservation/{reservationId}/renew
Path parameters
Attributo
Obbligatorio
Tipo
Descrizione
reservationId
sì
string
id della prenotazione
Response
Attributo
Tipo
Descrizione
reservationId
string
id della prenotazione
reservationExpiresAt
string (date-time) formato yyyy-MM-dd'T'HH:mm:ss
data di scadenza della prenotazione
reservationExpiresIn
long
minuti entro i quali la prenotazione scadrà
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
-
Prenotazione non rinnovabile
404
-
Prenotazione non trovata
500
-
Errore generico interno
Annullamento della prenotazione della fascia di consegna curl -X DELETE 'https://api.ponyu.it/ponyu/v1/secured/delivery-slot-reservation/9cc96ed4-144c-4ad7-a9e0-80f0dfb47d01-1661355232655' \
-H 'api_key: THE_API_KEY' \
-H 'accept: application/json'
Il comando qui sopra restituisce una risposta simile a questa:
{
"reservationId" : "9cc96ed4-144c-4ad7-a9e0-80f0dfb47d01-1661355232655" ,
"reservationExpiresAt" : "2022-05-11T10:57:22+02:00" ,
"reservationExpiresIn" : 30
}
Questo endpoint annulla la prenotazione di una fascia di consegna.
HTTP Request
DELETE /v1/secured/delivery-slot-reservation/{reservationId}
Path parameters
Attributo
Obbligatorio
Tipo
Descrizione
reservationId
sì
string
id della prenotazione
Response status
Http Status
Error Code
Descrizione
200
-
OK
404
-
Prenotazione non trovata
500
-
Errore generico interno
Zone curl -X GET 'https://api.ponyu.it/ponyu/secured/sender-service-zones?latitude=41.7400043&longitude=14.6950002' \
-H 'api_key: THE_API_KEY' \
-H 'accept: application/json'
Il comando qui sopra restituisce una risposta simile a questa:
[
{
"deliverySlots" : [
{
"pickupDate" : "2023-03-13T10:00:00+01:00" ,
"deliveryDateStart" : "2023-03-13T10:00:00+01:00" ,
"deliveryDateEnd" : "2023-03-13T14:00:00+01:00" ,
"nOrders" : 10 ,
"cutoffPeriod" : 120 ,
"cutoff" : "2023-03-13T08:00:00+01:00"
},
{
"pickupDate" : "2023-03-13T16:00:00+01:00" ,
"deliveryDateStart" : "2023-03-13T16:00:00+01:00" ,
"deliveryDateEnd" : "2023-03-13T20:00:00+01:00" ,
"nOrders" : 10 ,
"cutoffPeriod" : 120 ,
"cutoff" : "2023-03-13T14:00:00+01:00"
}
],
"name" : "Roma" ,
"senders" : [
{
"code" : "1" ,
"name" : "Mittente 1"
},
{
"code" : "2" ,
"name" : "Mittente 2"
}
]
}
]
Questo endpoint verifica se le coordinate di un punto di consegna rientrano in una zona servita, inoltre restituisce gli orari disponibili per il ritiro e la consegna.
HTTP Request
GET /secured/sender-service-zones?latitude={latitude}&longitude={longitude}&date={date}&minSlotsNum={minSlotsNum}
Query parameters
Attributo
Obbligatorio
Tipo
Descrizione
latitude
sì
double
latitudine del punto di consegna
longitude
sì
double
longitudine del punto di consegna
date
no
string (date-time) formato yyyy-MM-dd
data per la quale si vogliono recuperare le fasce di consegna, se non passato si intende il giorno corrente
minSlotsNum
no
integer
numero minimo di slot richiesti
minCutoff
no
integer
filtra gli slot rimuovendo quelli il cui cutoff scade a meno di minCutoff
minuti
minOrdersNum
no
integer
filtra gli slot rimuovendo quelli il cui numero residuo di ordini è minore del valore richiesto
Response
Attributo
Tipo
Descrizione
-
< ZoneTO > array
lista delle zone a cui afferiscono le coordinate
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
-
Formato coordinate errato
500
-
Errore generico interno
Stampa lettera di vettura curl -X GET 'https://api.ponyu.it/ponyu/secured/shipments/12300123/waybill' \
-H 'api_key: THE_API_KEY' \
-H 'accept: application/json'
Il comando qui sopra restituisce una risposta simile a questa:
Il servizio restituisce un documento pdf.
Questo endpoint produce la lettera di vettura in formato pdf.
HTTP Request
GET /secured/shipments/{shipmentId}/waybill
Path parameters
Attributo
Obbligatorio
Tipo
Descrizione
shipmentId
sì
string
id della spedizione
Response
Attributo
Tipo
Descrizione
-
< byte > array
formato application/pdf
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
-
Richiesta non valida
400
-
Spedizione non trovata
500
-
Errore generico interno
Fasce di Consegna curl -X GET 'https://api.ponyu.it/ponyu/secured/delivery-shifts?date=2020-06-05' \
-H 'api_key: THE_API_KEY' \
-H 'accept: application/json'
Il comando qui sopra restituisce una risposta simile a questa:
[
{
"startTime" : "09:00:00" ,
"endTime" : "13:00:00" ,
"nOrders" : 30 ,
"cutoffPeriod" : 120
},
{
"startTime" : "14:00:00" ,
"endTime" : "19:00:00" ,
"nOrders" : 30 ,
"cutoffPeriod" : 120
}
]
Questo endpoint restituisce le fasce di consegna.
HTTP Request
GET /secured/delivery-shifts
Query parameters
Attributo
Obbligatorio
Tipo
Descrizione
date
no
string (date-time) formato yyyy-MM-dd
data per la quale si vogliono recuperare le fasce di consegna, se non passato si intende il giorno corrente
Response
Attributo
Tipo
Descrizione
-
< DeliveryShiftTO > array
lista delle fasce di consegna
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
-
Richiesta non valida o data errata
500
-
Errore generico interno
Modifica spedizione curl -X PATCH 'https://api.ponyu.it/ponyu//v2/secured/shipments/123' \
-H 'api_key: THE_API_KEY' \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-d '{
"order":{
"note":"consegnate il prima possibile",
"pickupDueDate":"2020-06-22T13:00:00+02:00",
"requestedDeliveryRangeStartDate":"2020-06-22T13:15:00+02:00",
"requestedDeliveryRangeEndDate":"2020-06-22T13:25:00+02:00",
"promptAsap":true,
"orderAssembly":true,
"immediateReturn":false
},
"senderInfo":{
"email":"mario.rossi@email.com",
"name":"Mario Rossi",
"address":"Via della Moscova 1",
"addressInfo":"primo piano",
"city":"Milano",
"postcode":"20121",
"country":"Italia",
"phoneNumber":"3337654321"
},
"customerInfo":{
"email":"giuseppe.verdi@email.com",
"name":"Giuseppe Verdi",
"address":"Via della Moscova 34",
"addressInfo":"Citofonare 1004",
"city":"Milano",
"postcode":"20121",
"country":"Italia",
"phoneNumber":"3331234567"
},
"orderItems":[
{
"item":{
"name":"Aglianico del Vulture DOC 2017 Jéroboam - Elena Fucci (Cassetta di legno)",
"price":180.0,
"barcode":"1234",
"shelfPosition":"A12/3",
"imageUrl":"https://catalogovini.it/image.jpg"
},
"quantity":1
}
],
"paymentInfo":{
"cashOnDelivery":true,
"deliveryCharge":2.9,
"total":180.0
}
}'
Il comando qui sopra restituisce una risposta simile a questa:
{
"id" : 123 ,
"distance" : 3.08 ,
"timestamp" : "2022-05-11T10:57:22+02:00" ,
"message" : "Order Updated" ,
"orderId" : "C2234S74F" ,
"confirmedPickupDueDate" : "2022-05-11T22:05:00+02:00" ,
"confirmedRequestedDeliveryDate" : "2022-05-11T22:30:00+02:00" ,
"confirmedRequestedDeliveryRangeStartDate" : "2022-05-11T22:20:00+02:00" ,
"confirmedRequestedDeliveryRangeEndDate" : "2022-05-11T22:30:00+02:00"
}
Esempio di risposta di errore 400 in caso di capacità esaurita:
{
"timestamp" : "2022-05-11T10:42:52+02:00" ,
"message" : "Time slot no more available" ,
"errors" : [
{
"code" : "no_available_ts" ,
"message" : "The requested pickup due date exceeds the next available pickup"
}
],
"orderId" : "C2234S74F"
}
Questo endpoint modifica una spedizione se possibile. Vengono modificati solo gli attributi della spedizione presenti nella request.
HTTP Request
PATCH /v2/secured/shipments/{id}
Path parameters
Attributo
Obbligatorio
Tipo
Descrizione
id
sì
long
id della spedizione sulla piattaforma PonyU
Request Body
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
order
no
OrderRange
-
dettagli dell'ordine
senderInfo
no
SenderInfo
-
informazioni del mittente
customerInfo
no
CustomerInfo
-
informazioni del destinatario
orderItems
no
< OrderItem > array
-
lista di elementi che compongono l'ordine
paymentInfo
no
PaymentInfo
-
dettagli sul pagamento
Response
Attributo
Tipo
Descrizione
id
long
id della spedizione sulla piattaforma PonyU
message
string
messaggio descrittivo dell'operazione
orderId
string
id dell'ordine dato in input
trackingCode
string
tracking code della spedizione
timestamp
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
timestamp dell'operazione
confirmedPickupDueDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ss
orario di ritiro
confirmedRequestedDeliveryDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
orario di consegna
confirmedRequestedDeliveryRangeStartDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
inizio della fascia di consegna richiesta
confirmedRequestedDeliveryRangeEndDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ssX
fine della fascia di consegna richiesta
shipmentPacks
< ShipmentPackTO > array
lista dei colli che compongono la spedizione. Nel caso in cui sia attiva la LDV digitale, il barcode sarà generato in automatico
errors
< Error > array
lista di errori, presente solo in caso di errore
Response status
Http Status
Error Code
Descrizione
201
-
Risorsa creata
400
bad_request
Errore relativo ad una richiesta errata
400
order_into_the_past
La richiesta ha la data di delivery nel passato
400
no_available_ts
La pickup due date non è (più) disponibile
400
bad_address
L'ordine contiene un indirizzo che non può essere processato e/o non è stato riconosciuto
400
invalid_delivery_slot_reservation
La prenotazione della fascia di consegna non è valida
500
-
Errore generico interno
Annulla spedizione curl -X PUT 'https://api.ponyu.it/ponyu/secured/shipments/C2234S74F/cancel' \
-H 'api_key: THE_API_KEY' \
-H 'accept: application/json'
Il comando qui sopra restituisce una risposta simile a questa:
{
"Message" : "Operation Success" ,
"OrderId" : "C2234S74F" ,
"Timestamp" : "1599067134107"
}
Questo endpoint annulla una spedizione se possibile.
HTTP Request
PUT /secured/shipments/{orderId}/cancel
Path parameters
Attributo
Obbligatorio
Tipo
Descrizione
orderId
sì
string
codice dell'ordine
Response
Attributo
Tipo
Descrizione
Message
string
messaggio descrittivo dell'operazione
OrderId
string
codice dell'ordine
Timestamp
string
timestamp dell'operazione
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
-
Formato coordinate errato
404
-
Spedizione non trovata
500
-
Errore generico interno
Tracking curl -X GET 'https://api.ponyu.it/ponyu/v2/secured/tracking/PNY1234' \
-H 'api_key: THE_API_KEY' \
-H 'accept: application/json'
Il comando qui sopra restituisce una risposta simile a questa:
{
"senderName" : "Mario Rossi" ,
"orderId" : "1" ,
"deliveryAddress" :{
"address" : "Via Celimontana 17" ,
"city" : "Roma" ,
"province" : "RM" ,
"country" : "Italia" ,
"zipCode" : "00184" ,
"location" :{
"latitude" : 41.88847 ,
"longitude" : 12.49638
},
"partialMatch" : false ,
"fullAddress" : "Via Celimontana 17, 00184, Roma RM, Italia"
},
"pickupAddress" :{
"address" : "Via Leonina 18" ,
"city" : "Roma" ,
"province" : "RM" ,
"country" : "Italia" ,
"zipCode" : "00184" ,
"location" :{
"latitude" : 41.89483 ,
"longitude" : 12.49194
},
"partialMatch" : false ,
"fullAddress" : "Via Leonina 18, 00184, Roma RM, Italia"
},
"receiverName" : "Giuseppe Verdi" ,
"customerOrderId" : 1 ,
"lastPonyPosition" :{
"latitude" : 41.8948283 ,
"longitude" : 12.4919383
},
"trackingCode" : "PNY1234" ,
"shipmentStatus" : "PROGRESS"
}
Questo endpoint restitisce lo status tracking di una spedzione.
HTTP Request
GET /v2/secured/tracking/{trackingCode}
Path parameters
Attributo
Obbligatorio
Tipo
Descrizione
trackingCode
sì
string
tracking code
Response
Attributo
Tipo
Descrizione
trackingCode
string
tracking code
orderId
string
codice dell'ordine
customerOrderId
long
id fisico sulla piattaforma del partner
creationDate
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
data di creazione
pickupDueDateRangeStart
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
inizio della fascia di ritiro richiesta
pickupDueDateRangeEnd
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
fine della fascia di ritiro richiesta
requestedDeliveryDateRangeStart
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
inizio della fascia di consegna richiesta
requestedDeliveryDateRangeEnd
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
fine della fascia di consegna richiesta
assignedDate
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
data di assegnazione al driver
atPickupSiteDate
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
data di arrivo al mittente
pickupDate
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
data di ritiro
atDeliverySiteDate
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
data di arrivo al destinatario
deliveryDate
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
data di consegna
waitingDate
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
data in cui la spedzione è andata in WAITING
toReturnDate
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
data di inizio restituzione al mittente
atReturnSiteDate
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
data arrivo al mittente per la restituzione
returnedDate
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
data restituzione al mittente
waitingReason
enum (F01, F02, F03, F04, F05, F06, F07, F08, F09)
causale non consegnato
ponyReadyToGoForDelivery
boolean
specifica se il pony è in consegna: shipmentStatus == PROGRESS
&& ponyReadyToGoForDelivery == false
-> pacco ritirato ma non ancora in consegna; shipmentStatus == PROGRESS
&& ponyReadyToGoForDelivery == true
-> pacco ritirato e in consegna
ponyReadyToGoForDeliveryDate
string (date-time formato yyyy-MM-dd'T'HH:mm:ss.SSSX )
data in cui il pony va in consegna
receiverName
string
nome del destinatario
senderName
string
nome del mittente
deliveryAddress
GeoAddressTO
indirizzzo di consegna
pickupAddress
GeoAddressTO
indirizzo di ritiro
shipmentStatus
enum (REQUESTED, ASSIGNED, AT_PICKUP_SITE, PROGRESS, AT_DELIVERY_SITE, COMPLETED, CANCELLED, WAITING, TO_RETURN, AT_RETURN_SITE, RETURNED)
stato della spedizione
lastPonyPosition
LocationTO
ultima posizione del pony disponibile
Response status
Http Status
Error Code
Descrizione
200
-
OK
404
-
Spedizione non trovata
500
-
Errore generico interno
Aggiunta colli alla spedizione curl -X POST 'https://api.ponyu.it/ponyu/v2/secured/shipments/123/packs' \
-H 'api_key: THE_API_KEY' \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-d '[
{
"name": "pacco 1",
"barcode": "1234567890",
"weight": 10,
"size": 1
},
{
"name": "pacco 2",
"barcode": "0987654321",
"weight": 10,
"size": 1
}
]'
Il comando qui sopra restituisce una risposta simile a questa:
[
{
"name" : "pacco 1" ,
"barcode" : "1234567890" ,
"weight" : 10 ,
"size" : 1
},
{
"name" : "pacco 2" ,
"barcode" : "0987654321" ,
"weight" : 10 ,
"size" : 1
}
]
Questo endpoint aggiunge colli ad una spedzione già esistente.
HTTP Request
POST /v2/secured/shipments/{id}/packs
Path parameters
Attributo
Obbligatorio
Tipo
Descrizione
id
sì
long
id della spedizione sulla piattaforma PonyU
Request Body
Attributo
Obbligatorio
Tipo
Descrizione
-
sì
< ShipmentPackTO > array
lista dei colli da associare alla spedizione
Response
Attributo
Tipo
Descrizione
-
< ShipmentPackTO > array
lista dei colli che compongono la spedizione
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
-
La richiesta contiene dati non corretti
404
-
Spedizione non trovata
500
-
Errore generico interno
Webhook Webhook cambiamenti di stato
Di seguito un esempio di json postato al webhook:
{
"customerOrderId" : 123 ,
"orderId" : "C2234S74F" ,
"status" : "AT_PICKUP_SITE" ,
"operationDate" : "2020-06-22T11:15:00.000+02:00"
}
Tramite questo webhook vengono comunicati i cambiamenti di stato della spedizone. Di seguito viene drescitta la struttura dell'oggetto postato.
Attributo
Tipo
Descrizione
customerOrderId
long
id fisico sulla piattaforma del partner
orderId
string
codice dell'ordine
status
enum (REQUESTED, ASSIGNED, AT_PICKUP_SITE, PROGRESS, AT_DELIVERY_SITE, COMPLETED, CANCELLED, WAITING, TO_RETURN, AT_RETURN_SITE, RETURNED)
stato dell'ordine
operationDate
string (date-time) formato yyyy-MM-dd'T'HH:mm:ss.SSSX
timestamp dell'operazione
Webhook posticipi
Di seguito un esempio di json postato al webhook:
{
"customerOrderId" : 123 ,
"orderId" : "C2234S74F" ,
"pickupDueDate" : "2021-10-15T11:15:00.000+02:00" ,
"pickupDueDateRangeStart" : "2021-10-15T10:15:00.000+02:00" ,
"pickupDueDateRangeEnd" : "2021-10-15T11:15:00.000+02:00" ,
"requestedDeliveryDate" : "2021-10-15T14:30:00.000+02:00" ,
"requestedDeliveryDateRangeStart" : "2021-10-15T11:15:00.000+02:00" ,
"requestedDeliveryDateRangeEnd" : "2021-10-15T14:30:00.000+02:00" ,
"operationDate" : "2021-10-15T10:48:00.000+02:00"
}
Tramite questo webhook vengono comunicati i posticipi della spedizone. Di seguito viene drescitta la struttura dell'oggetto postato.
Servizi Express Calcolo del prezzo curl -X POST 'https://api.ponyu.it/ponyu/v2/secured/price/calculate' \
-H 'api_key: THE_API_KEY' \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-d '{
"additionalServices": ["STATE_SMS", "STATE_EMAIL", "PICKUP_PREFERENCE"],
"startPickupRange": "2020-06-13T10:00:00+0200",
"endPickupRange": "2020-06-13T11:00:00+0200",
"startDeliveryRange": "2020-06-13T16:00:00+0200",
"endDeliveryRange": "2020-06-13T17:00:00+0200",
"pickupAddress": {
"address": "Via della Moscova 1",
"city": "Milano",
"province": "MI",
"zipCode": "20121",
"location": {
"latitude": 45.47542,
"longitude": 9.19655
}
},
"deliveryAddress": {
"address": "Via della Moscova 34",
"city": "Milano",
"province": "MI",
"zipCode": "20121",
"location": {
"latitude": 45.47695,
"longitude": 9.18904
}
},
"items": [
{
"width": 20,
"length": 20,
"height": 20,
"weight": 2
}
]
}'
Il comando qui sopra restituisce una risposta simile a questa:
{
"price" : 4.90 ,
"canBeFulfilled" : true
}
Questo endpoint calcola il prezzo della spedizione.
HTTP Request
POST /v2/secured/price/calculate
Request Body
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
additionalServices
No
< string > array
enum (STATE_SMS, STATE_EMAIL, CASH_ON_DELIVERY, PICKUP_PREFERENCE)
Servizi aggiuntivi
pickupAddress
Sì
GeoAddressTO
-
Indirizzo di ritiro
deliveryAddress
Sì
GeoAddressTO
-
Indirizzo di consegna
startPickupRange
Sì
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
Inizio della fascia di ritiro richiesta
endPickupRange
Sì
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
Fine della fascia di ritiro richiesta
startDeliveryRange
Sì
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
Inizio della fascia di consegna richiesta
endDeliveryRange
Sì
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
Fine della fascia di consegna richiesta
items
Sì
< ItemTO > array
-
Colli della spedizione
Response
Attributo
Tipo
Descrizione
price
double
Servizi aggiuntivi
canBeFulfilled
boolean
Specifica se la spedizione può essere accettata
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
-
La richiesta contiene dati non corretti
500
-
Errore generico interno
Creazione spedizione curl -X POST 'https://api.ponyu.it/ponyu/v1/secured/express/shipments' \
-H 'api_key: THE_API_KEY' \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-d '{
"additionalServices": ["STATE_SMS", "PROXIMITY_SMS", "PICKUP_PREFERENCE"],
"customerOrderId":1234,
"orderId": "C2234S74F",
"sender": {
"name": "Mario Rossi",
"phoneNumber": "3337654321",
"email": "mario.rossi@email.com",
"address": "Via della Moscova 1",
"city": "Milano",
"country": "Italia",
"postcode": "20121",
"addressInfo": "Citofono Rossi, primo piano"
},
"receiver": {
"name": "Giuseppe Verdi",
"phoneNumber": "3331234567",
"email": "giuseppe.verdi@email.com",
"address": "Via della Moscova 34",
"city": "Milano",
"country": "Italia",
"postcode": "20121",
"addressInfo": "Citofonare 1004"
},
"pickupDueDateRangeStart":"2020-06-22T10:00:00+02:00",
"pickupDueDateRangeEnd":"2020-06-22T12:00:00+02:00",
"requestedDeliveryDateRangeStart":"2020-06-22T15:00:00+02:00",
"requestedDeliveryDateRangeEnd":"2020-06-22T20:00:00+02:00",
"note": "se non sono a casa lasciare al portiere",
"items": [
{
"reference": "Collo 1",
"width": 20.0,
"length": 5.0,
"height": 30.0,
"weight": 7.5,
"barcode": "123456789"
}
],
"price": 4.9,
"paymentInfo": {
"cashOnDelivery": true,
"deliveryCharge": 2.9,
"total": 12.9
}
}'
Il comando qui sopra restituisce una risposta simile a questa:
{
"additionalServices" :[ "STATE_SMS" , "PROXIMITY_SMS" , "PICKUP_PREFERENCE" ],
"orderId" : "C2234S74F" ,
"sender" :{
"name" : "Mario Rossi" ,
"phoneNumber" : "3337654321" ,
"email" : "mario.rossi@email.com" ,
"address" : "Via della Moscova 1" ,
"city" : "Milano" ,
"provinceCode" : "MI" ,
"country" : "Italia" ,
"postcode" : "20121" ,
"addressInfo" : "Citofono Rossi, primo piano" ,
"latitude" : 45.47542 ,
"longitude" : 9.19655
},
"receiver" :{
"name" : "Giuseppe Verdi" ,
"phoneNumber" : "3331234567" ,
"email" : "giuseppe.verdi@email.com" ,
"address" : "Via della Moscova 34" ,
"city" : "Milano" ,
"provinceCode" : "MI" ,
"country" : "Italia" ,
"postcode" : "20121" ,
"addressInfo" : "Citofonare 1004" ,
"latitude" : 45.47695 ,
"longitude" : 9.18904
},
"pickupDueDateRangeStart" : "2020-06-22T10:00:00+02:00" ,
"pickupDueDateRangeEnd" : "2020-06-22T12:00:00+02:00" ,
"requestedDeliveryDateRangeStart" : "2020-06-22T15:00:00+02:00" ,
"requestedDeliveryDateRangeEnd" : "2020-06-22T20:00:00+02:00" ,
"note" : "se non sono a casa lasciare al portiere" ,
"items" :[
{
"weight" : 7.5 ,
"width" : 20.0 ,
"length" : 5.0 ,
"height" : 30.0 ,
"type" : "PACK" ,
"barcode" : "123456789"
}
],
"price" : 4.9 ,
"paymentInfo" : {
"cashOnDelivery" : true ,
"deliveryCharge" : 2.9 ,
"total" : 12.9
}
}
Questo endpoint crea una spedizione.
HTTP Request
POST /v1/secured/express/shipments
Request Body
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
additionalServices
No
< string > array
enum (STATE_SMS, STATE_EMAIL, CASH_ON_DELIVERY, PICKUP_PREFERENCE)
Servizi aggiuntivi
orderId
Sì
string
lunghezza massima 255
Identificativo dell'ordine
sender
Sì
SenderInfo
-
Informazioni del mittente
receiver
Sì
CustomerInfo
-
Informazioni del destinatario
pickupDueDateRangeStart
Sì
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
Inizio della fascia di ritiro richiesta
pickupDueDateRangeEnd
Sì
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
Fine della fascia di ritiro richiesta
requestedDeliveryDateRangeEnd
Sì
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
Inizio della fascia di consegna richiesta
requestedDeliveryDateRangeStart
Sì
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
Fine della fascia di consegna richiesta
note
No
string
lunghezza massima 4000
Note
items
Sì
< ItemTO > array
-
Colli della spedizione
price
Sì
double
-
Prezzo della spedizione
paymentInfo
No
PaymentInfo
-
dettagli sul pagamento
Response
Attributo
Tipo
Constraint
Descrizione
additionalServices
< string > array
enum (STATE_SMS, STATE_EMAIL, CASH_ON_DELIVERY)
Servizi aggiuntivi
orderId
string
lunghezza massima 255
Identificativo dell'ordine
sender
SenderInfo
-
Informazioni del mittente
receiver
CustomerInfo
-
Informazioni del destinatario
pickupDueDateRangeStart
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
Inizio della fascia di ritiro richiesta
pickupDueDateRangeEnd
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
Fine della fascia di ritiro richiesta
requestedDeliveryDateRangeEnd
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ss.SSSX
Inizio della fascia di consegna richiesta
requestedDeliveryDateRangeStart
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ss.SSSX
Fine della fascia di consegna richiesta
note
string
lunghezza massima 4000
Note
items
< ItemTO > array
-
Colli della spedizione
price
double
-
Prezzo della spedizione
paymentInfo
PaymentInfo
-
dettagli sul pagamento
Response status
Http Status
Error Code
Descrizione
200
-
OK
400
SHP0011
Errore nei valori di delivery range
400
SHP0023
Dimensioni dei colli oltre i valori massimi
400
SHP0024
Mittente e/o destinatario fuori zona
400
SHP0025
Impossibile accettare l'ordine
400
SHP0026
Colli con dimensioni errate e/o nulle
400
SHP0027
Turni di consegna non definiti
400
SHP0031
Delivery range già iniziato
400
SHP0037
Errore nei valori di pickup range
400
SHP0038
Valori di pickup range non validi rispetto al delivery range
400
SHP0039
Pickup range già iniziato
400
SHP0040
Le date di pickup e delivery devono essere lo stesso giorno
500
-
Errore generico interno
Models Order
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
note
no
string
lunghezza massima 4000
Note dell'ordine
pickupDueDate
sì
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
orario di ritiro richiesto
requestedDeliveryDate
sì
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
orario di consegna
promptAsap
no
boolean
di default è false
indica se l'ordine deve essere consegnato il prima possibile
OrderRange
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
note
no
string
lunghezza massima 4000
Note dell'ordine
pickupDueDate
sì se non c'è deliverySlotReservationId
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
orario di ritiro richiesto
requestedDeliveryRangeStartDate
sì se non c'è deliverySlotReservationId
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
inizio della fascia di consegna richiesta
requestedDeliveryRangeEndDate
sì se non c'è deliverySlotReservationId
string (date-time)
formato yyyy-MM-dd'T'HH:mm:ssX
fine della fascia di consegna richiesta
deliverySlotReservationId
no
long
-
id della prenotazione delle fascia di ritiro/consegna
promptAsap
no
boolean
di default è false
indica se l'ordine deve essere consegnato il prima possibile
orderAssembly
no
boolean
di default è false
indica se l'ordine deve essere assemblato oltre che consegnato
immediateReturn
no
boolean
di default è false
indica se per l'ordine deve essere attivato il servzio accessorio di reso immediato
OrderItem
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
item
sì
Item
-
dettagli dell'item
quantity
sì
integer
-
numero di item
Item
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
name
sì
string
lunghezza massima 255
nome dell'item
price
sì
double
decimal(19,2)
prezzo dell'item
barcode
no
string
lunghezza massima 255
codice a barre del prodotto (obbligatorio per il picking)
shelfPosition
no
string
lunghezza massima 255
identificativo dello scaffale su cui è posizionato il prodotto (obbligatorio per il picking)
imageUrl
no
string
lunghezza massima 255
url dell'immagine del prodotto (obbligatorio per il picking)
ShipmentPackTO
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
name
sì
string
lunghezza massima 255
nome del collo
barcode
sì
string
lunghezza massima 255
codice a barre del collo
size
sì
integer
-
misura del collo es. 1 -> Small, 2 -> Medium, 3 -> Large
fridge
no
boolean
di default è false
indica se il prodotto deve essere trasportato a temperatura controllata
weight
sì
double
-
peso del collo
PaymentInfo
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
cashOnDelivery
sì
boolean
-
indica se l'ordine è in contanti
deliveryCharge
sì
double
decimal(19,2)
spese di consegna
total
sì
double
decimal(19,2)
totale dell'ordine escluse le spese di consegna
Error
Attributo
Tipo
Descrizione
code
string
codice dell'errore
message
string
descrizione dell'errore
SenderInfo
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
name
sì
string
lunghezza massima 255
Nome del mittente
phoneNumber
sì
string
lunghezza massima 255
Numero di telefono del mittente
email
no
string
lunghezza massima 255
Indirizzo email del mittente
address
sì
string
lunghezza massima 255
Via e numero civico del mittente
city
sì
string
lunghezza massima 255
Città del mittente
provinceCode
no
string
lunghezza massima 2
Sigla della provincia del mittente
country
no
string
lunghezza massima 255
Nazione del mittente
postcode
sì
string
lunghezza massima 5
CAP del mittente
addressInfo
no
string
lunghezza massima 255
Informazioni aggiuntive sull'indirizzo del mittente
CustomerInfo
Attributo
Obbligatorio
Tipo
Constraint
Descrizione
name
sì
string
lunghezza massima 255
Nome del destinatario
phoneNumber
sì
string
lunghezza massima 255
Numero di telefono del destinatario
email
no
string
lunghezza massima 255
Indirizzo email del destinatario
address
sì
string
lunghezza massima 255
Via e numero civico del destinatario
city
sì
string
lunghezza massima 255
Città del destinatario
provinceCode
no
string
lunghezza massima 2
Sigla della provincia del destinatario
country
no
string
lunghezza massima 255
Nazione del destinatario
postcode
sì
string
lunghezza massima 5
CAP del destinatario
addressInfo
no
string
Informazioni aggiuntive sull'indirizzo del destinatario
DeliverySlotTO
LocalizedValueTO
Attributo
Tipo
Descrizione
locale
string
locale in cui è espresso il valore
value
string
valore localizzato
ZoneTO
Attributo
Tipo
Descrizione
name
string
nome della zona
deliverySlots
< DeliverySlotTO > array
lista degli orari disponibili per il pickup e la delivery
senders
< SenderTO > array
lista mittenti della zona
SenderTO
Attributo
Tipo
Descrizione
name
string
nome della zona
code
string
codice del mittente
DeliveryShiftTO
Attributo
Tipo
Descrizione
startTime
string
inizio della fascia di consegna nel formato HH:mm:ss
endTime
string
fine della fascia di consegna nel formato HH:mm:ss
preparationTime
string
tempo massimo di preparazione concesso al merchant espresso in minuti
nOrders
int
ordini rimanenti in questa fascia di consegna
cutoffPeriod
int
cutoff in minuti prima dell’inizio della fascia
Stati spedizione
Codice
Descrizione
REQUESTED
Spedizione accettata
ASSIGNED
Spedizione assegnata ad un pony
AT_PICKUP_SITE
Pony arrivato al punto di ritiro
PROGRESS
Spedizione ritirata
AT_DELIVERY_SITE
Pony arrivato al punto di consegna
COMPLETED
Spedizione conegnata
CANCELLED
Spedizione annullata
WAITING
Spedizione in stato di attesa, non siamo riusciti a consegnare (es. cliente non trovato), da qui la spedizione potrebbe ritornare in consegna o andare in restituzione
TO_RETURN
Spedizione in restituzione al mittente
AT_RETURN_SITE
Pony arrivato al mittente per la restituzione
RETURNED
Spedizione resa
Causali non consegnato
Codice
Descrizione
F01
Destinatario assente
F02
Portineria chiusa
F03
Destinatario non presente su citofono
F04
Civico non trovato
F05
Pacco rifiutato
F06
Pagamento non ricevuto
F07
Recapito non tentato per cause di forza maggiore
F08
Rifiuto con riserva
F09
Indirizzo errato
Appendice Errori
Di seguito una lista generica di errori che possono essere restituiti dalle API:
HTTP Status
Descrizione
400
Bad Request -- Your request is invalid.
401
Unauthorized -- Your API key is wrong.
403
Forbidden -- You are not authorized to use the API.
404
Not Found -- The specified resource could not be found.
405
Method Not Allowed -- You tried to access a resource with an invalid method.
406
Not Acceptable -- You requested a format that isn't json.
429
Too Many Requests -- You're requesting too many resources! Slow down!
500
Internal Server Error -- We had a problem with our server. Try again later.
503
Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
Ambienti Staging Environment
URL
Authentication
https://staging.ponyu.it/ponyu
By api key
Production Environment
URL
Authentication
https://api.ponyu.it/ponyu
By api key
Date and Time Patterns
Date and time formats are specified by date and time pattern strings. Within date and time pattern strings, unquoted letters from 'A' to 'Z' and from 'a' to 'z' are interpreted as pattern letters representing the components of a date or time string. Text can be quoted using single quotes (') to avoid interpretation. "''" represents a single quote. All other characters are not interpreted; they're simply copied into the output string during formatting or matched against the input string during parsing.
The following pattern letters are defined (all other characters from 'A' to 'Z' and from 'a' to 'z' are reserved):
Letter
Date or Time Component
Presentation
Examples
G
Era designator
Text
AD
y
Year
Year
1996; 96
Y
Week year
Year
2009; 09
M
Month in year
Month
July; Jul; 07
w
Week in year
Number
27
W
Week in month
Number
2
D
Day in year
Number
189
d
Day in month
Number
10
F
Day of week in month
Number
2
E
Day name in week
Text
Tuesday; Tue
u
Day number of week (1 = Monday, ..., 7 = Sunday)
Number
1
a
Am/pm marker
Text
PM
H
Hour in day (0-23)
Number
0
k
Hour in day (1-24)
Number
24
K
Hour in am/pm (0-11)
Number
0
h
Hour in am/pm (1-12)
Number
12
m
Minute in hour
Number
30
s
Second in minute
Number
55
S
Millisecond
Number
978
z
Time zone
General time zone
Pacific Standard Time; PST; GMT-08:00
Z
Time zone
RFC 822 time zone
-0800
X
Time zone
ISO 8601 time zone
-08; -0800; -08:00
Examples
The following examples show how date and time patterns are interpreted in the U.S. locale. The given date and time are 2001-07-04 12:08:56 local time in the U.S. Pacific Time time zone.
Date and Time Pattern
Result
"yyyy.MM.dd G 'at' HH:mm:ss z"
2001.07.04 AD at 12:08:56 PDT
"EEE, MMM d, ''yy"
Wed, Jul 4, '01
"h:mm a"
12:08 PM
"hh 'o''clock' a, zzzz"
12 o'clock PM, Pacific Daylight Time
"K:mm a, z"
0:08 PM, PDT
"yyyyy.MMMMM.dd GGG hh:mm aaa"
02001.July.04 AD 12:08 PM
"EEE, d MMM yyyy HH:mm:ss Z"
Wed, 4 Jul 2001 12:08:56 -0700
"yyMMddHHmmssZ"
010704120856-0700
"yyyy-MM-dd'T'HH:mm:ss.SSSZ"
2001-07-04T12:08:56.235-0700
"yyyy-MM-dd'T'HH:mm:ssX"
2001-07-04T12:08:56-0700
"yyyy-MM-dd'T'HH:mm:ss.SSSXXX"
2001-07-04T12:08:56.235-07:00
"YYYY-'W'ww-u"
2001-W27-3