POST method only
Description:
Use this service to provide the commercial data of a transaction of type “exchange”.
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/exchanges/ |
| Production | https://api.tidisystems.com/commercial-data/exchanges/ |
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. Must be consistent across operations to link operations to the same 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. Must be consistent across operations to link operations to the same shop | |
|
shop_address |
(2) | string | Address of the shop. For instance, "shop_address": "Great Street, 45" | |
|
} |
End of dictionary | |||
|
returns |
[ |
(1) | list | Items' data of all items returned |
| { | (1) | dict | Data of every single item returned | |
|
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 that your client’s client is applying on this product, if any. For instance, "promotion": “Christmas campaign” | |
| reason | (4) | string | The reason for returning this object, if your client’s client wishes to share it. For instance, "reason": "Lower price at competitor" | |
|
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/R-742890” | |
|
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 | Number of units or bulk weight of this product returned. For instance, "units": 3 or "units": 1.54 | |
|
} |
End of dictionary | |||
|
] |
End of list | |||
|
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 discount applied on this product. As an example, if you apply 15.5% discount, write “discount”: 15.5 | |
|
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/R-742890” | |
|
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 | 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" | |
|
current_receipt_id |
(1) | string | The ID of the original transaction this exchange transaction is referring to and as on your systems, so that you can identify it in the future. For instance, "currentReceiptId": 1. Pro tip 1: we will validate this field on our system. If you have already provided this as a previous transaction’s receiptId or currentReceiptId, then both transactions will also be linked on our system and your client will see the full history linked for them on their TIDI account as well. If you did not provide it previously, the transaction will still be linked to your client but they will not see to which transaction it was previously linked on our systems. Pro tip 2: this field could be the same as receiptId in case you do not generate new receipt Id’s for exchanges in your system | |
|
api_version |
(1) | string | The API version you are targeting | |
|
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 |