...
CRS public API is exposed via Swagger by following URL:
{host_url}/swagger/{microservice_name}/uiswagger/index
where {host_url}- URL of CRS instance to integrate (for example, https://prodshadowprod02shadow.cloudretailsystems.dk/),
{microservice_name} - name of microservice, which feature is supposed to be used. In scope of web shop integration following microservice names will be used:
...
Also it is worth to read following document in order to get short CRS API reference: /wiki/spaces/MBSG/pages/44512
Basic information for all requests
HTTP word - POST
All requests should contain header Content-Type - application/json.
Work with Get[Something]Page requests
...
| Code Block | ||
|---|---|---|
| ||
{
{
"id":actor_id,
"propertiesToLoad": { "value": <write 11111111111111flags value> }
}
} |
[propertiesToLoad] - flag enumeration with following options:
| Code Block | ||
|---|---|---|
| ||
FieldSet = 1, WebAddresses = 2, Emails = 4, Addresses = 8, Fields = 16, Groups = 32, Phones = 64, Roles = 128, User = 256, Relations = 512, PaymentInfo = 1024, WorkingHours = 2048, ExternalDataRecord = 4096 |
If all actor properties needed properties E.g. to load should be FieldSet | WebAddresses | Emails and so on - 1111111111111 in resultand Email we need to either use bit AND operation or just sum, so 1+4=5 in our case.
[propertiesToLoad] is an optional property, if it will is not be defined , all actor properties will be loaded.
...
| Code Block | ||
|---|---|---|
| ||
{
"sortInfo":[
],
"propertiesToLoad": <write flags 11111111111111value>,
"offset":0,
"count":page_size,
"includeOverallEntryCount":true
} |
...
[RoleSystemName]- allows to filter actors by specific role
[SearchPattern] - allows to filter actor whcich which person or organization name, phone, email or customer identifier satisfies search pattern
[ModifiedAtFrom] - allows to filter actors modified after specific timestamp
[ModifiedAtTo] - allows to filter actors modified before specific timestamp
...
| Code Block | ||
|---|---|---|
| ||
{
"sortInfo":[
],
"propertiesToLoad": <write flags 111111111111value>,
"offset":0,
"count":50,
"includeOverallEntryCount":true,
"roleSystemName":{
"value":"Customer"
}
} |
...
| Code Block | ||
|---|---|---|
| ||
{
"sortInfo":[
],
"propertiesToLoad": <write flags 111111111111value>,
"offset":0,
"count":50,
"includeOverallEntryCount":true,
"roleSystemName":{
"value":"Supplier"
}
} |
...
| Code Block | ||
|---|---|---|
| ||
{
"sortInfo": [],
"propertiesToLoad": <write flags 1111111111111value>,
"offset": 0,
"count": 50,
"includeOverallEntryCount": true,
"modifiedAtFrom": {
"value": "2020-01-01T18:25:43.511Z"
},
"modifiedAtTo": {
"value": "2021-01-01T18:25:43.511Z"
},
"searchPattern": {
"value": "aa"
}
} |
...
| Code Block | ||
|---|---|---|
| ||
{
"propertiesToLoad": {
"value": <write flags 1111111111111value>
},
"offset": 0,
"count": page_size,
"includeOverallEntryCount": true,
"modifiedAfter": {
"value": "2017-09-26T12:52:29.960Z"
}
} |
...
Create blank invoice,
Book invoice.
Sales prices and amounts are considered to include VAT part by default, e.g. price, discount or total amount on invoice.
Get sales orders (paged)
Word: POST
URL: {host_url}/api/financial/SalesOrder/GetSalesOrdersPage
...
[product]
[product_category]
[product_variant] if product supports variants - variant is required
[product_instance] if product supports instances - instance is required
[financial_account_number]- taken by rules described above
[vat_type] - taken from accounting microservice by financial account number
[sales_price] - calculated by following rule: If product instance is selected and its sales price is not null- product instance's sales price. If not- check variant. If variant is selected and its sales price is not null- variant's sales price. If sales price still not calculated - should be used sales price from product. [sales_price] is considered to include VAT part.
[quantity] - user input. Please note that quantity should be 1 for sales order items where product instance is defined
[manual_discount] - user input. Sale item amount will be calculated as [sales_price] * [quantity]. If it is needed to register sale item with different amount - [manual_discount] should be specified
All enlisted entities will be used in example below. [manual_discount] is considered to include VAT part.[cost_price] - the rule is:
take cost price from instance, if any
take cost price from variant, if any
take cost price from product, if it is null and product.isDefaultCostPriceApplicable = true then product.defaultCostPrice should be used
...
| Code Block | ||
|---|---|---|
| ||
{
"modelUpdates":[
{
"modelType":"CreateSalesOrderItemModelUpdate",
"financialData":{
"priceIncludesVat" // should always be true,
"saleFinancialAccountNumber" // [financial_account_number],
"vatAccountNumber" // should be taken from [vat_type] if presented, else - undefined
"vatRate" // should be taken from [vat_type] if presented, else - undefined
"discountAccountNumber" // should be taken from [vat_type] if presented, else - undefined
"usedVatFinancialAccountNumber" // should be taken from [vat_type] else - undefined
"usedVatRate" // should be taken from [vat_type] if presented, else - undefined
},
"manualDiscountAmount" // [manual_discount]
"quantity" // [quantity],
"inventoryItemData":{
"displayName" // from [product]
"productId" // from [product]
"variantId" // from [product_instance] if presented, , else - undefined,
"instanceId" // from [product_instance] if presented, else - undefined
"productIdentifier" // from [product_variant]
"isUserDefinedPriceAllowed // from [product]
"isCustomDisplayNameAllowed // from [product]
"costPrice" // [cost_price]
"isUsed"from [product_instance] if presented, else - undefined
"purchasePrice" //from [product_instance] if presented, else - undefined] if presented, else - undefined
"isProductInstanceRequired" from product.isProductInstancesSupported
},
"price" - [sales_price]
},
{
"modelType":"SetSalesOrderCustomerDataModelUpdate",
"actor":{ // this entire block may be undefined if [customer] is not defined
"value":{
"actorId"// from [customer]
"fullName"// Property [ActorText] from [customer]
"identification// Customer Identifier (from [customer])
}
},
"address":{ // this entire block may be undefined if [address] is not defined
"value":{
"addressLine1" // from [address], required
"addressLine2" // from [address]
"postalCode" // from [address], required
"postalDistrict" // from [address]
"country" // from [address], required
"latitude" // from [address]
"longitude" // from [address]
}
},
"email":{ // this entire block may be undefined if [email] is not defined
"value" // [email] itself
},
"phone":{ // this entire block may be undefined if [phone] is not defined
"value" // [phone] itself
}
}
],
"modelType":"CreateSalesOrderCommand"
} |
...
| Code Block | ||
|---|---|---|
| ||
{
"modelUpdates":[
{
"modelType":"CreateSalesOrderItemModelUpdate",
"financialData":{
"priceIncludesVat":true,
"saleFinancialAccountNumber":1100,
"vatAccountNumber":14262,
"vatRate":25,
"discountAccountNumber":7200,
"usedVatFinancialAccountNumber":null,
"usedVatRate":null
},
"manualDiscountAmount":300.14,
"quantity":1,
"inventoryItemData":{
"displayName":"Sony Playstation 4 (cf18-4136-9f92-31764c4)",
"productId":106,
"variantId":null,
"instanceId":165,
"productIdentifier":"ID_108",
"isUserDefinedPriceAllowed":false,
"isCustomDisplayNameAllowed":false,
"costPrice":3000,
"isUsed":false,
"purchasePrice":null,
"isProductInstanceRequired": true
},
"price":3001.45
},
{
"modelType":"SetSalesOrderCustomerDataModelUpdate",
"actor":{
"value":{
"actorId":8,
"fullName":"0000100001 a_person Customer",
"identification":"0000100001"
}
},
"address":{
"value":{
"addressLine1":"myStreet",
"addressLine2":"222",
"postalCode":"2100",
"postalDistrict":"København Ø",
"country":"Denmark",
"latitude":null,
"longitude":null,
}
},
"email":{
"value":"example@gmail.com"
},
"phone":{
"value":"77777777"
}
}
],
"modelType":"CreateSalesOrderCommand"
} |
In response sales order Id will be presented.
Advanced flows:
Some customers need to continue modifying sales order even after it is ready or invoiced (e.g. to add work hours to sales order and invoice it separately.). In this case sapera can be told that sales order should support such a flow by setting
AllowModifyingWhenReady = {value: true}at creation time in root ofCreateSalesOrderCommandbody. When it is set - client app will ask at invoice time if sales order should be completed. User can choose to complete
Update Sales Order
It is possible to update sales order after creation (add or change customer data or contact info, add, change or remove sale items). All model updates described above that are used in CreateSalesOrderCommand may be used in UpdateSalesOrderCommand, they may be reviewed in Swagger.
...
[product]
[product_category]
[product_variant] if product supports variants - variant is required
[product_instance] if product supports instances - instance is required
[financial_account_number] - taken by rules described above ([Get product financial and VAT data])
[vat_type] - taken from accounting microservice by financial account number
[sales_price] - calculated by following rule: If product instance is selected and its sales price is not null- product instance's sales price. If not- check variant. If variant is selected and its sales price is not null- variant's sales price. If sales price still not calculated - should be used sales price from product. [sales_price] is considered to include VAT part.
[quantity] - user input. Please note that quantity should be 1 for sales order items where product instance is defined
[manual_discount] - user input. Sale item amount will be calculated as [sales_price] * [quantity]. If it is needed to register sale item with different amount - [manual_discount] should be specified. [manual_discount] is considered to include VAT part.
All enlisted entities will be used in example below.
...
| Code Block | ||
|---|---|---|
| ||
{
"modelUpdates":[
{
"modelType":"CreateInvoiceItemModelUpdate",
"financialData":{
"priceIncludesVat" // should always be true,
"saleFinancialAccountNumber" // [financial_account_number],
"vatAccountNumber" // should be taken from [vat_type] if presented, else - undefined
"vatRate" // should be taken from [vat_type] if presented, else - undefined
"discountAccountNumber" // should be taken from [vat_type] if presented, else - undefined
"usedVatFinancialAccountNumber" // should be taken from [vat_type] else - undefined
"usedVatRate" // should be taken from [vat_type] if presented, else - undefined
},
"manualDiscountAmount" // [manual_discount]
"quantity" // [quantity],
"inventoryItemData":{
"displayName" // from [product]
"productId" // from [product]
"variantId" // from [product_instance] if presented, , else - undefined,
"instanceId" // from [product_instance] if presented, else - undefined
"productIdentifier" // from [product_variant]
"isUserDefinedPriceAllowed // from [product]
"isCustomDisplayNameAllowed // from [product]
"costPrice" // from [product_instance] if presented, else - undefined
"isUsed"from [product_instance] if presented, else - undefined
"purchasePrice" //from [product_instance] if presented, else - undefined
"isProductInstanceRequired" from product.isProductInstancesSupported
},
"price" - [sales_price]
},
{
"modelType":"SetInvoiceCustomerDataModelUpdate",
"actor":{ // this entire block may be undefined if [customer] is not defined
"value":{
"actorId"// from [customer]
"fullName"// from [customer]
"identification// from [customer]
}
},
"address":{ // this entire block may be undefined if [address] is not defined
"value":{
"addressLine1" // from [address], required
"addressLine2" // from [address]
"postalCode" // from [address], required
"postalDistrict" // from [address]
"country" // from [address], required
"latitude" // from [address]
"longitude" // from [address]
}
},
"email":{ // this entire block may be undefined if [email] is not defined
"value" // [email] itself
},
"phone":{ // this entire block may be undefined if [phone] is not defined
"value" // [phone] itself
}
}
],
"modelType":"CreateInvoiceAndReserveCommand"
} |
...
| Code Block | ||
|---|---|---|
| ||
{
"modelUpdates":[
{
"modelType":"CreateInvoiceItemModelUpdate",
"financialData":{
"priceIncludesVat":true,
"saleFinancialAccountNumber":1100,
"vatAccountNumber":14262,
"vatRate":25,
"discountAccountNumber":7200,
"usedVatFinancialAccountNumber":null,
"usedVatRate":null
},
"manualDiscountAmount":300.14,
"quantity":1,
"inventoryItemData":{
"displayName":"Sony Playstation 4 (cf18-4136-9f92-31764c4)",
"productId":106,
"variantId":null,
"instanceId":165,
"productIdentifier":"ID_108",
"isUserDefinedPriceAllowed":false,
"isCustomDisplayNameAllowed":false,
"costPrice":3000,
"isUsed":false,
"purchasePrice":null,
"isProductInstanceRequired": true
},
"price":3001.45
},
{
"modelType":"SetInvoiceCustomerDataModelUpdate",
"actor":{
"value":{
"actorId":8,
"fullName":"0000100001 a_person Customer",
"identification":"0000100001"
}
},
"address":{
"value":{
"addressLine1":"myStreet",
"addressLine2":"222",
"postalCode":"2100",
"postalDistrict":"København Ø",
"country":"Denmark",
"latitude":null,
"longitude":null,
}
},
"email":{
"value":"example@gmail.com"
},
"phone":{
"value":"77777777"
}
}
],
"modelType":"CreateInvoiceAndReserveCommand"
} |
...
| Code Block | ||
|---|---|---|
| ||
{
"modelUpdates":[
{
"modelType":"CreateInvoiceItemModelUpdate",
"salesOrderItemReference":{
"value":{
"salesOrderId" // from [sale_order]
"salesOrderIdentifier // from [sale_order]
"salesOrderItemId" // from [sale_order_item]
}
},
"financialData":{ // just copy from property with same name from [sale_order_item] or change if needed
"saleFinancialAccountNumber"
"vatRate"
"vatAccountNumber"
"discountAccountNumber"
"priceIncludesVat"
"usedVatRate"
"usedVatFinancialAccountNumber"
},
"manualDiscountAmount"// just copy from property with same name from [sale_order_item] or change if needed
"quantity"// just copy from property with same name from [sale_order_item] or change if needed
"inventoryItemData":{ // just copy from property with same name from [sale_order_item] or change if needed
"displayName"
"productId"
"variantId"
"instanceId"
"productIdentifier"
"isUserDefinedPriceAllowed"
"isCustomDisplayNameAllowed"
"costPrice"
"isUsed"
"purchasePrice",
"isProductInstanceRequired"
},
"price"// just copy from property with same name from [sale_order_item] or change if needed
},
{
"modelType":"SetInvoiceCustomerDataModelUpdate",
"customerDescriptor":{ // copy from property [customer] of [sale_order] or compose based on [customer]
"value":{
"actorId"
"fullName"
"identification"
}
},
"firstName":{
"value" // take from [customer] if possible or user input
},
"lastName":{
"value" // take from [customer] if possible or user input
},
"organizationName":{
"value" // take from [customer] if possible or user input
},
"address":{ // take from [customer] if possible or user input
"value":{
"addressLine1"
"addressLine2"
"postalCode"
"postalDistrict"
"country"
"latitude"
"longitude"
}
},
"email":{
"value" // take from [customer] if possible or user input
},
"phone":{
"value" // take from [customer] if possible or user input
}
}
],
"modelType":"CreateInvoiceCommand"
} |
...
| Code Block | ||
|---|---|---|
| ||
{
"modelUpdates":[
{
"modelType":"CreateInvoiceItemModelUpdate",
"salesOrderItemReference":{
"value":{
"salesOrderId":1,
"salesOrderIdentifier":"0000000001",
"salesOrderItemId":1
}
},
"financialData":{
"saleFinancialAccountNumber":1100,
"vatRate":25,
"vatAccountNumber":14262,
"discountAccountNumber":7200,
"priceIncludesVat":true,
"usedVatRate":null,
"usedVatFinancialAccountNumber":null
},
"manualDiscountAmount":300.14,
"quantity":1,
"inventoryItemData":{
"displayName":"Sony Playstation 4 (cf18-4136-9f92-31764c4)",
"productId":106,
"variantId":null,
"instanceId":165,
"productIdentifier":"ID_108",
"isUserDefinedPriceAllowed":false,
"isCustomDisplayNameAllowed":false,
"costPrice":3000,
"isUsed":false,
"purchasePrice":null,
"isProductInstanceRequired": true
},
"price":3001.45
},
{
"modelType":"SetInvoiceCustomerDataModelUpdate",
"customerDescriptor":{
"value":{
"actorId":8,
"fullName":"0000100001 a_person Customer",
"identification":"0000100001"
}
},
"firstName":{
"value":"a_person"
},
"lastName":{
"value":"Customer"
},
"organizationName":{
"value":null
},
"ean":{
},
"address":{
"value":{
"addressLine1":"myStreet",
"addressLine2":"222",
"postalCode":"2100",
"postalDistrict":"København Ø",
"country":"Denmark",
"latitude":null,
"longitude":null
}
},
"email":{
"value":"example@gmail.com"
},
"phone":{
"value":"77777777"
}
},
{
"modelType":"SetInvoiceProductInstanceModelUpdate",
"productInstance":{
"productInstanceId":null,
"displayValue":"",
"productId":null,
"productVariantId":null
}
},
{
"modelType":"SetInvoicePaymentDueDateModelUpdate",
"paymentDueDate":"2018-09-27T13:38:46+03:00"
}
],
"modelType":"CreateInvoiceCommand"
} |
...