There are the purchases tied to customer accounts stored in CRM CareCloud. The purchases are saved online when closing the bill or imported by the offline web service after the purchase. There are many parameters that specifies the purchase like bill items and its prices, date and time of the purchase, store, where purchase was made or loyalty card number. All this data are used for segmentation or voucher creation.
All available methods for resource purchases.
HTTP method | Endpoint | Description |
---|---|---|
[badge-blue GET] | /purchases | Get information about a collection of purchases |
[badge-blue GET ] | /purchases/{purchase_id} | Get information about a specific purchase |
All available methods for sub-resources of resource purchases.
HTTP method | Endpoint | Description |
---|---|---|
[badge-blue GET ] | /purchases/{purchase_id}/purchase-items | Collection of the purchase items |
[badge-blue GET ] | /purchases/{purchase_id}/vouchers | Collection of vouchers |
[badge-blue GET ] | /purchases/{purchase_id}/points | Collection of points |
Action methods for resource purchases.
HTTP method | Endpoint | Description |
---|---|---|
[badge-blue GET] | /purchases/{purchase_id}/actions/payment-summary | Action method returns payment summary of the purchase. Shows credit, points and vouchers summary. |
[badge-green POST] | /purchases/actions/recommended-best-rewards | Method returns all available rewards for POS installation. Rewards can be used later in send purchase process |
[badge-green POST] | /purchases/actions/accept-payment | This method processes purchase closure from POS |
[badge-green POST] | /purchases/actions/send-purchase | Method send the final closed bill to CareCloud from POS |
[badge-green POST] | /purchases/actions/assign-customer | Method assigns a customer to existing purchase |
Get a list of purchases saved in CRM
[badge-blue GET] /purchases
Parameter name | Type | Description | Mandatory (Yes/No) |
---|---|---|---|
count | integer | The number of records to return. Default value is 100. |
No |
offset | integer | The number of records from a collection to skip. Default value is 0. | No |
sort_field | string | One of the query string parameters for sorting. Response is sorted by the specified field. | No |
sort_direction | string | Direction of sorting the response list. Possible values are: ASC / DESC | No |
store_id | string | The unique id for the store where purchase was made | No |
customer_id | string | The unique id for the customer | No |
type_id | string | Purchase type | No |
payment_time_from | string | Date and time from of the purchase payment (YYYY-MM-DD HH:MM:SS) | No |
payment_time_to | string | Date and time to of the purchase payment (YYYY-MM-DD HH:MM:SS) | No |
purchase_items_extension | boolean | If true, resource returns extended response with purchase items. If false, the resource won't be extended. If the parameter is not set, the default value is false | No |
Status code: 200 OK
Output structure : object
Parameter name | Type | Description |
---|---|---|
purchases | Purchase[] | List of purchases |
total_items | integer | Count of all found purchases |
GET https://<projectURL>/rest-api/enterprise-interface/v1.0/purchases?count=1&purchase_items_extension=true&offset=99
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZXJwcmlzZV9pbnRlcmZhY2U6NGRmOzI1ZTcYTdhYmQ0OWVhZWJhYzE2OTI3NTQxMDY0Y2MxYjk3NTBhNGYxMTFmNzhhYTYwMTg1Mg==
HTTP/1.1 200 OK
Date: Tue, 27 Apr 2021 16:36:29 GMT
Content-Type: application/json; charset=utf-8
{
"data": {
"purchases": [
{
"purchase_id": "80c0e8d018748b2106387694bf",
"customer_id": "8bc8ea4c1466859cbba26e522f",
"store_id": "8fd73167342d06899c4c015320",
"external_purchase_id": "208",
"payment_time": "2012-11-14 21:16:51",
"items_count": 2,
"purchase_items": [
{
"purchase_item_id": "84b757641df03b1529c2c7f66c",
"product_id": "89b3b24b405f461c63d8fcaa0c",
"external_id": null,
"purchase_item_type_id": "86e05affc7a7abefcd513ab400",
"price": 1.99,
"amount": null,
"vat_rate": null,
"additional_properties": [
{
"property_record_id": "note:84b757641df03b1529c2c7f66c",
"property_id": "note",
"property_name": "note",
"property_value": null,
"last_change": null
},
{
"property_record_id": "transaction_discounts:84b757641df03b1529c2c7f66c",
"property_id": "transaction_discounts",
"property_name": "Discounts",
"property_value": [],
"last_change": null
},
{
"property_record_id": "item_price:84b757641df03b1529c2c7f66c",
"property_id": "item_price",
"property_name": "Item price",
"property_value": null,
"last_change": null
}
]
},
{
"purchase_item_id": "82b4a764d9cd4b14780e011e33",
"product_id": "83be813bf058ac655c1c7a2337",
"external_id": null,
"purchase_item_type_id": "86e05affc7a7abefcd513ab400",
"price": 1.99,
"amount": null,
"vat_rate": null,
"additional_properties": [
{
"property_record_id": "note:82b4a764d9cd4b14780e011e33",
"property_id": "note",
"property_name": "note",
"property_value": null,
"last_change": null
},
{
"property_record_id": "transaction_discounts:82b4a764d9cd4b14780e011e33",
"property_id": "transaction_discounts",
"property_name": "Discount",
"property_value": [],
"last_change": null
},
{
"property_record_id": "item_price:82b4a764d9cd4b14780e011e33",
"property_id": "item_price",
"property_name": "Item Price",
"property_value": null,
"last_change": null
}
]
}
],
"type_id": "86e05affc7a7abefcd513ab400",
"total_price": 18.96,
"currency_id": "86e05affc7a7abefcd513ab400",
"card_number": "2001990001884",
"cashdesk_number": 2,
"last_change": "2012-11-14 21:15:52.918601"
}
],
"total_items": 156919
}
}
Response code: 200 (OK); Time: 623ms; Content length: 3457 bytes
Get information about a specific purchase
[badge-blue GET] /purchases/{purchase_id}
Parameter name | Type | Description | Mandatory (Yes/No) |
---|---|---|---|
purchase_id | string | The unique id for the purchase | Yes |
Status code: 200 OK
Output structure : Purchase
GET https://<projectURL>/rest-api/enterprise-interface/v1.0/purchases/8bc3btbb6f14765b3025cea06c
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZXJwcmlzZV9pbnRlcmZhY2U6NDU3NDJhMDAxNmEyZjctNDI3YWUwMTM0NmMyOWQxNmE4NzI1MWZlzZmMzcwNmI2MDJmDfN2Q2Mw==
HTTP/1.1 200 OK
Date: Tue, 20 Oct 2020 13:21:07 GMT
Content-Type: application/json; charset=utf-8
{
"data": {
"purchase_id": "8bc3bbb6f147465b025cea06c",
"customer_id": "8bc8ea4c1466859cba26e522f",
"store_id": "8fd73167342d06899c4c15320",
"external_purchase_id": "274430",
"payment_time": "2012-10-04 11:00:13",
"items_count": 9,
"purchase_items": null,
"type_id": "86e05affc7a7abefcd51ab400",
"total_price": 35.47,
"currency_id": "86e05affc7a7abefcd53ab400",
"card_number": "2001990001884",
"cashdesk_number": 1,
"last_change": "2012-10-04 10:54:07.994253"
}
}
Action method shows credit, point and voucher summary of purchase.
[badge-blue GET] /purchases/{purchase_id}/actions/payment-summary
Parameter name | Type | Description | Mandatory (Yes/No) |
---|---|---|---|
purchase_id | string | The unique id of the purchase | Yes |
Status code: 200 OK
Output structure : object
Parameter name | Type | Description |
---|---|---|
earned_points | float | Amount of earned points of the purchase. |
used_credits | float | Amount of credits used to pay of the purchase |
used_points | float | Amount of points used to pay of the purchase |
used_points_total | float | Amount of points used to pay and used in vouchers of the purchase |
used_vouchers | Voucher[] | List of used vouchers |
GET http://<projectURL>/rest-api/enterprise-interface/v1.0/purchases/81c08d0187y48b2106387694bf/actions/payment-summary
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZfJwcmlzZV9pbnRlcmZhY2U6MGNjMMzYTQE1NDg1OTNiYzJiMjYxOTQxNGY1ZjhhNGMyOTJmNjEwMzI3ZmMwNWZiNzUxYzNhNw==
HTTP/1.1 200 OK
Date: Tue, 20 Apr 2021 09:28:39 GMT
Content-Type: application/json; charset=utf-8
{
"data": {
"earned_points": 376,
"used_credits": 0,
"used_points": 0,
"used_points_total": 0,
"used_vouchers": []
}
}
Method returns all available rewards for POS installation. The output contains list of all available and valid rewards. Each reward contains a parameter of maximum usage of rewards in a purchase. If amount equals zero, reward can not be applied. Rewards are allways connected to products through bill items.
[badge-green POST] /purchases/actions/recommended-best-rewards
Parameter name | Type | Description | Mandatory (Yes/No) |
---|---|---|---|
store_id | string | Id of store | Yes |
cashdesk_number | string | Number of the cashdesk in store | Yes |
card_number | string | A customer's card number | Yes |
reward_list_type | string | Type of the rewards Possible values: F - full (all manual rewards available and valid for the specific POS)/ C -condensed (only manual rewards corresponding to items on the bill - maxCount not equals zero)/ A - all rewards list including automatic apply this is only for the DATA CUBE |
Yes |
bill | Bill | Structure of bill from POS | Yes |
Status code: 200 OK
Output structure : object
Parameter name | Type | Description |
---|---|---|
recommended_best_rewards | RecommendedReward[] | List of the best rewards for POS |
total_items | integer | Count of all found rewards |
POST https://<projectURL>/rest-api/enterprise-interface/v1.0/purchases/actions/recommended-best-rewards
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZXJwcmlzZV9pbnRlcmZhY26ZDxYmU2ZDkxyYjA4ZGMyZWQwMzkxYmFmOTkyMjhkNjJmN2IzMTk1MzM1YmYwMzhmMDQwMzBiZGQxMA==
{
"store_id": "8fd73167342d06899c15320",
"cashdesk_number" : "1",
"reward_list_type" : "F",
"bill": {
"bill_id": "8fbea1c1eaa8edd35e7f278",
"payment_time": "2016-06-30T15:5:49+02:00",
"currency_id": "8bed991c6a470eaaffbf048",
"total_price": "700",
"bill_items": [{
"plu_ids": [{
"list_code": "GLOBAL",
"code": "abc"
}],
"plu_name": "qwer",
"category_plu_id": "8fbea1c1ea8edda5e67f27Q",
"vat_rate": 4,
"quantity": 2,
"paid_amount": 6,
"price": 4,
"bill_item_id": "6fd73167342d6899c415320",
"loyalty_off": true,
"purchase_item_type_id": "89d3d433c86ec59fe51b18a"
}]
}
}
HTTP/1.1 200 OK
Date: Wed, 21 Apr 2021 08:54:24 GMT
Content-Type: application/json; charset=utf-8
{
"data": {
"recommended_best_rewards": [
{
"code": "PTV138",
"name": "SVK_wine",
"reward_priority": 9,
"max_count": null,
"description": "SVK_wine",
"reward_properties": {
"image": "",
"valid_from": "00:00:00",
"valid_to": "00:00:00"
}
}
],
"total_items": 1
}
}
The method processes bill closure requests. CareCloud returns information about discounts, applied vouchers, and points used for payment that change the bill's final price.
[badge-green POST] /purchases/actions/accept-payment
Parameter name | Type | Description | Mandatory (Yes/No) |
---|---|---|---|
store_id | string | Id of the store | Yes |
cashdesk_number | integer | A store cashdesk number | Yes |
card_number | string | A customer's card number | No |
payment_type | string | Method of the bill closure Possible values: āSā-standard / āDā- use discount now |
Yes |
max_points | string | Amount of points to be redeemed | No |
max_credit | string | Amount of credits to be used | No |
benefit_codes | string[] | The bill closure will use present codes and recommend discounts | No |
bill | Bill | Structure of a bill from POS | Yes |
Status code: 200 OK
Output structure : object
Parameter name | Type | Description |
---|---|---|
accepted_payment | AcceptedPayment | The structure contains values for applied rewards, vouchers, discounts, and other benefits |
POST https://<projectURL>/rest-api/enterprise-interface/v1.0/purchases/actions/accept-payment
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZXJwcmlzZV9pbnRlcmZhY2U6lWZjMGU0NjFlZmQwZmY5YzU1ODI2NTg4NWM4NmM5MmQwYjRkMzJmYThmYzEzNTE2ZmY5NQ==
{
"store_id": "8fd73167342d06899c4015320",
"cashdesk_number": 1,
"card_number": "2001990002294",
"payment_type": "S",
"max_points": "4",
"max_credit": "7",
"benefit_codes": [],
"bill": {
"bill_id": "89c91bbc4ddd440da11b86756",
"bill_number": "54938",
"payment_time": "2016-06-30T15:51:49+02:00",
"created_by": "Rk",
"currency_id": "8bed991c68a470eaaeffbf048",
"total_price": "700",
"utm": {
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "spring_sale"
},
"bill_items": [{
"plu_ids": [{
"list_code": "GLOBAL",
"code": "NONONO"
}],
"plu_name": "GLOBAL",
"category_plu_id": "8fbea1c1ea8eddca35e67f27Q",
"vat_rate": 4,
"quantity": 2,
"paid_amount": 6,
"price": 4,
"bill_item_id": "8fbea1c1eaa8edda35e67f278",
"loyalty_off": true,
"purchase_item_type_id": "89d3d403c86e8c559fe51b18a",
"customer_id": "86ae806b29ae109233bf2a5f5"
}]
}
}
HTTP/1.1 200 OK
Date: Mon, 26 Apr 2021 17:19:50 GMT
Content-Type: application/json; charset=utf-8
{
"data": {
"accepted_payment": {
"recommended_discounts": [],
"credit_points": 0,
"price_of_credit_points": 0,
"credit": 0,
"benefit_codes": [],
"credit_points_of_this_transaction": 0,
"total_credit_points": 0,
"total_credit": 960,
"messages": []
}
}
}
The method sends the final closed bill to CareCloud. It returns info about success/failure in the response.
[badge-green POST] /purchases/actions/send-purchase
Parameter name | Type | Description | Mandatory (Yes/No) |
---|---|---|---|
store_id | string | Id of the store | Yes |
cashdesk_number | integer | Number of the cashdesk in the store | Yes |
card_number | string | Number of the customer's card | No |
customer_id | string | Id of the customer that made the purchase. You can search customers by plenty parameter in resource customers | No |
bill | FinalBill | Structure of the final bill from POS | Yes |
Status code: 201 Created
Output structure : object
Parameter name | Type | Description |
---|---|---|
purchase_id | string | Id of the created purchase |
POST https://<projectURL>/rest-api/enterprise-interface/v1.0/purchases/actions/send-purchase
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZXJwcmlzZV9pbnRlcmZhYMzcwNWMwMjBkNTQxYjgzNGYzNDkwMzIzYjlhODg1YmE2ZmI2YjMwNjYwMWY0MjVmOGI5NA==
{
"store_id": "8fd73167342d0689c4c01z5320",
"cashdesk_number": 1,
"card_number": "6",
"bill": {
"fiscal": true,
"purchase_type_id": "86e05affc7a7abefzcd513ab00",
"canceled": false,
"payment_type": "S",
"payment_time": "2016-06-30T15:51:49+02:00",
"currency_id": "8bed991c68a4707azaeffbf048",
"total_price": "700",
"payment_recap": {
"credit_points": 7.0,
"amount_for_credit": 4.2
},
"bill_id": 3424746665,
"bill_number": "agkdoqjwe",
"create_date_time": "2016-06-30T15:51:49+02:00",
"bill_items": [{
"plu_ids": [{
"list_code": "GLOBAL",
"code": "NONONO"
}],
"plu_name": "GLOBAL",
"category_plu_id": "8fbea1c1eaa8edcza35e67fr27Q",
"vat_rate": 4,
"quantity": 2,
"paid_amount": 6,
"price": 43333,
"bill_item_id": 4634,
"loyalty_off": true,
"purchase_item_type_id": "89d3d4303c86e8r559fe51b18a"
}],
"utm": {
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "spring_sale"
}
}
}
HTTP/1.1 201 Created
Date: Mon, 26 Apr 2021 11:18:48 GMT
Content-Type: application/json; charset=utf-8
{
"data": {
"purchase_id": "8da9ed69bc5fca59c55a308ce"
}
}
The method assigns customer to the existing purchase. If customer could collect points, he is going to gain coresponding amount of points.
[badge-green POST] /purchases/actions/assign-customer
Parameter name | Type | Description | Mandatory (Yes/No) |
---|---|---|---|
store_id | string | Id of the store | Yes |
external_purchase_id | string | The unique external id of the purchase | Yes |
card_number | string | Number of the customer's card. Parameter is mandatory only if customer_id is not set. | No |
customer_id | string | The unique id of the customer. Parameter is mandatory only if card_number is not set. | No |
Status code: 204 No Content
Output structure : object