Evoliz Integration Guidelines for Ecommerce

Welcome to our Guidelines!

We're happy to share with you our new SDK! Please check our Product Changelog to see the main updates.

You'll find comprehensive guides and documentation to help you start integration Evoliz API as quickly as possible, as well as support if you get stuck.

Quickstart

Evoliz provides an API for retrieving and creating data in your account such as orders, invoices and customers.

After creating an account on Evoliz and subscribing to an offer, you will be able to create your API credntials and use them with the API, allowing you to start developing your application immediately.

These Integration Guidelines are designed to help you integrate Evoliz into your system.

Sofware Development Kit

The Evoliz PHP Sofware Development Kit provides convenient access to the Evoliz API from applications written in the PHP language. The use of the SDK facilitates the integration of Evoliz by providing a pre-defined set of classes for API resources that initialize themselves dynamically from API responses which makes it compatible with a wide range of versions of the Evoliz API. There are also many integration examples.

The SDK is available on GitHub. You can find the source code, the different examples, the documentation and the tests. The SDK is open to collaboration, so do not hesitate to propose features in Pull Request, while taking care to respect the code of conduct.

The SDK is available as a package on Packagist. You can install it via Composer like this:

composer require evoliz/evoliz-php

To use the package, use Composer's autoload:

require_once('vendor/autoload.php');

API credentials

To create one or several sets of API credentials from your Evoliz account, go to Applications, then to the Available Connectors section.

Then enable the Evoliz API connector. To find it more easily, you can directly select the API tag.

You can then generate a set of API credentials (public key & secret key). They will be used in every API request to authenticate your app.

image

The secret key, as its name suggests, should be stored securely in order to make sure that only your servers make calls and trigger action on your app.

Client number

To retrieve your client number, you need to login to Evoliz and then click on the question mark (upper right corner) and get the first part of the client number displayed.

image

Authentication with the SDK

The authentication to the API with the SDK is very simple. It can be done in the following way:

$config = new Evoliz\Client\Config('YOUR_COMPANYID', 'YOUR_PUBLIC_KEY', 'YOUR_SECRET_KEY');

Managing authentication to the API is one of the biggest challenges of the SDK. When you log in to the API using your public and secret keys, a JSON Web Token is provided to authenticate you for a period of 15 minutes. You then have to give this token to each API call you will make.

A systematic reconnection at each call with the SDK not being conceivable, we have decided to store the authentication token as well as its expiration date in your Cookies in order to make a control on the validity of the token and to reuse it for each call throughout its validity.

E-commerce

The current version of the SDK includes only the e-commerce scope. It contains all the API features that can be useful for the management of an e-commerce website:

  • The management of the catalog with the recovery and the creation of articles
  • The management of clients with :
    • Recovery and creation of clients
    • Recovery and creation of client contacts
  • The management of sales with :
    • Recovery, creation and invoicing of orders
    • Recovery, creation and payment of invoices

Synchronisation to Evoliz

The synchronisation of each object to Evoliz with the SDK is done in a simple way. You can find here all the examples of synchronization.

Duplication

It' s important to avoid possible duplication. To do this, you must link your item from your e-commerce store to the one synchronised in Evoliz using a unique identifier allowing you to make the link between the two of them (such as the reference for the articles). You must therefore, for each creation of an object such as articles, perform a research to find out if it exists before creating it (find or create).

Orders synchronisation

As we saw before, we need to do a search to check that the order we want to create does not already exist in Evoliz. For this, we will look at the external_document_number field of the Evoliz orders which must be unique.

$saleOrderRepository = new SaleOrderRepository($config);
$matchingSaleOrders = $saleOrderRepository->list(['search' => 'ORDER_KEY']);

If the order already exists, then it should not be recreated.

However, if the research does not result in anything, then you can create the order like this (by modifying the example with the information of your order and by looking at the available fields in the API documentation:

$newSaleOrder = $saleOrderRepository->create(new SaleOrder([
    'external_document_number' => 'evz42',
    'documentdate' => '2022-03-14',
    'clientid' => 1,
    'term' => [
        'paytermid' => 1,
    ],
    'items' => [
        new Item([
            'articleid' => 1,
        ]),
        new Item([
            'designation' => 'Banana',
            'quantity' => 42,
            'unit_price_vat_exclude' => 1
        ])
    ]
]));

Shipping costs management

We do not handle shipping costs in Evoliz. If your order contains shipping costs, you will have to add them as an Item line:

$items[] = new Item([
    'designation' => 'Frais de livraison',
    'quantity' => 1,
    'unit_price_vat_exclude' => 4
]);

Don't forget to manage the VAT if it also applies to your shipping costs.

Rebate management

In the case of a line discount, the discount must be applied to an Item line as follows:

$newItem['rebate'] = ($productRegularPrice - $productSalePrice) * $quantity;

For a global rebate, the rebate calculation may be done differently between the e-commerce store and Evoliz (taking into consideration the VAT in the calculation or not). If the calculation is the same, you can add the amount or the percentage using the global_rebate field in the order. Otherwise, you will have to add a new negative Item line with the discount amount like this:

$items[] = new Item([
    'designation' => 'Remise globale',
    'quantity' => 1,
    'unit_price_vat_exclude' => - round(($orderDiscountTotal + $orderDiscountTax), 2)
]);

Articles synchronisation

As we saw before, we need to do a search to check that the article we want to create does not already exist in Evoliz. For this, we will look at the reference field of the Evoliz articles which must be unique.

$articleRepository = new ArticleRepository($config);
$matchingArticles = $articleRepository->list(['reference' => 'ARTICLE_REFERENCE']);

If the article already exists, it must not be recreated but recovered to be integrated into the new order.

However, if the research does not result in anything, then you can create the article like this (by modifying the example with the information of your article and by looking at the available fields in the API documentation:

$newArticle = $articleRepository->create(new Article([
    'reference' => 'evz42',
    'designation' => 'Mug banana'
]));

Clients synchronisation

As we saw before, we need to do a search to check that the client we want to create does not already exist in Evoliz. For this, we will look at the name field of the Evoliz clients.

$clientRepository = new ClientRepository($config);
$matchingClients = $clientRepository->list(['search' => 'CLIENT_NAME']);

If we have matches, then a lookup for matches should be performed on the postal code (address.postcode), city (address.city) and country (address.country.iso2). If the client already exists, it must not be recreated but recovered to be integrated into the new order.

However, if the research does not result in anything, then you can create the client like this (by modifying the example with the information of your client and by looking at the available fields in the API documentation:

$newClient = $clientRepository->create(new Client([
    'name' => 'Doe',
    'type' => 'Particulier',
    'address' => [
        'postcode' => '83130',
        'town' => 'La Garde',
        'iso2' => 'FR'
    ]
]));

Contact clients synchronisation

As we saw before, we need to do a search to check that the contact client we want to create does not already exist in Evoliz. For this, we will look at the clientid field and the email field (which must be unique) of the Evoliz contact clients.

$contactClientRepository = new ContactClientRepository($config);
$matchingContactClients = $contactClientRepository->list([
    'clientid' => $clientId,
    'email' => 'CONTACT_EMAIL'
]);

If the contact client already exists, it must not be recreated but recovered to be integrated into the new order.

However, if the research does not result in anything, then you can create the contact client like this (by modifying the example with the information of your contact client and by looking at the available fields in the API documentation:

$newContactClient = $contactClientRepository->create(new ContactClient([
    'clientid' => 1,
    'lastname' => 'Doe',
    'email' => 'contact@johndoe.com',
]));

Invoicing and payment of orders

You must invoice and pay an order in Evoliz at the moment that you receive the payment. First you must invoice your order as follows:

$saleOrderRepository = new SaleOrderRepository($config);

// The invoice method takes a 2nd argument to precise whether to save the invoice or to keep it as draft
$draftInvoice = $saleOrderRepository->invoice($orderId, true);

Then, adapt the following code according to your needs and the payment methods correspondence table to pay the invoice:

$invoiceRepository = new InvoiceRepository($config);
$payment = $invoiceRepository->pay($invoiceId, 'Payment with the SDK', $paymentMethodIdentifier, $invoiceNetToPay);

Payment methods

Here is a table of correspondence between the identifier and the label of the different payment methods allocated for an invoice in Evoliz:

Payment method identifier Payment method
1 Paypal
2 Virement
3 Carte bancaire
4 Chèque
5 Espèces
6 Autres
7 Chèque Emploi Service Universel (CESU)
8 Prèlèvement
9 Lettre de change
10 Traite
11 Chèque vacances
12 Contre-remboursement
13 Avoir