RBS Integrations - rettersoft/rbs-docs GitHub Wiki

Integrating to an RBS project can be done with following actions. These actions can be called via SDK or REST api. Please check our REST api documentation.

Models

Common Models

// IMPORTANT: All price fields are integer. (ACTUAL PRICE * 100)
Price {
    "normal": number, // base price, integer
    "discounted": number, // discounted price, integer
    "priceAfterPromotions": number, // price after all possible promotions applied, integer
    "priceAfterInterest": number // price after all possible interests(like installment interest) applied, integer
}

// All price fields which end with "Str" contains a string formatted by locale.
PriceStr {
    "normal": string, // ₺0,00
    "discounted": string, // ₺0,00
    "priceAfterPromotions": string, // ₺0,00
    "priceAfterInterest": string // ₺0,00
}

AppliedPromotionItem {
    "promotionId": string, // promotion's ID
    "discount": number, // applied discount for current promotion
}

AppliedPromotion {
    "promotionId": string, // promotion's ID
    "title": string, // promotion's human readable name
    "appliedDiscount": number, // applied discount for current promotion
    "appliedServiceFeeDiscount": number, // applied service fee discount for current promotion
    "erpTags": string[], // ERP codes
    "tags": string[] // various tags
}

AppliedCampaign {
    "campaignId": string, // campaign's ID
    "appliedDiscount": number // applied discount for current campaign
}

ProductImage {
    "id": string // FILE_ID: you can request this file via RBS storage service
}

ProductAttribute {
    "attType": string, // attribute type
    "fieldName": string, // attribute's variable name
    "fieldNameLabel": string, // attribute's name in human readable form
    "valueLabel": string, // attribute's value in human readable form
    "value": any // attribute's actual value
}

Product {
    "images": ProductImage[],
    "attributes": ProductAttribute[],
    "children": Product[]
}

Profile {
    "acceptedKvkk": boolean, // KVKK accepted?
    "acceptedTerms": boolean, // terms and condition accepted?
    "birthDate": string, // DD/MM/YYYY
    "communicationByEmail": boolean, // communication via email permission
    "communicationByPhone": boolean, // communication via sms permission
    "email": string, // email address
    "emailConfirmed": boolean, // email confirmation check
    "emailConfirmedAt": timestamp, // milliseconds
    "firstName": string, // user's name
    "lastName": string, // user's last name
    "gender": "M", // user's gender, M: male, F: female, U: unknown
    "phoneNumber": string, // user's phone number (msisdn) 905001234567
    "phoneNumberConfirmed": boolean, // msisdn confirmation check
    "phoneNumberConfirmedAt": timestamp, // milliseconds
    "priceSegment": string, // segmentation value for price listing, default
    "receivePromotionalContent": boolean, // promotional content permission
    "registrationChannel": string, // user's registration channel
    "tags": string[], // user's segmentation tags
    "uid": string, // user id
    "userExtraInformation": { // all out of model data will be written as extra information
        "registrationType": string // user's registration type, default
    }
}

enum SuborderStatus {
    CANCEL = '50',
    NONE = '10',
    RETURN = '20',
    REPLACE = '35',
}

Address Model

Address {
    addressId?: string // address id
    name: string // a short name to remember the address, i.e. Evim
    userId?: string // user id
    nameSurname?: string // person's name and surname for invoice
    identityNo?: string // national identity number
    recipient?: string // recipient's name and surname for shipment
    phone?: string // phone number
    note?: string // directions
    country?: string
    city?: string
    district?: string
    neighborhood?: string
    street?: string
    building?: string // building number
    floor?: string // floor number
    door?: string // door (flat) number
    postalCode?: string
    lat?: number // latitude
    lng?: number // longitude
    acc?: number // accuracy for gps location in meters
    invoiceType?: string // C: Corporate, I: Individual
    companyName?: string // for invoice
    taxNo?: string // for invoice
    taxOffice?: string // for invoice
    isInvoice?: boolean
}

Order Model

Order {
    "itemTypeTotals": { // total prices by item types in shopping cart
        "serviceFee": { // service fee
            "totalPriceWithTax": Price, // total prices includes taxes
            "totalPriceWithTaxStr": PriceStr // total prices including taxes in localized number format
        },
        "product": {
            "totalPriceWithTax": Price, // total prices includes taxes
            "totalPriceWithTaxStr": PriceStr // total prices including taxes in localized number format
        }
    },
    "promotionDiscount": 0, // total promotion discount
    "promotionDiscountStr": "₺0,00", // total promotion discount in localized number format
    "serviceFeeDiscount": 0, // service fee discount
    "serviceFeeDiscountStr": "₺0,00", // service fee discount in localized number format
    "totalPriceWithTax": Price, // total prices including taxes
    "totalPriceWithTaxStr": PriceStr, // total prices including taxes in localized number format
    "totalPriceWithoutTax": Price, // total prices without taxes
    "totalPriceWithoutTaxStr": PriceStr, // total prices without taxes in localized number format
    "appliedCampaigns": AppliedCampaign[], // all applied campaigns
    "campaignDiscount": 0, // total campaign discount
    "campaignDiscountStr": "₺0,00", // total campaign discount in localized number format
    "totalDiscount": 0, // total discount
    "totalDiscountStr": "₺0,00", // total discount in localized number format
    "productCount": 0, total product count
    "appliedPromotions": AppliedPromotion[], // all applied promotions
    "promotionSuggestions": { // suitable promotions based on user's shopping cart
        "minAmountForFreeServiceFee": 0 // minimum amount to be qualified for service fee promotion
    },
    "items": [ // uniquely grouped items
        {
            // service fee
            "itemType": string, // product | serviceFee | bag
            "qty": 1, // quantity
        },
        {
            // product
            "merchantId": string, // default
            "variantGroupId": string,
            "itemId": string,
            "qty": number, // quantity
            "product": Product, // product details
            "stock": number, // available stocks when the order committed
            "bundleType": string, // bundle | child | none
            "itemType": string, // product | serviceFee | bag
            "appliedPromotions": AppliedPromotionItem[], // applied promotions for current item
            "totalPriceWithTax": Price, // total prices including taxes
            "totalPriceWithTaxStr": PriceStr, // total prices including taxes in localized number format
            "priceWithTax": Price, // single price including taxes
            "priceWithTaxStr": PriceStr, // single price including taxes in localized number format
            "priceWithoutTax": Price, // single price without taxes
            "priceWithoutTaxStr": PriceStr // single price without taxes in localized number format
        },
        {
            // returned product
            "merchantId": string, // default
            "variantGroupId": string,
            "itemId": string,
            "qty": number, // quantity
            "product": Product, // product details
            "stock": number, // available stocks when the order committed
            "bundleType": string, // bundle | child | none
            "itemType": string, // product | serviceFee | bag
            "appliedPromotions": AppliedPromotionItem[], // applied promotions for current item
            "totalPriceWithTax": Price, // total prices including taxes
            "totalPriceWithTaxStr": PriceStr, // total prices including taxes in localized number format
            "priceWithTax": Price, // single price including taxes
            "priceWithTaxStr": PriceStr, // single price including taxes in localized number format
            "priceWithoutTax": Price, // single price without taxes
            "priceWithoutTaxStr": PriceStr // single price without taxes in localized number format
        }
    ],
    "suborders": [ // individually separate items
        {
            // service fee
            "itemType": string, // product | serviceFee | bag
            "qty": 1, // quantity
            "quantityCoefficient": float, // default 1
            "amount": number, // item's total paid price
            "updatedAt": timestamp, // milliseconds
            "id": string // suborder id
        },
        {
            // product
            "merchantId": string, // default
            "variantGroupId": string,
            "itemId": string,
            "qty": 1, // quantity
            "bundleType": string, // bundle | child | none
            "itemType": string, // product | serviceFee | bag
            "quantityCoefficient": float, // default 1
            "amount": number, // item's total paid price
            "updatedAt": timestamp, // milliseconds
            "id": string, // suborder id
            "storeId": string, // item's store id default
            "status": SuborderStatus // item's current status
        },
        {
            // returned product
            "merchantId": string, // default
            "variantGroupId": string,
            "itemId": string,
            "qty": 1, // quantity
            "bundleType": string, // bundle | child | none
            "itemType": string, // product | serviceFee | bag
            "quantityCoefficient": float, // default 1
            "amount": number, // item's total paid price
            "updatedAt": timestamp, // milliseconds
            "id": string, // suborder id
            "storeId": string, // default
            "status": SuborderStatus, // item's current status
            "reason"?: string, // reason for update
            "responsible"?: string, // who made the update
            "returnedAt": timestamp // milliseconds
        }
    ],
    "tags": string[], // gift
    "orderId": "ORDER_ID",
    "zoneId": "ZONE_ID",
    "ip": "IP_ADDRESS",
    "invoiceAddress": Address, // invoice address
    "shipmentAddress": Address, // shipment address (delivery)
    "profile": Profile, // user's profile
    "createdAt": timestamp, // milliseconds
    "createdBy": string, // internal user id or service id
    "updatedAt": timestamp, // milliseconds
    "updatedBy": string // internal user id or service id
    "isCancelled"?: boolean
}

Shipment Model

type Slot = [ string, string ] // ["HH:mm", "HH:mm"]

ShipmentPool {
    "type": string, // currently: CARGO,  possible other options: RESERVED, ON_DEMAND, SELF
    "provider": string, // AYKARGO, AYKARGO_EXPRESS, ARASKARGO, YURTICI_KARGO
    "date"?: string, // YYYY-MM-DD
    "slot"?: Slot,
    "storeId": string, // default
    "fee": number // service fee
}

Shipment {
    "items": [
        {
            // service fee
            "itemType": string, // product | serviceFee | bag
            "qty": 1, // quantity
            "totalPriceWithTax": Price, // total prices including taxes
            "totalPriceWithTaxStr": PriceStr, // total prices including taxes in localized number format
            "priceWithTax": Price, // single price including taxes
            "priceWithTaxStr": PriceStr, // single price including taxes in localized number format
            "priceWithoutTax": Price, // single price without taxes
            "priceWithoutTaxStr": PriceStr // single price without taxes in localized number format
        },
        {
            // product
            "merchantId": string, // default
            "variantGroupId": string,
            "itemId": string,
            "qty": number, // quantity
            "product": Product, // product details
            "stock": number, // available stocks when the order committed
            "bundleType": string, // bundle | child | none
            "itemType": string, // product | serviceFee | bag
            "totalPriceWithTax": Price, // total prices including taxes
            "totalPriceWithTaxStr": PriceStr, // total prices including taxes in localized number format
            "priceWithTax": Price, // single price including taxes
            "priceWithTaxStr": PriceStr, // single price including taxes in localized number format
            "priceWithoutTax": Price, // single price without taxes
            "priceWithoutTaxStr": PriceStr // single price without taxes in localized number format
        },
        {
            // returned product
            "merchantId": string, // default
            "variantGroupId": string,
            "itemId": string,
            "qty": number, // quantity
            "product": Product, // product details
            "stock": number, // available stocks when the order committed
            "bundleType": string, // bundle | child | none
            "itemType": string, // product | serviceFee | bag
            "totalPriceWithTax": Price, // total prices including taxes
            "totalPriceWithTaxStr": PriceStr, // total prices including taxes in localized number format
            "priceWithTax": Price, // single price including taxes
            "priceWithTaxStr": PriceStr, // single price including taxes in localized number format
            "priceWithoutTax": Price, // single price without taxes
            "priceWithoutTaxStr": PriceStr // single price without taxes in localized number format
        }
    ],
    "suborders": [
        {
            // product
            "merchantId": string, // default
            "variantGroupId": string,
            "itemId": string,
            "qty": 1, // quantity
            "bundleType": string, // bundle | child | none
            "itemType": string, // product | serviceFee | bag
            "quantityCoefficient": float, // default 1
            "amount": number, // item's total paid price
            "updatedAt": timestamp, // milliseconds
            "id": string, // suborder id
            "storeId": string, // default
            "status": SuborderStatus // item's current status
        },
        {
            // returned product
            "merchantId": string, // default
            "variantGroupId": string,
            "itemId": string,
            "qty": 1,
            "bundleType": string, // bundle | child | none
            "itemType": string, // product | serviceFee | bag
            "quantityCoefficient": float, // default 1
            "amount": number, // item's total paid price
            "updatedAt": timestamp, // milliseconds
            "id": string, // suborder id
            "storeId": string, // default
            "status": SuborderStatus, // item's current status
            "reason"?: string, // reason for update
            "responsible"?: string, // who made the update
            "returnedAt": timestamp // milliseconds
        }
    ],
    "pool": ShipmentPool, // shipment configuration pool
    "orderId": "ORDER_ID",
    "shipmentId": "SHIPMENT_ID",
    "zoneId": "ZONE_ID",
    "merchantId": "MERCHANT_ID",
    "address": Address, // shipment address
    "profile": Profile, // user's profile
    "createdAt": timestamp, // milliseconds
    "createdBy": string, // internal user id or service id
    "updatedAt": timestamp, // milliseconds
    "updatedBy": string, // internal user id or service id
    "isCancelled"?: boolean,
    "cannotCancel"?: boolean, // flag for shipment to check ability for cancelling
    "boxes"?: string[], // boxes to deliver
    "note"?: string, // note for couriers
    "doNotRingBell"?: boolean, // do not ring door bell flag for couriers
    "contactlessPayment"?: boolean // contactless payment flag for couriers
}

For more information about Shopping Cart related fields please check our Cart Service.

Push Stocks

It's possible to increase / decrease stocks as well as to overwrite them directly. If you want to overwrite the current value, you should send overwrite attribute as TRUE.

Action name: rbs.process.request.START

Post body for single change:

{
    processId: 'PUSH_STOCKS',
    payload: {
        merchantId: string,
        storeId: string,
        variantGroupId: string,
        itemId: string,
        qty: number,
        overwrite?: boolean
    }
}

Post body for multiple changes:

{
    processId: 'PUSH_STOCKS',
    payload: {
        increase: [
            {
                merchantId: string,
                storeId: string,
                variantGroupId: string,
                itemId: string,
                qty: number,
            }
        ],
        decrease: [
            {
                merchantId: string,
                storeId: string,
                variantGroupId: string,
                itemId: string,
                qty: number,
            }
        ],
        overwrite: [
            {
                merchantId: string,
                storeId: string,
                variantGroupId: string,
                itemId: string,
                qty: number,
            }
        ]
    }
}

Updating Shipment Details in Simple Warehouse Integrations

In order to update status of a shipment, you should start a specific process with following payload.

Action name: rbs.process.request.START

Post body:

{
    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
    }
}

Commit Order

If the order is provisioned, you can commit final changes by starting following process. You should send actual weight in quantityCoefficient instead of products' attribute values.

Action name: rbs.process.request.START

Post body:

{
    processId: 'ORDER_COMMIT',
    payload: {
        orderId: 'STRING',
        changes: [
            { id: 'SUBORDER_ID', quantityCoefficient: number }
        ]
    }
}

Cancel Order

Action name: rbs.process.request.START

Post body:

{
    processId: 'CANCEL_ORDER',
    payload: { 
        orderId: 'ORDER_ID',
        reason: 'STRING',
        comment: 'STRING'
    }
}

Export Data From RBS

If you want realtime data (order, shipment, user, etc.) updates from RBS, you should provide an endpoint to receive them. Every change triggers a process called "EXPORT" and send the data to your endpoint accordingly.