Sales

You are here: Home » Commercial Data » Sales

POST method only

Description:

Use this service to provide the commercial data of a transaction of type “sale”.

The identification of the users involved in this request, you and your client, can be provided either on the user_ids section of the body as part of the JSON payload or in the header third_party_cert. The process to use the third_party_cert is described here. The commercial data must be provided in the body in either way.

Important: if the relation between you and your client is not showing as “Accepted” in your account, this request will get blocked. You may read this to understand how to get it accepted.

If you wish to integrate the QR code in your front-end, please review a code sample here.

Environment	Endpoint
Testing	https://testapi.tidisystem.com/commercial-data/sales/
Production	https://api.tidisystems.com/commercial-data/sales/

Click to open our sandbox on Postman

Input:

Body:

1st JSON level	2nd JSON level	Required	Type	Description
user_ids	{	(5)	dict	Identifiers of users involved in this transaction: you and the company
	user_token	(2)	string	The user token as described here
	relation_key	(6)	string	The relation key as described here
	shared_provider_id	(6)	string	The shared provider Id as described here
	}			End of dictionary
client	{	(4)	dict	End-user data to link the TIDI-receipt
	client_email	(2)	string with email-like format	Email of the client to the send the email to. For instance, "client_email": "example@gmail.com"
	}			End of dictionary
employee	{	(4)	dict	Data of the employee that performed the transaction. Click here to understand the behaviour of this dict.
	employee_id	(2)	string	ID of the employee
	employee_name	(2)	string	Name of the employee. For instance, "employee_name": "John"
	employee_surname	(4)	string	Surname of the employee. For instance, "employee_surname": "García Ramírez"
	}			End of dictionary
shop	{	(4)	dict	Data of the shop where the transaction was performed. Click here to understand the behaviour of this dict.
	shop_id	(2)	string	ID of the shop
	shop_address	(2)	string	Address of the shop. For instance, "shop_address": "Great Street, 45"
	}			End of dictionary
sales	[	(1)	list	Items' data of all items sold
	{	(1)	dict	Data of every single item sold
	discount	(4)	float	The discount applied on this product. As an example, if you apply 15.5% discount, write “discount”: 15.5
	promotion	(4)	string	The promotion applied to this product, if any. For instance, "promotion": “Christmas campaign”
	brand	(4)	string	The brand of the product. For instance, "brand": “Nike”
	currency	(1)	string	The currency in which the price of the product is denominated in ISO-4217, i.e. if it’s USD 20.45, give “currency”: “USD”
	price	(3)	int	The price of the product with the VAT included, i.e. if it’s USD 20.45, give “price”: 2045
	price_without_vat	(3)	int	The price of the product with the VAT excluded, i.e. if it’s USD 20.45, give “price_without_vat”: 2045
	product_name	(1)	string	The name of the product involved in the transaction. For instance, "product_name": "trousers"
	product_subtype	(4)	string	The secondary level of product classification as on your systems. For instance, "product_subtype": "jeans" in the case of a trouser.
	product_type	(4)	string	The primary level of product classification as on your systems. For instance, "product_type": "cloth" in the case of a trouser.
	purchasers_id_reference	(4)	string	The ID of this product as on your client’s provider’s systems, to identify it in the future. For instance, "purchasers_id_reference": “65/R742890”
	sellers_id_reference	(1)	string	The ID of this product as on your systems, to identify it in the future. For instance, "sellers_id_reference": “7859403”
	vat	(1)	float	The VAT percentage applied. If VAT = 7.7%, give “vat”: 7.7
	units	(1)	int or float	Number of units or bulk weight of this product sold. For instance, "units": 3 or "units": 1.54
	}			End of dictionary
	]			End of list
shipping		(1)	int	The shipping cost involved. For instance, if it is CHF 10.00, write “shipping”: 1000
subtotal		(4)	int	The subtotal of this transaction, this is, including the VAT amount, as on your client’s screen. For instance, if it is USD 155.50, give “subtotal”: 15550. Warning: in the case that it is not provided, it will be automatically calculated by us from each item’s price, price_without_vat, vat, units and/or discount. If you want the amount calculated by you to be reflected in the TIDI-receipt, please provide this number. For more information, please read this
taxes		(4)	int	The total taxes applied on this transaction. For instance, if it is USD 155.50, give “taxes”: 15550. Warning: in the case that it is not provided, it will be automatically calculated by us from each item’s price, price_without_vat, vat, units and/or discount. If you want the amount calculated by you to be reflected in the TIDI-receipt, please provide this number. For more information, please read this
total		(4)	int	The total of this transaction, including the VAT amount, as on your client’s screen. For instance, if it is USD 155.50, write “total”: 15550. Warning: in the case that it is not provided, it will be automatically calculated by us from each item’s price, price_without_vat, vat, units and/or discount. If you want the amount calculated by you to be reflected in the TIDI-receipt, please provide this number. For more information, please read this
receipt_id		(1)	string	The ID of this transaction on your systems, so that you can identify it in the future using your own ID. For instance, "receipt_id": "3-ERQ1542"
api_version		(1)	string	The API version you are targeting. For instance "api_version": "2023_11"
operation_datetime		(1)	string	The datetime of the operation in ISO-8601 standard. For instance: "operation_datetime": "2022-10-13T18:03:48+02:00"

Headers:

Key	Required	Type	Description	Obtained by
third_party_cert	(5)	string	The third-party certificate obtained from another endpoint	Check

(1) Compulsory field and cannot be null or empty

(2) If the parent is not null, this field has to appear and cannot be null or empty

(3) Either price or price_without_vat must be provided. In the event of both being provided, the leading one will always be price when calculating the subtotal and total fields.

(4) Optional field

(5) Either the body attribute user_ids or the header third_party_cert must be provided. In the event of both being provided, the leading one will always be user_ids when understanding what users are involved in this transaction.

(6) Either relation_key or shared_provider_id must be provided. In the event of both being provided, the leading one will always be relation_key when understanding what company this data belongs to.

Output:

1st level Key	2nd level Key	Type	Description
png_with_qr_bytes_64encoded_as_string		string	The PNG with the QR code generated, created as a bytes object, then encoded in base-64 and finally provided to you as a string
operation_id		int	ID of the transaction created in our systems (counting all transactions generated, not only of this client of yours), relational only in TIDI’s DB
id_provider_operation		int	ID of the transaction of your client created in our systems (referred just to this client), relational only in TIDI’s DB. This will be the recently-created receipt ID of this client within TIDI’s DB
status		string	“OK” if the request was correct; “NOK” otherwise
http_status		int	The HTTP status code
error_trace:	[	list	List of errors' data that occurred during the request
	{	dict
	error_name	string	The error that occurred during the request. You may retrieve more information about it with parameter “errors_url”
	error_message	string	The explanation of the error
	error_code	string	The internal error code, in case you need to contact support to get it fixed.
	}
	]
errors_url		string	The URL to the list of errors, to retrieve more information