JOY webservice
Getting started
In this article, you can read about JOY integration and its options in the Tau Ceti panel.
JOY is an external integration Yves Rocher uses for order, stock, and campaign code management. Currently, during the order creation process at the last step, JOY validates if a current product stock in JOY and assigned to the altshop campaign code is correct. If it's not correct customer is unable to finish the order with a notification to try again later.
When the order is created in Tau Ceti it's going through an internal check process, which is followed by a JOY check process. After passing both checks the order is being sent to JOY.
Table of contents:
- JOY - TC communication
- Configuration
- Orders to verify
- JOY stocks
- JOY / Failed orders report
- JOY / Real time validation
JOY - TC communication
Communication between JOY and Tau Ceti happens in cycles or during certain events. Below you can find used communications between Tau Ceti and JOY:
Cyclic communication
Stock synchronization happens every hour at different times for every environment. Updates stock levels stored in the TC database based on values from JOY. Stocks are retrieved from JOY always using the regular altshop default campaign code. This value uses the Order API.
Stock synchronization schedule:
- Polish environment synchronizes every hour at
XX:00. - Czech environment synchronizes every hour at
XX:12. - Slovak environment synchronizes every hour at
XX:24. - Hungarian environment synchronizes every hour at
XX:36. - Romanian environment synchronizes every hour at
XX:48.
Import of invoice numbers happens every 30 minutes. Retrieves invoice numbers from JOY for orders that, when placed in JOY, did not generate an invoice. The invoice number is used in other processes (i.e.: invoicing, EET CZ). This value uses the Order API.
Export e-commerce orders happen every 3 minutes. Exports orders to JOY. When exporting orders in JOY, Tau Ceti creates and updates consumer data (this doesn't happen anywhere else). The order is exported regardless of the paid status. When exporting orders, Tau Ceti also performs a check to see if a city name definition exists in JOY for the postal code used. If it does not exist, the record is created. In this way, we automatically populate the address dictionary in JOY, because otherwise, JOY would not allow us to save multiple orders. This value uses the Order API.
Export e-commerce order payment information happens every 3min. Exports order payment information if such information was not available when the order was exported. Uses Invoice API.
Event-based communication
Export BaseLinker orders - when a positive validation of an order from BaseLinker is completed. Always creates new consumers in JOY. It does not use existing accounts. Orders with e-payments are exported to JOY only if they have already been paid. It uses Order API.
Import of order status changes and waybill numbers from JOY - when Tau Ceti gets a notification sent to TC API. Order status change information may include a waybill number, which is stored in the database for presentation to the consumer for order tracking. Waybill numbers are also sent to BaseLinker if the notification is for an order originating from BaseLinker.
Checking campaign code and inventory in real-time - at the time of order closing (approval of order placement by the consumer). Uses Order API.
RememberTau Ceti service is waiting 5 seconds for a connection initiation. If the connection is not initiated it will result in a timeout.
If Tau Ceti doesn't receive a response to their request from the JOY service within 30 seconds it will result in a timeout.
Configuration
Initial JOY configuration on a new environment requires joint cooperation between Tau Ceti developer team and the JOY team to set it up properly.
You can find the JOY configuration in the:
System > System / Settings > Integrations > JOY Webservices
 |
| Visualization of the JOY webservices tab in System / Settings |
In the JOY configuration you can find the following options:
- JOY Enabled - A switch that enables or disables JOY integration
- Invoice API: WSDL URL - URL of Invoice API WSDL. This URL shouldn't be changed.
- Invoice API: market code - Market code. This code is provided by JOY
- Invoice API: login - Login provided by JOY, which allows connecting to the JOY API
- Invoice API: password - Password provided by JOY, which allows connecting to the JOY API
- Invoice API: Use Keep-Alive - Defines whether we reuse existing connections to the JOY API when we make more than 1 request to the API in a single process. This option is unstable and may cause issues, so it is recommended to leave it disabled.
- Order API: WSDL URL - URL of Order API WSDL. This URL shouldn't be changed.
- Order API: market code - Market code. This code is provided by JOY
- Order API: login - Login provided by JOY, which allows connecting to the JOY API
- Order API: password - Password provided by JOY, which allows connecting to the JOY API
- Order API: Use Keep-Alive - Defines whether we reuse existing connections to the JOY API when we make more than 1 request to the API in a single process. This option is unstable and may cause issues, so it is recommended to leave it disabled.
- Order API: skip order filters - If enabled, filters set in JOY are ignored. It should be enabled because it is very common to have filters set up in JOY that prevent orders from being placed. If skip orders filters are enabled, filters in JOY do not block order placement.
- API: Technical breaks - Definies in a HH:MM-HH:MM;HH:MM-HH:MM (i.e. 08:00-10:00;22:00-23:00) format when the API technical break occurs. Please do not use e.g. 23:00-01:00 range, as the time is always checked for the current day.
- Stock real time validation - A switch that defines if real-time validation for stocks is enabled when creating a new e-commerce order. If it is enabled, but JOY is unable to validate stocks because of i.e. connection issues customers won't be able to create new orders.
- Campaign codes real time validation - A switch that defines if real-time validation for campaign codes is enabled when creating a new e-commerce order. If it is enabled, but JOY is unable to validate the campaign codes because of i.e. connection issues customers won't be able to create new orders.
- Joy Export Logs: Lifetime (days) - Defines for how long JOY export logs will be stored.
- Delete errors older than (days) - Defines after how many days system deletes JOY errors
- Export company data - A switch that defines if customer company data in the Invoice table should be exported to JOY.
Please notice that JOY allows only for setting company data within customer records. It means that customers placing two orders using the same account, on the same day, with different invoice data will probably receive invoices with the same data as the person/company receiving the invoice. It applies not only to company data, it applies to entire billing data. They are overwritten during the export of every customer's order.
Additionally used fields were added to JOY for Romania only. It means that JOY may not support the usage of these fields for any other country than Romania.
Only billing address company data are transferred to JOY. There is no option to pass company data for delivery data.
Orders to verify
Whenever an order fails an internal Tau Ceti check or JOY check it will be visible with an error message in the:
Orders > Orders / to verify
 |
| Visualization of the Orders / to verify tab |
In the Orders / to verify tab there is an option to
- Re-export the order - The system tries once again to verify the order and re-export it to the JOY. If the verification fails once again the order will be visible once again in Orders / to verify after a short time.
RememberIn most cases whenever an error cannot be re-exported it should be handled by the JOY team on their side unless it's an error with incorrect customer invoice/delivery data, which needs to be fixed in the Tau Ceti panel.
The JOY support team can be contacted via email [email protected].
If you are not sure about the error please contact the Tau Ceti helpdesk team via
email [email protected].
- Mark the order as correctly exported - Severs the connection between Tau Ceti and JOY regarding this order and marks it as correctly exported in the Tau Ceti admin panel.
Warning Marking an order as correctly exported severs the connection between Tau Ceti and JOY regarding this order, which means any updates on both platforms won't be sent to the other platform. This means that the order will also not have a generated invoice.
RememberIn Orders / to verify there are also visible orders with errors from other integrations like Rumanku used in Click & Collect functionality. Rumanku errors can be recognized with a CC: at the beginning of the error message. The JOY team is not handling Rumanku errors.
JOY stocks
JOY stocks functionality can be used to verify a product stock available in JOY as well as it is a quick way to verify if a connection with JOY works correctly, as it will return an error whenever trying to check a stock.
You can find JOY stocks in:
Catalog > Joy stocks
 |
| Visualization of the JOY stocks |
In the JOY stocks you are able to choose a desired campaign code and then type the SKU number of a desired product. By pressing the Check stock button you will be able to see how exactly many pieces of typed product are available for a selected campaign code. You are additionally able to see an XML request sent to JOY and its response.
If typed product is not available in JOY or the connection to JOY doesn't work properly you won't see any product information, but a message that the product couldn't be found.
JOY / Failed orders report
It is possible to see all orders that have not been placed in Tau Ceti admin panel, because of failed JOY campaign code or stock validation. You can find such report with failed JOY orders in:
Reports > JOY / Failed orders
 |
| Visualization of the filter in JOY failed orders report |
In the filters tab we have following options:
- Error time - Defines a range of dates within the errors will be searched for
- Order ID - Defines an order ID of a failed order
- Customer ID - Defines a customer's internal ID.
 |
| Visualization of the filtered JOY failed orders |
With an applied filter, you can see all of the orders in a selected date range that has failed. In the Error column, you can see what was exactly a source of an error.
If the order was placed afterward it's Order ID will be blue and clickable. By clicking the Order ID you will be redirected to the order page.
JOY / Real time validation
Whenever there will be a planned maintenance of JOY webservice Yves Rocher can prepare for that by disabling the real-time validation for campaign codes and stocks. This can be done in JOY system settings described in Configuration chapter, but it can also be automated in:
System > JOY / Real time validation
 |
| Visualization of the JOY real time validation tab |
In the JOY / real time validation tab, we are able to select the:
- Mode - A Enable / Disable choice. Whenever the mode is set to Disable it will disable both validations (stock and campaign code) for a selected execution time, whenever it's set to Enable it will enable them.
- Execution time - A local time whenever the selected mode should be executed. Below the field, you are able to see a local time for a selected environment. As execution happens according to the local time please check if provided information by JOY applies to the environment local time i.e. if the JOY team has provided information that they have maintenance at 23:00 UTC+2 and the selected environment country is located in a UTC+3 timezone you have to select the hour 00:00.
The schedule applies only once for a selected mode, so there is no automatic way to enable the validation back whenever it's been disabled. In this case please remember to put another schedule, whenever you want to enable the validations back. For example:
29.07.2023 22:00 - Disabled mode
29.07.2023 23:00 - Enabled mode
This way JOY validation will be disabled for an hour on a selected environment.