Callback status zamówienia¶
Callback status pozwala na aktualizację statusu zamówienia użytkownika w jego aplikacji. Poprawia to doświadczenie zakupowe klienta i zmniejsza prawdopodobieństwo jego kontaktu z biurem obsługi sklepu. Krok 12 na poniższym diagramie.
sequenceDiagram
autonumber
actor User
participant OpenApp
participant Merchant
Merchant->>User: Wyświetlenie widgetu OA
User->>+OpenApp: Pobranie koszyka
OpenApp->>+Merchant: Pobranie koszyka i opcji dostawy
Merchant->>-OpenApp: Zwrócenie koszyka i opcji dostawy
OpenApp->>-User: Zwrócenie koszyka
User->>User: Opcje checkoutu (dostawa itp)
User->>+OpenApp: Płatność i złożenie zamówienia
OpenApp->>OpenApp: Autoryzacja płatności
OpenApp->>+Merchant: Potwierdzenie płatności i złożenie zamówienia
Merchant->>-OpenApp: Potwierdzenie złożenia zamówienia
OpenApp->>-User: Potwierdzenie zamówienia
Merchant->>OpenApp: Callback fulfillmentowy
OpenApp->>User: Wysłanie powiadomieniaPoniżej znajduje się lista statusów zamówień dostępnych dla sklepów. Zmiana statusu na inny odbywa się jedynie przez wysłanie nowego statusu zamówienia.
- ORDERED oznacza status zamówienia skutecznie złożonego przez klienta i przyjętego przez backend sklepu,
- FULFILLED oznacza status zamówienia przygotowanego do wysyłki,
- SHIPPED oznacza status zamówienia wysłanego do klienta - odebranego przez kuriera lub wysłanego transportem własnym sklepu,
- READY_FOR_PICKUP oznacza status zamówienia dostarczonego do punktu odbioru - Paczkomatu/Orlen Paczka lub własnego punktu odbioru sklepu,
- DELIVERED oznacza status zamówienia odberanego przez klienta lub dostarczonego pod wskazany adres,
- CANCELLED_MERCHANT oznacza status zamówienia, które zostało anulowane przez sklep (dowolny powód). Status ten jest możliwy do moment przejścia zamówienia w status DELIVERED (zmiana dokonana przez sklep lub OpenApp)
Logiczna sekwencja zmian statusów (każdy z kroków może być pominięty):
NEW -> ORDERED -> FULFILLED -> SHIPPED -> READY_FOR_PICKUP -> DELIVERED
NEW -> ORDERED -> FULFILLED -> SHIPPED -> IN_DELIVERY -> DELIVERED
stateDiagram-v2
state if_state2 <<choice>>
[*] --> ORDERED
ORDERED --> FULFILLED
FULFILLED --> SHIPPED
SHIPPED --> if_state2
if_state2 --> READY_FOR_PICKUP: APM lub odbiór w sklepie
if_state2 --> IN_DELIVERY: dostawa kurierem
READY_FOR_PICKUP --> DELIVERED
IN_DELIVERY --> DELIVERED
DELIVERED --> [*]Zamówienie wysyłane w jednej wysyłce¶
Request¶
Aktualizacja statusu zamówienia dokonuje się wysyłając dane metodą POST na następujący endpoint:
Żądanie z danymi o aktualizacji fulfillmentu:
| Fulfillment update request | |
|---|---|
{
"additionalProperties": false,
"type": "object",
"properties": {
"oaOrderId": {
"type": "string",
"title": "oaOrderId"
},
"shopOrderId": {
"type": "string",
"title": "shopOrderId"
},
"status": {
"$ref": "#/definitions/StoreDeliveryStatus",
"title": "status"
},
"notes": {
"type": "string",
"title": "notes"
},
"shipping": {
"additionalProperties": false,
"$ref": "#/definitions/OrderShipment",
"title": "shipping"
}
},
"required": [
"notes",
"oaOrderId",
"shopOrderId",
"status"
],
"definitions": {
"StoreDeliveryStatus": {
"title": "StoreDeliveryStatus",
"enum": [
"CANCELLED_MERCHANT",
"DELIVERED",
"FULFILLED",
"IN_DELIVERY",
"ORDERED",
"READY_FOR_PICKUP",
"SHIPPED"
],
"type": "string"
},
"OrderShipment": {
"additionalProperties": false,
"title": "OrderShipment",
"type": "object",
"properties": {
"operator": {
"description": "The operator of the shipment",
"maxLength": 64,
"type": "string",
"title": "operator"
},
"trackingCode": {
"description": "The tracking code.",
"maxLength": 64,
"type": "string",
"title": "trackingCode"
},
"trackingUrl": {
"description": "The tracking URL.",
"maxLength": 255,
"type": "string",
"title": "trackingUrl"
}
}
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
Response¶
W odpowiedzi OpenApp potwierdzi przyjęcie zlecenia zmiany statusu.
Errors¶
| Error name | Code |
|---|---|
IncorrectDeliveryStatusException |
400 |
OrderNotFoundException |
404 |
MerchantOrderOwnershipException |
404 |
Zamówienie rozdzielane na kilka wysyłek (paczek)¶
Możliwe jest, że zamówienie klienta zostanie wysłane nie w jednej, ale w kilku wysyłkach (paczkach). Aby poinformować o tym OpenApp i klienta, należy użyć endpointu multi-fulfillment opisanego poniżej.
Warning
Po rozdzieleniu zamówienia na wiele wysyłek, nie można już korzystać z endpointu dla pojedyńczej wysyłki. Dodatkowo, każda stworzona wysyłka musi być obecna w kazdym zapytaniu do endpointu multi-fulfillment. Tak więc, jeśli zamówienie zostanie podzielone na 3 wysyłki, należy aktualizować statusy z 3 wysyłkami na liście. Jeśli zamówienie zostanie następnie podzielone na 2 wysyłki, konieczne jest wysyłanie do OpenApp 3 wysyłek (trzecia wysyłka może mieć oczywiście status cancelled).
Request¶
Request aktualizujący status jest wykonywany przez POST na następujęcy endpoint:
Treść requestu zawiera informacje o statusie fulfillmentu (realizacji)The:
{
"additionalProperties": false,
"type": "object",
"properties": {
"oaOrderId": {
"type": "string",
"title": "oaOrderId"
},
"shopOrderId": {
"type": "string",
"title": "shopOrderId"
},
"shipments": {
"description": "The shipments for the order",
"type": "array",
"items": {
"$ref": "#/definitions/OrderShipmentMulti"
},
"title": "shipments"
}
},
"required": [
"oaOrderId",
"shipments",
"shopOrderId"
],
"definitions": {
"OrderShipmentMulti": {
"additionalProperties": false,
"title": "OrderShipmentMulti",
"type": "object",
"properties": {
"shipmentId": {
"description": "The id of the shipment",
"maxLength": 64,
"type": "string",
"title": "shipmentId"
},
"status": {
"$ref": "#/definitions/StoreDeliveryStatus",
"description": "The status of the shipment",
"title": "status"
},
"notes": {
"description": "Optional merchant notes on the shipment",
"maxLength": 64,
"type": "string",
"title": "notes"
},
"products": {
"description": "The products which will be in this shipment",
"type": "array",
"items": {
"$ref": "#/definitions/OrderShipmentProduct"
},
"title": "products"
},
"timing": {
"description": "The estimation of the delivery time, i.e. 'next business day' or 'July 18th'.",
"maxLength": 40,
"type": "string",
"title": "timing"
},
"operator": {
"description": "The operator of the shipment",
"maxLength": 64,
"type": "string",
"title": "operator"
},
"trackingCode": {
"description": "The tracking code.",
"maxLength": 64,
"type": "string",
"title": "trackingCode"
},
"trackingUrl": {
"description": "The tracking URL.",
"maxLength": 255,
"type": "string",
"title": "trackingUrl"
}
},
"required": [
"shipmentId",
"status"
]
},
"StoreDeliveryStatus": {
"title": "StoreDeliveryStatus",
"enum": [
"CANCELLED_MERCHANT",
"DELIVERED",
"FULFILLED",
"IN_DELIVERY",
"ORDERED",
"READY_FOR_PICKUP",
"SHIPPED"
],
"type": "string"
},
"OrderShipmentProduct": {
"additionalProperties": false,
"title": "OrderShipmentProduct",
"type": "object",
"properties": {
"id": {
"description": "The unique ID of the product.",
"maxLength": 36,
"type": "string",
"title": "id"
},
"quantity": {
"description": "The number of items in the purchase.",
"minimum": 0,
"type": "integer",
"title": "quantity"
}
},
"required": [
"id",
"quantity"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
Odpowiedź¶
W odpowiedzi, OpenApp potwierdzi status.
Errors¶
| Error name | Code |
|---|---|
OrderNotFoundException |
404 |
MerchantOrderOwnershipException |
404 |