Credentials

In order to leverage the functionality provided by the API, you will need credentials: a CRM ID and a CRM API key. Both of these need to be included in every message to the CRM, where they will be validated before performing any operations. If either one is incorrect, or not included, the operation will be aborted and a 401 response will be returned.

API credentials are only extended to official partners of Econtract. To become a partner and receive and these credentials, please get in touch with the organisation management.

Installation

PHP integration

Econtract has developed a PHP package that will allow you to easily integrate with the Econtract CRM application. This package is stored on Github and can be included in your project using composer.

{
        "require": {
            "econtract/crm": "3.*"
        }
    }

Or install it via the commandline:

composer require econtract/crm

Next, you will need to create a configuration file named .env and add the following values to it:

AB_CRM_URL=http://foo.com/bar           // URL to the Aanbieders CRM system
    AB_CRM_ID=your_crm_api_id               // Your unique CRM API ID
    AB_CRM_KEY=your_crm_api_key             // Your unique CRM API key

Finally, you will need to load the configuration file in before creating a new instance of the CrmService class which you can use to create the actual PHP calls. Please note that this file is loaded automatically in some PHP frameworks (e.g. Laravel 5), so it may not be necessary to do this yourself.

include('vendor/autoload.php');

    use Econtract/Crm/CrmService;


    $dotenv = new Dotenv\Dotenv(__DIR__);
    $dotenv->load();


    $crmService = new CrmService();
    $contract = $crmService->getContract( 63 );

Laravel integration

If you are using Laravel, you can leverage the CrmServiceProvider class that is included in the CRM package. Add the service provider to your config/app.php file:

'providers'             => array(

        //...
        \Econtract\Crm\CrmServiceProvider::class,

    )

Additionally, there is also a facade which makes it easy and intuitive to call the various method that the package provides. This alias also must be included your config/app.php file:

'facades'               => array(

        //...
        'Crm'                   => \Econtract\Crm\Facades\Crm::class,

    ),

Once this is done, you can easily call the methods using the facade:

$contract = Crm::getContract( 666 );

Integrations with other platforms

For all other platforms, integration with the CRM is also possible, though Econtract does not provide additional resources such as libraries or packages. In order to send or receive information from the CRM, simply submit a cURL request of the correct type (GET or POST) with the required data to the URL that matches your requirements. Be sure to always include your personal CRM API ID and API key in every request to ensure that the request will be processed correctly.

Usage

Get client

Resource HTTP format URL format Description
Client GET /api/clients/{id} Retrieve a client from the CRM

Parameters

Name Parameter Required Type Description
ID id yes integer ID of the client in the CRM

After sending the request, the CRM will send a detailed response with all information of the model.

Examples

// PHP using the econtract/crm package
    $client = Crm::getClient( 666 );

Create client

Resource HTTP format Method Description
Client POST /api/clients Create a new client in the CRM
Name Parameter Required Type Description
Gender gender yes integer Gender (*)
Market segment segment yes integer Market segment (*)
First name first_name yes string First name
Last name last_name yes string last name
Birth date birthdate no date Birth date (YYYY-MM-DD)
Birth place birthplace no string Birth place
Nationality nationality no string Nationality (be, nl,...)
ID card number idnr no string ID card number
National registry number rrnr no string National registry number
Cellphone cellphone yes string Cellphone (04xxxxxxxx)
Landline landline yes string Landline (0xxxxxxxx)
Fax fax no string Fax (0xxxxxxxx)
Email email yes string Email
Language language yes string Language (nl, fr)
Company name company no string Company name
Vat number vat no string Vat number (BExxxx.xxx.xxx)
Iban iban no string IBAN nr (BExx xxxx xxxx xxxx)
Bic bic no string BIC nr
Family size family_size no integer Family size

(*) Check the CRM parameters page for additional information on which values are accepted for this field

There is no need to check for duplication, as the CRM will do this for you. If a value does not apply for a particular customer (e.g. no vat number), the value can be ignored. After sending the request, the CRM will send a detailed response with all information of the recently created model.

Examples

// PHP using the econtract/crm package
    $client = Crm::createClient(
        array(
            'gender'                => 1,
            'segment'               => 1,
            'first_name'            => 'John',
            'last_name'             => 'Doe',
            'birthdate'             => '1956-12-25',
            'birthplace'            => 'Hasselt',
            'nationality'           => 'BE',
            'idnr'                  => 5,
            'rrnr'                  => 6,
            'cellphone'             => '012457898',
            'landline'              => '',
            'fax'                   => '',
            'email'                 => 'john.doe@server.com',
            'language'              => 'nl',
            'bban'                  => '',
            'iban'                  => '',
            'bic'                   => '',
            'family_size'           => 3,
        )
    );

Get address

Resource HTTP format Method Description
Address GET /api/addresses/{id} Retrieve an address from the CRM

Parameters

Name Parameter Required Type Description
ID id yes integer ID of the client in the CRM

After sending the request, the CRM will send a detailed response with all information of the model.

Examples

// PHP using the econtract/crm package
    $address = Crm::getAddress( 666 );

Create address

Resource HTTP format Method Description
Address POST /api/addresses Create a new address in the CRM

Parameters

Name Parameter Required Type Description
Street street yes string Street
House number nr yes integer House number
Box box yes string Box
Zip code postal_code yes string Zip code
City city yes string City
Country country yes string Country (BE, NL, ...)
Client ID client_id yes integer ID of the client to whom the address belongs

There is no need to check for duplication, as the CRM will do this for you. After sending the request, the CRM will send a detailed response with all information of the recently created model.

Examples

// PHP using the econtract/crm package
    $address = Crm::createAddress(
        array(
            'street'        => 'SomeStreet',
            'nr'            => 10,
            'box'           => '',
            'postal_code'   => 1234,
            'city'          => 'SomeCity',
            'country'       => 'BE',
            'client_id'     => 666,
        )
    );

Get contract

Resource HTTP format Method Description
Contract GET /api/contracts/{id} Retrieve an contract from the CRM

Parameters

Name Parameter Required Type Description
ID id yes integer ID of the contract in the CRM

After sending the request, the CRM will send a detailed response with all information of the model.

Examples

// PHP using the econtract/crm package
    $contract = Crm::getContract( 666 );

Create order

Resource HTTP format Method Description
Order POST /api/orders Create a new order in the CRM

To create a new order in the CRM, you will have to provide all information required for the creation of the order along with the request. This includes all data related to the order, as well as all data pertaining to the client, the address and (optionally) the invoice_address for the contract. All data must be added in a single array and sent to the econtract CRM system. In order to prevent parameter collision, these data sets must prefixed with the client_, address_, and invoice_address_ strings, respectively. The CRM will make sure that no duplicate clients, addresses and orders will be created. If a client, address or order exists, the CRM will perform an update instead of creating a new one.

Aside from these general data entries, you will also need to send additional information depending on the product type of the order you are creating. These values should be added to the same array as the information above and sent as a whole to the CRM. The CRM will take care of filtering the data and assigning it to the correct models in the database. All parameters and their acceptable values are listed in the tables below.

After sending the request, the CRM will send a detailed response with all information of the recently created model.

Order parameters

Name Parameter Required Type Description
Product type product_type yes string Product type of the order that is being created
Comparison ID comparison_id yes integer ID of the comparison that was used to generate the order
Affiliate ID affiliate_id yes integer ID of the affiliate through which the order was placed
Sales channel ID sales_channel_id yes integer ID of the sales channel through which the order was placed
IP address ip_address yes integer IP address of the client for the order is created
Cookie ID cookie_id no string Can be found in the JSON response that you receive when creating the comparison
Customer remarks remarks no string Remarks given by the customer while placing the order
Internal remarks internal_remarks no string Internal remarks given by the agent while placing the order (not visible to the customer)
Supplier ID supplier_id yes integer ID of the selected supplier
Product ID product_id yes integer ID of the selected product
Payment method payment_method yes integer Payment that is to be used for this contract (*)

(*) Check the CRM parameters page for additional information on which values are accepted for this field

Electricity contract parameters

Name Parameter Required Type Description
EAN code ean yes string EAN code for day and day-night meters
Exclusive night EAN code ean_excl no string EAN code for exclusive night meters
Meter type mru_type yes integer Meter type (*)
Meter number mru_nr yes integer Meter number of the electricity meter
Connection type connection_type yes integer Connection type of the meter (*)
Usage day usage_day no integer Usage day in kWh
Usage_night usage_night no integer Usage night in kWh
Usage exclusive night usage_excl no integer Usage exclusive night in kWh
Situation situation yes integer Situation for which the contract is being created (*)
Current supplier donor yes string Id of the current supplier
Client number at current supplier donor_client_nr yes integer Customer number at current supplier
Index of day meter index_day no integer Index of the day meter
Index of night meter index_night no integer Index of the night meter
Index of exclusive night meter index_excl no integer Index of the exclusive night meter

(*) Check the CRM parameters page for additional information on which values are accepted for this field

Gas contract parameters

Name Parameter Required Type Description
EAN code ean yes string EAN code for gas meter
Meter number mru_nr yes integer Meter number of the gas meter
Usage usage_gas no integer Usage in kWh
Situation situation yes integer Situation for which the contract is being created (*)
Current supplier donor yes string Id of the current supplier
Client number at current supplier donor_client_nr yes integer Customer number at current supplier
Index of gas meter index_gas no integer Index of the gas meter

(*) Check the CRM parameters page for additional information on which values are accepted for this field

Dualfuel pack contract parameters

Name Parameter Required Type Description
EAN code elec_ean yes string EAN code for day and day-night meters
Exclusive night EAN code elec_ean_excl no string EAN code for exclusive night meters
Meter type elec_mru_type yes integer Meter type (*)
Electricity meter number elec_mru_nr yes integer Meter number of the electricity meter
Connection type elec_connection_type yes integer Connection type of the meter (*)
Electricity usage day elec_usage_day no integer Usage day in kWh
Electricity usage night elec_usage_night no integer Usage night in kWh
Electricity usage exclusive night elec_usage_excl no integer Usage exclusive night in kWh
Electricity situation elec_situation yes integer Situation for which the contract is being created (*)
Current electricity supplier elec_donor yes string Id of the current supplier
Client number at current electricity supplier elec_donor_client_nr yes integer Customer number at current supplier
Index of day meter elec_index_day no integer Index of the day meter
Index of night meter elec_index_night no integer Index of the night meter
Index of exclusive night meter elec_index_excl no integer Index of the exclusive night meter
Gas EAN code gas_ean yes string EAN code for gas meter
Gas meter number gas_mru_nr yes integer Meter number of the gas meter
Gas Usage gas_usage no integer Usage in kWh
Gas unit gas_unit no integer Unit of the gas usage (kwh, m3)
Gas situation gas_situation yes integer Situation for which the contract is being created (*)
Current gas supplier gas_donor yes string Id of the current supplier
Client number at current gas supplier gas_donor_client_nr yes integer Customer number at current supplier
Index of gas meter gas_index no integer Index of the gas meter

(*) Check the CRM parameters page for additional information on which values are accepted for this field

Mobile contract parameters

Coming soon!

Examples: electricity contract

// PHP using the econtract/crm package
    $contract = Crm::createOrder(
        array(

            // Client data
            'client_gender'                     => 1,
            'client_segment'                    => 1,
            'client_first_name'                 => 'John',
            'client_last_name'                  => 'Doe',
            'client_birthdate'                  => '1956-12-25',
            'client_birthplace'                 => 'Hasselt',
            'client_nationality'                => 'BE',
            'client_idnr'                       => 5,
            'client_rrnr'                       => 6,
            'client_cellphone'                  => '012457898',
            'client_landline'                   => '',
            'client_fax'                        => '',
            'client_email'                      => 'john.doe@server.com',
            'client_language'                   => 'nl',
            'client_bban'                       => '',
            'client_iban'                       => '',
            'client_bic'                        => '',
            'client_family_size'                => 3,

            // Address data
            'address_street'                    => 'Street 02',
            'address_nr'                        => 10,
            'address_box'                       => '',
            'address_postal_code'               => 3500,
            'address_city'                      => 'Hasselt',
            'address_country'                   => 'BE',

            // Order data
            'comparison_id'                     => 45688954,
            'affiliate_id'                      => 50,
            'sales_channel_id'                  => 1,
            'ip_address'                        => '192.168.1.1',
            'remarks'                           => 'Please fix fast',
            'internal_remarks'                  => 'Fix fast for this customer',
            'product_id'                        => 12,
            'supplier_id'                       => 5,
            'payment_method'                    => 1,
            'producttype'                       => 'electricity',

            // Contract details data
            'ean'                               => '',
            'ean_excl'                          => '',
            'mru_type'                          => 2,
            'mru_nr'                            => '',
            'connection_type'                   => 1,
            'usage_day'                         => '',
            'usage_night'                       => '',
            'usage_excl'                        => '',
            'situation'                         => 3,
            'donor'                             => '',
            'donor_client_nr'                   => '',
            'index_day'                         => '',
            'index_night'                       => '',
            'index_excl'                        => '',
        )
    );

Examples: gas contract

// PHP using the econtract/crm package
    $contract = Crm::createOrder(
        array(

            // Client data
            'client_gender'                     => 1,
            'client_segment'                    => 1,
            'client_first_name'                 => 'John',
            'client_last_name'                  => 'Doe',
            'client_birthdate'                  => '1956-12-25',
            'client_birthplace'                 => 'Hasselt',
            'client_nationality'                => 'BE',
            'client_idnr'                       => 5,
            'client_rrnr'                       => 6,
            'client_cellphone'                  => '012457898',
            'client_landline'                   => '',
            'client_fax'                        => '',
            'client_email'                      => 'john.doe@server.com',
            'client_language'                   => 'nl',
            'client_bban'                       => '',
            'client_iban'                       => '',
            'client_bic'                        => '',
            'client_family_size'                => 3,

            // Address data
            'address_street'                    => 'SomeStreet',
            'address_nr'                        => 10,
            'address_box'                       => '',
            'address_postal_code'               => 1234,
            'address_city'                      => 'SomeCity',
            'address_country'                   => 'BE',

            // Invoice address data (optional)
            'invoice_address_street'            => 'AnotherStreet',
            'invoice_address_nr'                => 22,
            'invoice_address_box'               => '',
            'invoice_address_postal_code'       => 2345,
            'invoice_address_city'              => 'AnotherCity',
            'invoice_address_country'           => 'BE',

            // Order data
            'comparison_id'                     => 45688954,
            'affiliate_id'                      => 50,
            'sales_channel_id'                  => 1,
            'ip_address'                        => '192.168.1.1',
            'remarks'                           => 'Please fix fast',
            'internal_remarks'                  => 'Fix fast for this customer',
            'product_id'                        => 12,
            'supplier_id'                       => 5,
            'payment_method'                    => 1,
            'producttype'                       => 'gas',

            // Contract details data
            'ean'                               => '',
            'mru_nr'                            => '',
            'usage_gas'                         => '',
            'situation'                         => 3,
            'donor'                             => '',
            'donor_client_nr'                   => '',
            'index_gas'                         => '',
        )
    );

Create lead

Resource HTTP format Method Description
Lead POST /api/leads Create a new lead in the CRM

Creating leads works similar as creating contracts. There are a number of general parameters that can be supplied for every lead, but also several additional parameters that may be added depending on the type of lead that you want to create. Below you will find a list of the general parameters, as well as all parameters for all available lead types that can be submitted to the CRM.

Aside from an array of data, you will also need to specify the type of lead you want to create. This can be done by passing the type as the first parameter to the createLead method and the data array as the second parameter as shown in the example below. In some cases, a utility method exists for a specific lead type. If this is the case, the utility method should be used to ensure proper request handling. All available types and data sets are listed below.

Parameters

Name Parameter Required Type Description
Gender gender yes integer Gender (*)
Market segment segment yes integer Market segment (*)
First name first_name yes string First name
Last name last_name yes string last name
Birth date birthdate no date Birth date (YYYY-MM-DD)
Cellphone cellphone yes string Cellphone (04xxxxxxxx)
Landline landline yes string Landline (0xxxxxxxx)
Email email yes string Email
Language language yes string Language (nl, fr)
Product type ID producttype_id no integer ID of the product type which the lead in interested (does not apply to every lead)
Supplier ID supplier_id no integer ID of the supplier in which the lead in interested (does not apply to every lead)
Product ID product_id no integer ID of the product in which the lead in interested (does not apply to every lead)
Affiliate ID affiliate_id yes integer ID of the affiliate through which the lead was created
Cookie ID cookie_id no string
IP address ip_address yes integer IP address of the client for the lead is created
Lead type lead_type yes string Type of lead you are creating. Is added as first parameter to the createLead method in the PHP package. When not using the package, this parameter must be added manually

(*) Check the CRM parameters page for additional information on which values are accepted for this field

Group purchase lead

Name Parameter Required Type Description
Family size family_size yes integer Family size
Street address_street yes string Street
House number address_nr yes integer House number
Box address_box yes string Box
Zip code address_postal_code yes string Zip code
City address_city yes string City
Country address_country yes string Country (BE, NL, ...)
Electricity EAN code elec_ean yes string EAN code for day and day-night meters
Exclusive night EAN code elec_ean_excl no string EAN code for exclusive night meters
Meter type elec_mru_type yes integer Meter type (*)
Connection type elec_connection_type yes integer Connection type of the meter (*)
Electricity usage day elec_usage_day no integer Usage day in kWh
Electricity usage night elec_usage_night no integer Usage night in kWh
Electricity usage exclusive night elec_usage_excl no integer Usage exclusive night in kWh
Gas EAN code gas_ean yes string EAN code for gas meter
Gas usage gas_usage no integer Gas usage
Gas unit gas_unit no integer Unit of the gas usage (kwh, m3)
Situation situation yes integer Situation for which the lead is being created (*)
Group purchase key group_purchase_key yes string Identifier for the specific group purchase for which the lead is created
Communication method communication_method yes string Method by which the leads wants to receive his/her communication (email, mail)
Residence type ID residence_type_id yes integer Type of house in which the lead lives (*)

(*) Check the CRM parameters page for additional information on which values are accepted for this field

// PHP using the econtract/crm package
    $lead = Crm::createLead(
        'group_purchase',
        array(
            'first_name'                            => 'John',
            'last_name'                             => 'Doe',
            'email'                                 => 'john.doe@server.com',
            'phone'                                 => '0499656565',
            'phone'                                 => '011245145',
            'vat'                                   => '',
            'birthdate'                             => '1986-12-25',
            'nationality'                           => 'BE',
            'family_size'                           => 3,
            'address_street'                        => 'SomeStreet',
            'address_nr'                            => 10,
            'address_box'                           => '',
            'address_postal_code'                   => 1234,
            'address_city'                          => 'SomeCity',
            'address_country'                       => 'BE',
            'elec_supplier_id'                      => 10,
            'elec_product_id'                       => 0,
            'elec_mru_type'                         => 1,
            'elec_usage_day'                        => 3500,
            'elec_usage_night'                      => 2400,
            'elec_usage_excl'                       => 0,
            'elec_has_solar'                        => false,
            'elec_solar_capacity'                   => 0,
            'gas_supplier_id'                       => 11,
            'gas_product_id'                        => 0,
            'gas_usage'                             => 32000,
            'gas_unit'                              => 'kwh',
            'group_purchase_key'                    => 'group_purchase_wallonia',
            'communication_method'                  => 'email',
            'residence_type_id'                     => 2,
        )
    );

Kobi lead

Coming soon!

// PHP using the econtract/crm package
    $response = Crm::createLead(
        'kobi',
        array(
            'gender'                        => 1,
            'segment'                       => 1,
            'first_name'                    => 'John',
            'last_name'                     => 'Doe',
            'language'                      => 'nl',
            'email'                         => 'john.doe@someserver.com',
            'phone'                         => '012457090',
            'vat'                           => '',
            'birthdate'                     => '1956-12-25',
            'address_street'                => 'SomeStreet',
            'address_nr'                    => 10,
            'address_box'                   => '',
            'address_postal_code'           => 1234,
            'address_city'                  => 'SomeCity',
            'address_country'               => 'BE',
            ’source_id'                     => '123_4567_8901’,
            ’current_supplier'              => ‘Luminus’,
        )
    );

Ikstapover lead

Coming soon!

Click-out lead

Resource HTTP format Method Description
Lead POST /api/leads/clickOut Create a new click-out lead in the CRM

Coming soon!

// PHP using the econtract/crm package
    $lead = Crm::createClickOutLead(
        array(
            'first_name'            => 'John',
            'last_name'             => 'Doe',
            'email'                 => 'john.doe@server.com',
            'product_type_id'       => 3,
            'supplier_id'           => 43,
            'product_id'            => 53,
            'url'                   => 'http://foo.com/bar',
        )
    );

Referral lead

Resource HTTP format Method Description
Lead POST /api/referrals Create a new referral lead in the CRM

Coming soon!

LaagsteFactuur lead

Coming soon!

// PHP using the econtract/crm package
    $response = Crm::createLead(
        'laagste_factuur',
        array(
            'gender'                        => 1,
            'segment'                       => 1,
            'first_name'                    => 'John',
            'last_name'                     => 'Doe',
            'language'                      => 'nl',
            'email'                         => 'john.doe@someserver.com',
            'phone'                         => '012457090',
            'vat'                           => '',
            'birthdate'                     => '1956-12-25',
            'address_street'                => 'SomeStreet',
            'address_nr'                    => 10,
            'address_box'                   => '',
            'address_postal_code'           => 1234,
            'address_city'                  => 'SomeCity',
            'address_country'               => 'BE',
            ’producttype_id'                => 14,
            ’ip_address'                    => ‘127.0.0.1’,
            ’source_id'                     => '123_4567_8901’,
            ’current_supplier_id'           => 10,
        )
    );

CallMeBack lead

// PHP using the econtract/crm package
    $lead = Crm::createCallMeBackLead(
        array(
            'first_name'                    => 'John',
            'last_name'                     => 'Doe',
            'email'                         => 'john.doe@server.com',
            'phone'                         => '0499656565',
            'producttype_id'                => 3,
            'product_id'                    => 4,
            'supplier_id'                   => 5,
            'affiliate_id'                  => 6,
            'subject'                       => 'Foo_subject',
            'remarks'                       => 'Foo_remarks',
            'call_at'                       => '2016-04-15 12:00:00',
            'call_until'                    => '2016-04-15 18:00:00',
            'deal_closed'                   => false,
        )
    );

Smappee lead for Electricity

Name Parameter Required Type Description
Comparison ID engine_id yes integer ID of the comparison that was generated for the Smappee user
// PHP using the econtract/crm package
    $response = Crm::createLead(
        'smappee',
        array(
            'gender'                        => 1,
            'segment'                       => 1,
            'first_name'                    => 'John',
            'last_name'                     => 'Doe',
            'language'                      => 'nl',
            'email'                         => 'john.doe@someserver.com',
            'phone'                         => '012457090',
            'address_postal_code'           => 1234,
            'supplier_id'                   => 5,
            'product_id'                    => 4,
            ’engine_id'                     => 63492812,
        )
    );

Get Latest Orders

Resource HTTP format Method Description
latests POST /api/latest Fetch latest orders from CRM

Parameters

Name Parameter Required Type Description
Age age no integer Max age of the orders returned.
Zipcode address_zipcode no integer Zipcode where to limit the results to
Language client_language no nl/fr Language of the client
Product Type product_type no string Producttype filter