Order Management Service - rettersoft/rbs-docs GitHub Wiki
# RBS Order Management Service
This service provides queries and mutations for orchestration of various services to manage orders.
How It Works
Creating a new order is a multi step journey on server-side. It starts with starting a new process called "CREATE_ORDER_AND_SHIPMENTS" on Process Manager service.
rbs.send({
action: 'rbs.process.request.START',
data: {
processId: 'CREATE_ORDER_AND_SHIPMENTS',
payload: orderInput
}
})
When you start a process, you will have an execution ID to track status of the process by polling "rbs.process.request.GET_EXECUTION".
rbs.send({
action: 'rbs.process.request.GET_EXECUTION',
data: {
processId: 'CREATE_ORDER_AND_SHIPMENTS',
executionId: 'executionId'
}
})
Models
To start a process, you need to send following input. In that input, you should
OrderInput {
"address": {
"shipmentAddress": {
"addressId": "01EYMX24JNP5439ND40RWM3GPS",
"name": "Test Address",
"country": "TÜRKİYE",
"city": "İSTANBUL",
"district": "ATAŞEHİR"
},
"invoiceAddress": {
"addressId": "01EYMXKC3JPBGRKQVNM3KP3W31",
"name": "Test Address",
"country": "TÜRKİYE",
"city": "İSTANBUL",
"district": "ATAŞEHİR"
}
},
"crm": {
"userId": "c85a5c6f11b1381c3cee0608cd80dec8"
},
"cart": {
"totalPriceToPay": 26910,
"totalPrice": 30000,
"serviceFeeDiscount": 900,
"discount": 3090,
"appliedPromotions": [
{
"title": "Deneme",
"appliedDiscount": 0,
"appliedServiceFeeDiscount": 900
},
{
"appliedDiscount": 0,
"appliedServiceFeeDiscount": 0
},
{
"appliedDiscount": 3090,
"appliedServiceFeeDiscount": 0
}
],
"promotionSuggestions": {
"minAmountForFreeServiceFee": 13300
},
"items": [
{
"merchantId": "Merchant",
"variantGroupId": "VaraiantGroupId",
"itemId": "ItemId",
"qty": 3,
"product": {
"images": [
"7208d184-f864-416e-8495-36a7eb897869"
],
"attributes": [
{
"fieldNameLabel": "CanReturnItem",
"attType": "UNKNOWN_TYPE",
"fieldName": "CanReturnItem",
"valueLabel": "true",
"value": true
},
{
"fieldNameLabel": "Description",
"attType": "UNKNOWN_TYPE",
"fieldName": "Description",
"valueLabel": " description",
"value": " description"
},
{
"fieldNameLabel": "test",
"attType": "UNKNOWN_TYPE",
"fieldName": "test",
"valueLabel": "",
"value": ""
},
{
"fieldNameLabel": "uruncesidi",
"attType": "LIST",
"fieldName": "uruncesidi",
"valueLabel": "",
"value": ""
},
{
"fieldNameLabel": "ItemFeatureBaran",
"attType": "UNKNOWN_TYPE",
"fieldName": "ItemFeatureBaran",
"valueLabel": "",
"value": ""
},
{
"fieldNameLabel": "isVirtual",
"attType": "UNKNOWN_TYPE",
"fieldName": "isVirtual",
"valueLabel": "true",
"value": true
},
{
"fieldNameLabel": "shortDescription",
"attType": "TEXT",
"fieldName": "shortDescription",
"valueLabel": "",
"value": ""
},
{
"badges": [],
"listValue": [
"demoCat"
],
"attType": "LIST",
"fieldName": "categories",
"listValueLabel": [
"demoCat"
],
"valueLabel": "",
"fieldNameLabel": "categories",
"value": ""
},
{
"fieldNameLabel": "shortName",
"attType": "TEXT",
"fieldName": "shortName",
"valueLabel": " Product",
"value": " Product"
},
{
"badges": [],
"listValue": [],
"attType": "LIST",
"fieldName": "productdetailIcons",
"listValueLabel": [],
"valueLabel": "",
"fieldNameLabel": "productdetailIcons",
"value": ""
},
{
"fieldNameLabel": "noDiscount",
"attType": "UNKNOWN_TYPE",
"fieldName": "noDiscount",
"valueLabel": "true",
"value": true
},
{
"badges": [],
"listValue": [],
"attType": "LIST",
"fieldName": "productFeature",
"listValueLabel": [],
"valueLabel": "",
"fieldNameLabel": "productFeature",
"value": ""
}
]
},
"stock": 1,
"price": {
"normal": 50000,
"discounted": 10000,
"priceToPay": 8970
}
}
]
},
"billing": {
"paymentOptions": [
{
"amount": 26910,
"authType": "AUTH",
"paymentMethod": "iyzico",
"providerConfigId": "iyzico1",
"installmentOption": {"installmentCount": 12, "interestRate": 10}
}
]
},
"logistics": {
"zoneId": "zoneA",
"note": "Not!",
"doNotRingBell": true,
"contactlessPayment": true,
"pools": {
"type": "CARGO",
"provider": "MNG",
"storeId": "pinardepo",
"fee": 9
}
}
}
Addresses
You should gather shipment and invoice addresses from Address Service
Cart Summary
You should get cart summary from Cart Service
Billing Options
You should get billing options from Billing Service User should select payment option for each partial payment and specify amount of each partial payment.
Logistics
You should get shipment pools from Logistics Service
User should select a shipment pool.
Order
{
"orderId": string,
"zoneId": string,
"ip": string,
"invoiceAddress": Address,
"shipmentAddress": Address,
"profile": {
"firstName": string,
"lastName": string,
"uid": string,
"phoneNumber": string,
"emailConfirmed": boolean,
"acceptedTerms": boolean,
"emailConfirmedAt": number, // timestamp
"birthDate": string, // DD/MM/YYYY
"acceptedKvkk": boolean,
"email": string,
"receivePromotionalContent": boolean
},
"items": [
{
"merchantId": string,
"variantGroupId": string,
"itemId": string,
"product": {
"images": ["7208d184-f864-416e-8495-36a7eb897869"],
"attributes": [
{
"fieldNameLabel": "CanReturnItem",
"attType": "UNKNOWN_TYPE",
"fieldName": "CanReturnItem",
"valueLabel": "true",
"value": true
},
{
"fieldNameLabel": "Description",
"attType": "UNKNOWN_TYPE",
"fieldName": "Description",
"valueLabel": " description",
"value": " description"
},
{
"fieldNameLabel": "test",
"attType": "UNKNOWN_TYPE",
"fieldName": "test",
"valueLabel": "",
"value": ""
},
{
"fieldNameLabel": "uruncesidi",
"attType": "LIST",
"fieldName": "uruncesidi",
"valueLabel": "",
"value": ""
},
{
"fieldNameLabel": "ItemFeatureBaran",
"attType": "UNKNOWN_TYPE",
"fieldName": "ItemFeatureBaran",
"valueLabel": "",
"value": ""
},
{
"fieldNameLabel": "isVirtual",
"attType": "UNKNOWN_TYPE",
"fieldName": "isVirtual",
"valueLabel": "true",
"value": true
},
{
"fieldNameLabel": "shortDescription",
"attType": "TEXT",
"fieldName": "shortDescription",
"valueLabel": "",
"value": ""
},
{
"badges": [],
"listValue": ["demoCat"],
"attType": "LIST",
"fieldName": "categories",
"listValueLabel": ["demoCat"],
"valueLabel": "",
"fieldNameLabel": "categories",
"value": ""
},
{
"fieldNameLabel": "shortName",
"attType": "TEXT",
"fieldName": "shortName",
"valueLabel": " Product",
"value": " Product"
},
{
"badges": [],
"listValue": [],
"attType": "LIST",
"fieldName": "productdetailIcons",
"listValueLabel": [],
"valueLabel": "",
"fieldNameLabel": "productdetailIcons",
"value": ""
},
{
"fieldNameLabel": "noDiscount",
"attType": "UNKNOWN_TYPE",
"fieldName": "noDiscount",
"valueLabel": "true",
"value": true
},
{
"badges": [],
"listValue": [],
"attType": "LIST",
"fieldName": "productFeature",
"listValueLabel": [],
"valueLabel": "",
"fieldNameLabel": "productFeature",
"value": ""
}
]
},
"price": { "normal": number, "discounted": number, "priceToPay": number },
"id": "1",
"storeId": string,
"status": string // 10: NONE/NORMAL
// 20: RETURN, 25: RETURN_ACCEPTED, 30: RETURN_REJECTED
// 35: REPLACE, 40: REPLACE_ACCEPTED, 45: REPLACE_REJECTED, 50: CANCEL
}
],
"totalPrice": number,
"totalPriceToPay": number,
"serviceFeeDiscount": number,
"discount": number,
"appliedPromotions": [
{
"title": string,
"appliedDiscount": number,
"appliedServiceFeeDiscount": number
},
]
}
How To Import
import RBS from '@rettersoft/rbs-sdk'
const result = await rbs.send({
action: string,
data: {
processId: 'IMPORT_EXISTING_ORDER_AND_SHIPMENT',
payload: ImportOrder,
}
// if you don't send a unique executionId, a sequential identifier will be generated automatically
})
ImportOrder {
"setup": [
{
"serviceId": "rbs.crm",
"config": {
"acceptedKvkk": boolean,
"acceptedTerms": boolean,
"birthDate": "DD/MM/YYYY",
"channel": string,
"email": string,
"firstName": string,
"lastName": string,
"phoneNumber": string, // 90...
"segments": string[],
"userId": string
}
},
{
"serviceId": "rbs.cart",
"config": {
"cartId": string, // if there is no cart information, feel free to put orderId
"totalPrice": number
}
},
{
"serviceId": "rbs.address",
"config": {
"shipmentAddress": {
"city": string,
"addressText": string,
"lon": number,
"addressId": string,
"directions": string,
"street": string,
"district": string,
"floor": string,
"building": string,
"neighborhood": string,
"lat": number,
"recipient": string,
"note": string,
"name": string // an easy to remember name
},
"invoiceAddress": {
"city": string,
"addressText": string,
"lon": number,
"addressId": string,
"directions": string,
"street": string,
"district": string,
"floor": string,
"building": string,
"neighborhood": string,
"lat": number,
"name": string, // an easy to remember name
"companyName": string,
"taxNo": string,
"taxOffice": string
}
}
},
{
"serviceId": "rbs.logistics",
"config": {
"zoneId": string,
"shipmentId": string,
"pools": {
"type": "CARGO",
"provider": "CARGO_COMPANY", // UPS, YURTICI, ARAS, etc.
"day": "YYYY-MM-DD" // day the shipment given to the cargo company
}
}
},
{
"serviceId": "rbs.oms",
"config": {
"orderId": string,
"items": [
{
"merchantId": string,
"id": string, // suborder id (unique in this order)
"variantGroupId": string,
"itemId": string, // product id
"price": number,
"name": string,
"storeId": string,
"status": "10"
// NONE = '10', RETURN = '20', RETURN_ACCEPTED = '25', RETURN_REJECTED = '30', REPLACE = '35', REPLACE_ACCEPTED = '40', REPLACE_REJECTED = '45', CANCEL = '50'
}
],
"ip": string,
"createdAt": number
}
}
]
}
Working With Order Documents
Currently we support 3 types of documents: Invoice (Regular), Invoice (Refund), Waybill.
enum OrderDocumentType {
INVOICE = 'IN',
REFUND_INVOICE = 'RI',
WAYBILL = 'WB',
}
Documents should have following attributes.
interface OrderDocumentInput {
type: OrderDocumentType
id: string // legal identifier of the document
file: string // compressed (gzip) file content in base64 format
}
interface OrderDocumentOutput {
type: OrderDocumentType
id: string // legal identifier of the document
file: string // file id from storage service
createdAt: number
}
You should call rbs.order.request.ADD_DOCUMENT to add a new document to an existing order. Do not forget to compress file via GZIP algorithm to avoid AWS Lambda request limits (6 MB).
RBS Core does not support binary input. In order to send a file through RBS, you should convert it to base64 format.
rbs.send({
action: 'rbs.order.request.ADD_DOCUMENT',
data: {
orderId: 'ORDER_ID',
document: {
type: 'IN', // a valid OrderDocumentType
id: 'DOCUMENT_ID',
file: 'FILE_CONTENT' // base64 format
}
}
})
Cancel Options
const result = await rbs.send({
action: 'rbs.order.get.CANCEL_OPTIONS',
data: {}
})
Cancel Order
const result = await rbs.send({
action: 'rbs.process.request.START',
data: {
processId: 'CANCEL_ORDER',
payload: {
orderId: 'ORDER_ID',
reason: 'STRING',
comment: 'STRING'
}
}
})
Return Items
const result = await rbs.send({
action: 'rbs.process.request.START',
data: {
processId: 'RETURN_ITEMS',
payload: {
orderId: 'ORDER_ID',
items: {
ITEM_ID: { reason: STRING, responsible: STRING }
}
}
}
})
Replace Items
const result = await rbs.send({
action: 'rbs.process.request.START',
data: {
processId: 'REPLACE_ITEMS',
payload: {
orderId: 'ORDER_ID',
items: {
ITEM_ID: CartItem
}
}
}
})
Post Commit Order
You should send actual weight in quantityCoefficient.
rbs.send({
action: 'rbs.process.request.START',
data: {
processId: 'ORDER_COMMIT',
payload: {
orderId: 'STRING',
changes: [
{ id: 'SUBORDER_ID', quantityCoefficient: number }
]
}
}
})