In this section will be presented the methods to be able to carry out transactions (movements) in the platform. Note that the hash that is obtained through the balance request is used in these same transactions.
The insertion of a movement is the process in which, after internal validations of the API (namely secondary_id and hash) a movement is inserted into the system.
curl -XPOST -H 'APIKEY: [the_tenant_api_key_string]' -H "Content-type: application/json" -d '
{
"secondary_id": "DEV_QERO_MOV_1",
"vat": "123456789"
"type": "BUY",
"referral": "351-922222222", */used only in SaaS system/*
"external_date": "2018-11-21T12:05:51Z",
"amount_gross": 1843,
"amount_net": 1498,
"products": [ {
"id": "PAPELARIA;\u001b;9010000000000",
"separator": ";\u001b;",
"quantity": 1,
“promotion”: 0,
"amount_unit": {
"gross": 1843,
"net": 1498
},
"iva": 23,
"description": "inteiro"
} ],
"identity_name": "SAGEHBT",
"credit_out": 0,
"hash": "0",
"coupons_name":[{"name":"10% off", "coupons":"rt34eds3"}]
}' 'https://[the_tenant_endpoint]/public-api/client/[secondary_id]/movement'
The secondary_id in “https://[the_tenant_endpoint]/public-api/client/[secondary_id]/movement” referes to the client identification, and can be:
Fields to take into account:
If everything has gone as expected, the API response will be as follows:
{
"secondary_id": "DEV_QERO_MOV_1",
"vat": "123456789"
"type": "BUY",
"external_date": "2018-11-21T12:05:51Z",
"amount_gross": 1843,
"amount_net": 1498,
"products": [ {
"id": "PAPELARIA;\u001b;9010000000000",
"separator": ";\u001b;",
"quantity": 1,
"amount_unit": {
"gross": 1843,
"net": 1498
},
"iva": 23,
"description": "inteiro"
} ],
"credit_out": 0,
"identity_name": "SAGEHBT",
"percentages": [ {
"product_id": "9010000000000",
"percentage": "10",
"percentage_by_campaign": [ {
"campaign_id": 23,
"percentage": 10
} ]
} ],
"credit_in": 0
}
It should be noted that, in this particular case, the movement was covered by an existing campaign. The percentages field (which is an array of JSON objects) tells you which product is involved, which discount percentage you have, and also the percentage discount for each single campaign (a product may be involved in more than one campaign).
The credit_in field indicates the points the customer won on the move. In this particular case you did not earn any points with this transaction.
In case of error, the reason for the error is displayed. If you try to insert a movement with an invalid hash, we will have the following response:
{
"message": "Hash invalid to this movement"
}
Or, if you have a secondary_id of repeated movement, we will have the following answer:
{
"message": "secondary_id already exists!"
}
CURL request of the insertion request of a new move to the customer with the secondary_id 351-911111111 (to identify a mobile number the argument must begin with "tele-"):
curl -XPOST -H 'APIKEY: [the_tenant_api_key_string]' -H "Content-type: application/json" -d '
{
"campaign_id" : 0 //The campaign_id = 0 is the default campaign,
"external_date" : "2023-03-20 15:45:00",
"points": "+500",
"reason" : "insertion of points
",
"secondary_id" : "Manual", //The content must be always "Manual"
"type" : "MANUAL", //The content must be always "MANUAL"
"expire_days" : "365"
}' 'https://[the_tenant_endpoint]//public-api/client/[secondary_id]/movement/manual'
Fields to take into account:
This movement allows to cancel a movement of the BUY type inserted previously. This order allows the return to be partial (example: 4 units of a product were purchased and only 2 were returned).
The structure of the request is very similar to that of the movement of type BUY, being that the field external_return_id corresponding to the secondary_id of the movement of BUY is added. For RETURN movement it is also necessary that there is a unique secondary_id. The products to be returned are placed in the products field as well as the quantity to be returned.
CURL request for a RETURN movement:
curl -XPOST -H 'APIKEY: [the_tenant_api_key_string]' -H "Content-type: application/json" -d '
{
"secondary_id": "RETURN_DEV_QERO_MOV_2",
"external_return_id": "DEV_QERO_MOV_2",
"type": "RETURN",
"referral": "351-922222222", */used only in SaaS system/*
"external_date": "2018-11-21T13:05:51Z",
"amount_gross": 1843,
"amount_net": 1498,
"products": [ {
"id": "PAPELARIA;\u001b;9010000000000",
"separator": ";\u001b;",
"quantity": 1,
"amount_unit": {
"gross": 1843,
"net": 1498
},
"iva": 23,
"description": "inteiro"
} ],
"identity_name": "SAGEHBT",
"hash": "D7E5nI"
}' 'https://[the_tenant_endpoint]/public-api/client/[secondary_id]/movement'
Fields to take into account:
The secondary_id in “https://[the_tenant_endpoint]/public-api/client/[secondary_id]/movement” referes to the client identification, and can be:
Like the previous request, in case of error the reason for the error is presented. If you try to insert a movement with an invalid hash, we will have the following response:
{
"message": "Hash invalid to this movement"
}
Or, if you have an external_return_id of a movement that does not exist, we will have the following answer:
{
"message": "No movement to that return"
}
If the return has proceeded as expected, we will have the following response from the API:
{
"date": "2018-11-21 14:20:55",
"type": "RETURN",
"store_id": "8",
"credit_in": "0",
"amount_net": "0",
"credit_out": 0,
"movement_id": "3",
"amount_gross": "0",
"secondary_id": "EGOI-RET-RETURN_DEV_QERO_MOV_2",
"external_date": "2018-11-21T13:05:51Z",
"amount_promotional": "0",
"external_return_id": "DEV_QERO_MOV_2",
"remaining_products": [ ],
"products": [ {
"id": "PAPELARIA;\u001b;9010000000000",
"separator": ";\u001b;",
"quantity": 1,
"amount_unit": {
"gross": 1843,
"net": 1498
},
"iva": 23,
"description": "inteiro"
} ]
}
The products field indicates the products that were returned and the remaining_products field indicates the products that were not returned for the movement in question.
Briefly the hold is a movement type that is sent to the API but is not inserted into the system. It essentially serves to verify the implementation of campaigns and other inherent validations. The CURL of the request is equal to the movement of type BUY, the only difference is in the type, which is of type HOLD.
curl -XPOST -H 'APIKEY: [the_tenant_api_key_string]' -H "Content-type: application/json" -d '
{
"secondary_id": "DEV_QERO_MOV_1",
"vat": "123456789"
"type": "HOLD",
"referral": "351-922222222", */used only in SaaS system/*
"external_date": "2018-11-21T12:05:51Z",
"amount_gross": 1843,
"amount_net": 1498,
"products": [ {
"id": "PAPELARIA;\u001b;9010000000000",
"separator": ";\u001b;",
"quantity": 1,
“promotion”: 0,
"amount_unit": {
"gross": 1843,
"net": 1498
},
"iva": 23,
"description": "inteiro"
} ],
"identity_name": "SAGEHBT",
"credit_out": 0,
"hash": "0"
}' 'https://[the_tenant_endpoint]/public-api/clients/transaction/hold/[secondary_id]'
The secondary_id in “https://[the_tenant_endpoint]/public-api/clients/transaction/hold/[secondary_id]” referes to the client identification, and can be:
If a movement of the type HOLD is inserted and it's necessary to remove that movement, the next web service should be called:
curl -XPOST -H 'APIKEY: [the_tenant_api_key_string]' -H "Content-type: application/json" -d '
{
"identity_name": "[store_name]",
"amount_gross": "[amount_gross]"
}' 'https://[the_tenant_endpoint]/public-api/clients/transaction/hold/cancel/[secondary_id]'
The store_name field should be the same identity_name sent in the HOLD movement, and also the amount_gross should be the same.
The secondary_id in “https://[the_tenant_endpoint]/public-api/clients/transaction/hold/cancel/[secondary_id]” referes to the client identification, and can be:
This service is used to captivate credit. For example if you are using an e-commerce and the purchase is not sent immediately, you can captivate the balance that the client is going to use in that purchase. This credit must be sent in cents (5 euros equal to 500)
For exemple: If an client is using 5 euros in credit_out, you can captivate that credit until the purchase is really finished.
curl -XPOST -H 'APIKEY: [the_tenant_api_key_string]' -H "Content-type: application/json" -d '
{
"credit": "500"
}' 'https://[the_tenant_endpoint]/public-api/balance/captivate/[secondary_id]'
The secondary_id in “https://[the_tenant_endpoint]/public-api/balance/captivate/[secondary_id]” referes to the client identification, and can be:
Before you send the transaction, you need to cancel the captivated balance using the service below. The service below needs an hash that will be generated and returned when you create an captivate.
Example of an response:
{
"balance_captivate_id": "5",
"client_id": "111111111",
"credit": "500",
"hash": "Fz1nlCmU"
}This service is used to cancel and captivate. Canceling the captivate will return that balance to the client.
curl -XPOST -H 'APIKEY: [the_tenant_api_key_string]' -H "Content-type: application/json" -d '
{
"hash": "17fhyso9"
}' 'https://[the_tenant_endpoint]/public-api/balance/captivate/[secondary_id]/cancel'
The secondary_id in “https://[the_tenant_endpoint]/public-api/balance/captivate/[secondary_id]/cancel” referes to the client identification, and can be:
CURL request to obtain the desired movement information.
CURL request to retrieve movements of the customer with the secondary_id 351-911111111 (to identify a mobile number the argument must begin with "tele-"):
curl -XGET -H 'APIKEY: [the_tenant_api_key_string]'
'https://[the_tenant_endpoint]/public-api/client/[secondary_id]/movement
In this request, to obtain the movements of a given customer, the argument secondary_id should be changed to a mobile number or a card number.
You can also search for a specific movement adding the ?secondary_id=TRANSACTIONID (ex: ?secondary_id=FS129349)
The flow to insert a movement is:
The return of a movement can be done in two flows:
This two flows are the same, the point here is that the system can handle multiple returns for a single movement.
The flow is similar to the movement:
Common mistakes made in the purchase movement integration.