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.

 

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