Cegid Y2 Module Integration Guide

This article provides direction on how to set up and configure the Cegid Y2 Integration Module and an overview on its feature set.

Table of Contents 

• Purpose
• Prerequisites
• Connector Configuration
• Initial setup
• CRM customer link
  • Assisted Customer Matching / Creation
  • Customer creation fields

  • Import Y2 Customers into Booxi

• Receipt creation
• Limitations
• Troubleshooting
• Documentation and External Links

Purpose

The purpose of the connector is to bridge Booxi and Cegid Y2 POS and CRM by linking Booxi clients to Y2 customers as well as creating sales from appointments using our custom POS Sale dialog. 

Prerequisites 

• The Integration Module and Connector require an active Cegid Y2 account version 14, 18 and 19.
• The Cegid Y2 account assigned in the integration module MUST have permissions to perform the following actions. Failing to do so will prevent the module from working as intended.

• • Create sales document
  • Create customers
  • View customers
  • Register code of store associated with the Booxi account
  • Y2 Product ID which will be used to charge no-shows

Information Required for the Module Activation

The following information must be provided to Booxi for the module activation. 

• The URL of the Y2 hosting instance
• Database Name
• Authentication Type (BASIC or NTLM)
• Credentials for Booxi to log in

Connector Configuration

Module Activation and Initialization

Information required

• URL of your Y2 hosting instance (the URL should not include the port :443)
• Database name
• Authentication Type (BASIC or NTLM)
• Credentials to log into that instance

It is highly important to make sure that the Cegid Y2 account assigned to the integration module has the necessary rights to perform the following tasks:

• Create sales documents
• Create customers
• View customers

• Register code of store associated with the Booxi account
• Y2 Product ID which will be used to charge no-shows

Module Activation and Initialization

1. Activate and configure the integration module in Booxi’s Back Office, under “My Business”.
   
2. Fill out all fields with the appropriate information.
   
3. Once again, make sure the port ":443" is not included in the hosting URL.
4. Save your changes.

Once the integration module is activated and configured. Several changes will appear in the Back Office’s interface.

• A Y2 id field on the Service and Personnel Details page.
• Option to create a Cegid Sale from an appointment.

---

Initial Setup 

Once the integration module is activated and configured, it is highly recommended to link services and staff in Booxi to their equivalent in Y2. This will be required to create sales on-hold in Y2 from appointments made in Booxi. 

 

How to Link Services and Staff

Services as well as Personnel created in Booxi can be linked by assigning a Y2 IDs. 

To manually link a service or personnel, follow these steps:

Link a Booxi Service with a Product ID in Y2

1. In the Back Office, select any service from the list. 
2. Under “Service Details”,  you can assign or edit a Y2 product ID.

 

Link a Booxi Personnel with an Employee in Y2

1. In the Back Office, select any employee from the list.
2. Under “Personnel Details”, you can assign or edit an employee ID.

Features

The integration module comes with a set of features (current and upcoming). Here are the main features currently available:

• CRM Customer Link
• Receipt Creation
  

---

CRM Customer Link

To facilitate the creation of an invoice in Y2, from a booking made in Booxi, linking data from both platforms is necessary. In order to do so, Booxi provides the following feature.

---

Assisted Customer Matching / Creation

Upon creating a receipt, Booxi will validate if its client has been linked to a Y2 customer. If so, the Y2 customer ID will be used to create a receipt. If not, Booxi will perform various searches to identify a list of best candidates. Booxi will present these candidates as a list of suggestions along with the option to create a brand new customer. If a match is selected, Booxi will link the client to the selected customer. Otherwise, if “Add New” is selected, Booxi will create the new customer in Y2 and link it with the client entry in Booxi .

Matching Configuration Options:

• Unique Email is ON (emails in Y2 are mandatory and unique)
• Booxi will perform a search for matching customers in Y2 based on the email and place this result first in the suggestion list.
• Unique Email is OFF (emails in Y2 are not mandatory and might not be unique)
• Booxi will perform a search for customers in Y2 using a matching combination of name+email, name+phone (mobile or landline), name, email or phone; the matching will be done sequentially (i.e. in the order described). If entries are found, the best candidates will be listed first.

• National Phone Number Format is ON (if Y2 is configured as such)

• When searching for a phone number (mobile or landline), Booxi uses international phone number format, unless national formatting is turned on. In such cases, Booxi converts any phone number in the appropriate format.
• Ex: +330612345678 is converted in 06 12 34 56 78
• Invert Names is ON (for countries or regions where last name is preferred)
• When searching for a client match, Booxi will reformat a customer’s name by inverting the first and last name, combining both as a single string and removing any spaces the resulting string might have.

In all cases, Booxi returns a list of suggested matches with the best one appearing first along with the option  “Add New” customer, which can be selected to create the new customer in Y2 if no proper match is suggested.

Interfaces:

API	CustomerWcfService
API Calls	SearchCustomerIdsAddNewCustomer (Y2 CustomerID)

---

Customer Creation Fields

This section lists properties set by Booxi when creating a new customer.

Properties

Payload example:

<?xml version='1.0' encoding='UTF-8'?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
    <S:Body>
        <AddNewCustomer xmlns="http://www.cegid.fr/Retail/1.0"
                        xmlns:ns2="http://schemas.microsoft.com/2003/10/Serialization/Arrays"
                        xmlns:ns3="http://www.cegid.fr/fault"
                        xmlns:ns4="http://schemas.microsoft.com/2003/10/Serialization/">
            <customerData>
                <EmailData>
                    <Email>jsmith@hotmail.com</Email>
                </EmailData>
                <FirstName>John</FirstName>
                <IsCompany>false</IsCompany>
                <LastName>Smith</LastName>
                <PhoneData>
                    <AlternativePhoneNumber>+15149999999</AlternativePhoneNumber>
                    <CellularPhoneNumber>+15141234567</CellularPhoneNumber>
                </PhoneData>
                <SalesPersonId>MFR005</SalesPersonId>
                <UsualStoreId>MFR001</UsualStoreId>
                <BirthDateData>
                    <BirthDateDay>1</BirthDateDay>
                    <BirthDateMonth>1</BirthDateMonth>
                    <BirthDateYear>1900</BirthDateYear>
                </BirthDateData>
                <OptinAlternativeEmail>AskCustomer</OptinAlternativeEmail>
                <OptinEmail>AskCustomer</OptinEmail>
                <OptinMobile>AskCustomer</OptinMobile>
            </customerData>
            <clientContext>
                <DatabaseId>BOOXI_UAT</DatabaseId>
            </clientContext>
        </AddNewCustomer>
    </S:Body>
</S:Envelope>

---

Import Y2 Customers into Booxi

Upon request, Booxi can import customer data from Y2 into Booxi’s database. This service is dispensed once and uses a strict CSV file format.

Features:

• Imported customers will be identified using the unique cegid customer id. Duplicates are rejected at export.
• Imported customers without first and last name will be rejected.
• Imported customers with invalid phone and email format will also be rejected.
• Some fields require specific values described in the standard import CSV file format.

---

Receipt Creation
 

Create a sale from an appointment

When creating a sale from an appointment, Booxi will make use of links created between services and products, staff and employee, as well as clients and customers if such links have been established. If a client hasn’t been linked to a corresponding Y2 customer, Booxi will try to find a match in Y2 and provide a list of suggestions as well as the option to create a new customer.

Matching is performed using email address or phone number. Perfect matches with name, phone number and email are listed first in the list of suggestions while partial matches are listed last. Once the process is completed,  a new “On-Hold” sale can be found in Y2.

 

On-Hold Receipt (Ticket en Attente)

Description:

Create a “On-Hold” (Ticket en attente) receipt in Y2 from a booking made with Booxi . An invoice is then completed in Y2 by a member of staff.

 

Workflow and Features:

• Create a receipt “On-Hold” in Y2 from a Booxi appointment using the following information:
• The register code associated with this Booxi account in the connector configuration.
• The Y2 product id associated with the Booxi service 
• The Y2 employee is associated with the Booxi staff.
• Creation is triggered when a staff selects the option to create a sale from a booking.
• Staff retrieves the receipt “On-Hold” (ticket en attente)  in Y2 and completes an invoice.

Interfaces:

Payload example:

<?xml version='1.0' encoding='UTF-8'?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
    <S:Body>
        <Create xmlns="http://www.cegid.fr/Retail/1.0"
                xmlns:ns2="http://schemas.microsoft.com/2003/10/Serialization/Arrays"
                xmlns:ns3="http://www.cegid.fr/fault" xmlns:ns4="http://schemas.microsoft.com/2003/10/Serialization/">
            <createRequest>
                <Header>
                    <Active>true</Active>
                    <Comment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
                    <CurrencyId>EUR</CurrencyId>
                    <CustomerId>MFR0010003433</CustomerId>
                    <Date>2024-09-29T00:00:00.000</Date>
                    <ExternalReference>A12690013</ExternalReference>
                    <InternalReference>8077ab9b-da86-42e7-8410-d1dd270a74f0</InternalReference>
                    <Origin>Shop</Origin>
                    <SalesPersonId>MFR005</SalesPersonId>
                    <StoreId>MFR001</StoreId>
                    <TaxExcluded>false</TaxExcluded>
                    <Type>ReceiptOnHold</Type>
                </Header>
                <Lines>
                    <Create_Line>
                        <Comment>29 sept. 2024, 14:00:00</Comment>
                        <ItemIdentifier>
                            <Reference>80096064</Reference>
                        </ItemIdentifier>
                        <NetUnitPrice>260</NetUnitPrice>
                        <Quantity>1</Quantity>
                        <UnitPrice>260</UnitPrice>
                    </Create_Line>
                </Lines>
            </createRequest>
            <clientContext>
                <DatabaseId>BOOXI_UAT</DatabaseId>
            </clientContext>
        </Create>
    </S:Body>
</S:Envelope>

Limitations

• The Integration Module and Connector require cegid Y2 version 14 or 18.

Troubleshooting

This section presents common issues, their cause and how to resolve them.

Action “Not Authorized” and “502” Message Upon Creating a Sale

Error Messages Viewing this customer (“name of customer”) is not authorized. Associating customer (“name of customer”) to store (FR032M) is not authorized. Creating a Sale returned a 502 message.

Resolution If you detect anomalies when creating a sale, please make sure that your CegidY2 account has the access rights to perform such actions. Please refer to Module Activation and Initialization for further details on how to make such a change.

Documentation and External Links

APIs and API Calls

Complete list of APIs and API Calls used by Booxi in its interactions with Cegid Y2.

API	API Calls
CustomerWcfService	SearchCustomerIds AddNewCustomer (“Y2 CustomerID”)
SaleDocumentService	Create (Type: ReceiptOnHold)