Logistics Service - rettersoft/rbs-docs GitHub Wiki
RBS Logistics Service
This service provides queries and mutations for zones and stores.
Models
Shipment Options
ShipmentOptions {
days: number // how many days in future people can create orders
maxPools?: number // how many pool configurations we can send back in "get pools"
}
Zones
Condition {
[operator: string]: string[] // operator might be IN or NIN (not in)
}
AddressRule {
[key: string]: Condition // key might be an attribute in Address model like city, district, etc.
}
Point {
lat: number
lng: number
}
Circle {
center: Point
radius: number // in meters
}
LocationRule {
// You should provide one of these
polygon?: Point[] // polygon: [{ lat: 41, lng: 29 }, { lat: 42, lng: 28 }, { lat: 43, lng: 27 }, { lat: 41, lng: 29 }]
circle?: Circle // circle: { center: { lat: 41, lng: 29 }, radius: 5000 }
}
ZoneRule {
// You should provide one of these
addr?: AddressRule // addr: { city: { IN: ['İSTANBUL'] }, district: { NIN: ['KADIKÖY'] } }
loc?: LocationRule // loc: { circle: { center: { lat: 41, lng: 29 }, radius: 5000 } }
}
ZoneInput {
zoneId?: string // If you prefer auto-generated ID, please do not send zoneId to create a new zone
name: string
rules?: ZoneRule[] = []
all?: boolean // set true if you want to test rules by AND instead of OR
fee?: ServiceFee // this amount might be overwritten by shipment company rules
minCartTotal?: number = 0
timezone?: number = 0
deleted?: boolean // There is only soft delete
}
Stores
MultiSelectionRule {
values: string[]
all: boolean
}
StoreRule {
types: string[] // shipment types: CARGO, RESERVED, ON_DEMAND, SELF
providers: string[] // shipment providers: YURTICI_KARGO, 34ABC123, 34DEF321
days?: string[] // [ 1, 2, 3, 4, 5, 6, 7 ] days of week
slots?: Slot[] // available slots [ [ '10:00', '12:00' ], [ '12:00', '14:00' ] ]
cutoff?: number // in minutes
time?: { slot: Slot, in: number } // { slot: [ '10:00', '18:00' ], in: 90 }
zones?: string[]
capacity?: number
fee?: number
minOrderCount?: number
minCartTotal?: number
maxCartWeight?: number
maxCartVolume?: number
category?: MultiSelectionRule // category { values: [ 'cold-chain' ] }
tag?: MultiSelectionRule // tag { values: [ 'tag-1', 'tag-2' ] }
segment?: MultiSelectionRule // segment { values: [ 'elite' ] }
}
StoreInput {
storeId?: string // If you prefer auto-generated ID, please do not send storeId to create a new store
merchantId: string
name: string
zones: string[] = []
rules?: StoreRule[] = []
all?: boolean // set true if you want to test rules by AND instead of OR
deleted?: boolean // There is only soft delete
}
Shipment Providers
ShipmentProviderInput {
storeId: string
shipmentType: string
merchantId?: string
providerId?: string // If you prefer auto-generated ID, please do not send providerId to create a new shipment provider
data: any // this might include 3rd party integration details
name?: string
deleted?: boolean // There is only soft delete
}
Shipments
Managing items in a shipment object is in progress. It will be added to the schema below ASAP.
ShipmentInput {
orderId: string
shipmentId?: string // If you prefer auto-generated ID, please do not send shipmentId to create a new shipment
address: Address
storeId?: string
merchantId?: string
items: Item[]
}
Working With Options
rbs.logistics.request.GET_OPTION : returns current options
Example Request : { "optionId": "SHIPMENT" }
Example Request : { "optionId": "SHIPMENT_TYPES" }
rbs.logistics.request.UPSERT_OPTION : updates existing options or inserts a new one
Example Request : { "optionId": "SHIPMENT", "data": { "days": 3, "linearStatuses": true } }
Example Request : { "optionId": "SHIPMENT_TYPES", "data": [ "CARGO", "RESERVED", "ON_DEMAND", "SELF" ] }
Working With Zones
rbs.logistics.request.UPSERT_ZONE : inserts a new zone or updates an existing zone
Example Response : { "zoneId": "ZONE_ID", "created": true }
rbs.logistics.request.LIST_ZONES : returns list of zones
Example Response : [{"zoneId":"01ERVD8Z3A827Z1MGMSEQH0R6Z","name":"Test","timezone":3}]
rbs.logistics.request.GET_ZONE : returns a zone
zoneId: ZONE_ID
Example Response : {"zoneId":"01ERVD8Z3A827Z1MGMSEQH0R6Z","name":"Test","timezone":3}
rbs.logistics.request.DELETE_ZONE : deletes a zone
zoneId: ZONE_ID
Example Response : {"zoneId":"01ERVD8Z3A827Z1MGMSEQH0R6Z","name":"Test","timezone":3, "deleted": true }
rbs.logistics.request.LOCATE_ZONE : returns a zoneId by address or location
{ address: ADDRESS, location: LOCATION }
Example Request : { "address": { "city": "İstanbul", "district": "Ataşehir" } }
Example Request : { "location": { "lat": 41, "lng": 29 } }
Example Response : {"zoneId":"01ERVD8Z3A827Z1MGMSEQH0R6Z"}
Working With Stores
rbs.logistics.request.UPSERT_STORE : inserts a new store or updates an existing store
Example Response : { "merchantId": "MERCHANT_ID", "storeId": "STORE_ID", "created": true }
rbs.logistics.request.LIST_STORES : returns list of stores
merchantId: MERCHANT_ID
Example Response : [{"merchantId": "MERCHANT_ID","storeId":"01ERVD8Z3A827Z1MGMSEQH0R6Z","name":"Test"}]
rbs.logistics.request.GET_STORE : returns a store
merchantId: MERCHANT_ID
storeId: STORE_ID
Example Response : {"merchantId": "MERCHANT_ID", "storeId":"01ERVD8Z3A827Z1MGMSEQH0R6Z", "name":"Test"}
rbs.logistics.request.DELETE_STORE : deletes a store
merchantId: MERCHANT_ID
storeId: STORE_ID
Example Response : {"merchantId": "MERCHANT_ID","storeId":"01ERVD8Z...H0R6Z", "name":"Test", "deleted": true}
Example Store Rules
It's possible to create various combinations of store rules to manage pools.
StoreRule {
types: ['CARGO']
providers: ['YURTICI_KARGO', 'ARAS_KARGO']
days: ['1', '2', '3', '4', '5', '6', '7']
slots: [ [ '10:00', '12:00' ], [ '12:00', '14:00' ] ]
zones: ['ZONE1']
capacity: 100
fee: 6.99
}
StoreRule {
types: ['CARGO']
providers: ['YURTICI_KARGO', 'SURAT_KARGO']
days: ['1', '2', '3', '4', '5', '6']
slots: [ [ '10:00', '13:00' ], [ '14:00', '17:00' ] ]
zones: ['ZONE2']
capacity: 85
fee: 5.99
}
StoreRule {
types: ['RESERVED']
providers: []
days: ['1', '2', '3', '4', '5', '6', '7']
slots: [ [ '10:00', '12:00' ], [ '12:00', '14:00' ], [ '14:00', '16:00' ], [ '16:00', '18:00' ] ]
zones: ['ZONE1', 'ZONE2']
capacity: 150
fee: 8.99
}
StoreRule {
types: ['ON_DEMAND']
providers: ['MOTOR1', 'MOTOR2', 'MOTOR3']
days: ['1', '2', '3', '4', '5', '6', '7']
slots: []
zones: ['ZONE2']
capacity: 3
fee: 9.99
}
StoreRule {
types: ['SELF']
providers: []
days: ['1', '2', '3', '4', '5', '6', '7']
slots: [ [ '10:00', '18:00' ] ]
zones: ['ZONE1']
capacity: 50
fee: 0
}
Working With Shipment Providers
rbs.logistics.request.UPSERT_SHIPMENT_PROVIDER : inserts a new shipment provider or updates an existing shipment provider
Example Response : { "shipmentType": "SHIPMENT_TYPE", "providerId": "PROVIDER_ID", "created": true }
rbs.logistics.request.LIST_SHIPMENT_PROVIDERS : returns list of shipment providers
merchantId: MERCHANT_ID
storeId: STORE_ID
Example Response : [{"merchantId": "MERCHANT_ID","storeId":"01ERVD8Z3A827Z1MGMSEQH0R6Z","name":"Test"}]
rbs.logistics.request.GET_SHIPMENT_PROVIDER : returns a shipment provider
merchantId: MERCHANT_ID
storeId: STORE_ID
shipmentType: SHIPMENT_TYPE
providerId: PROVIDER_ID
Example Response : {"merchantId": "MERCHANT_ID", "storeId":"01ERVD8Z3A827Z1MGMSEQH0R6Z", "shipmentType":"CARGO", "providerId": "PROVIDER_ID", "name": "Logistics Company", "data": {}}
Working With Shipment Pools
A shipment pool is a set of various delivery options. Pool configurations must cover all items in the cart. To accomplish that, a pool configuration might be groups of separated pool combinations for subsets of items in the cart.
rbs.logistics.request.GET_POOLS : returns available pool configurations
{ cartId: CART_ID, zoneId: ZONE_ID }
[
[ set of options for all items in cart ],
[
set of options for subset of items in cart,
set of options for rest of items in cart
],
]
[
[
{
"items": ["p1", "p2", "p3"],
"options": [
{
"type": "RESERVED",
"fee": 6,
"slots": {
"2020-12-18": [
["10:00", "12:00"],
["12:00", "14:00"],
["14:00", "16:00"],
["16:00", "18:00"]
],
"2020-12-19": [
["10:00", "12:00"],
["12:00", "14:00"],
["14:00", "16:00"],
["16:00", "18:00"]
],
"2020-12-20": [
["10:00", "12:00"],
["12:00", "14:00"],
["14:00", "16:00"],
["16:00", "18:00"]
],
"2020-12-21": [
["10:00", "12:00"],
["12:00", "14:00"],
["14:00", "16:00"],
["16:00", "18:00"]
]
}
},
{
"type": "ON_DEMAND",
"fee": 6,
"slots": { "2020-12-18": ["18:30", "20:00"](/rettersoft/rbs-docs/wiki/"18:30",-"20:00") }
}
]
}
],
[
{
"items": ["p1", "p2"],
"options": [
{ "type": "CARGO", "provider": "YURTICI_KARGO", "fee": 9 },
{ "type": "CARGO", "provider": "ARAS_KARGO", "fee": 9 }
]
},
{
"items": ["p3"],
"options": [
{
"type": "ON_DEMAND",
"fee": 6,
"slots": { "2020-12-18": ["18:30", "20:00"](/rettersoft/rbs-docs/wiki/"18:30",-"20:00") }
}
]
}
]
]
rbs.logistics.request.GET_REQUIREMENTS : returns requirements such as minimum cart total, service fee, etc.
{ zoneId: ZONE_ID }
[
{
"type": "CARGO",
"minTotal": 60,
"fee": 8.90
}
]
Validating Selected Shipment Pool in OMS
If you provide "selected pool" with rest of the original pooler input, algorithm checks if provided configuration is valid and responds with suitable stores. Thus, OMS would be able to call WMS to decrease stocks according to cart items. Requests from end users with pool parameter will be rejected immediately.
SelectedPool {
type: string
provider?: string
day?: string
slot?: Slot
}
rbs.logistics.request.GET_POOLS : returns available store(s) for selected pool configuration
{ cartId: CART_ID, zoneId: ZONE_ID, pool: SELECTED_POOL }
[
[
{
"items": ["p1", "p2", "p3"],
"storeId": "STORE_1",
}
],
[
{
"items": ["p1", "p2"],
"storeId": "STORE_1",
},
{
"items": ["p3"],
"storeId": "STORE_2",
}
]
]
Working With Shipments
rbs.logistics.request.GET_SHIPMENT : returns an existing shipment
orderId: ORDER_ID
shipmentId: SHIPMENT_ID
rbs.logistics.request.LIST_SHIPMENTS : returns existing shipments by order id
orderId: ORDER_ID
Updating Shipment Details
In order to update status of a shipment, you should start a specific process with following payload.
rbs.send({
action: 'rbs.process.request.START',
data: {
processId: 'SHIPMENT_JOURNEY',
payload: {
orderId: 'ORDER_ID',
shipmentId: 'SHIPMENT_ID',
status: 'PACKAGING' // current status
boxes?: ['BARCODE_1', 'BARCODE_2'] // send this if logistics provider got the boxes ready
trackingUrl?: 'url' // cargo tracking url
courierName?: 'NAME SURNAME' // courier name
cannotCancel?: true // from now on, no one can cancel this order
}
}
})
Tracking Shipments
In order to get shipment information via recipient's phone number, you should send a request with following payload.
rbs.send({
action: 'rbs.shipment.request.DATA',
data: {
orderId: 'ORDER_ID',
phoneNumber: 'PHONE_NUMBER'
}
})