# Introduction The eCOS® API allows you to programmatically interact with the eCOS® system. You can use it to perform a variety of tasks such as retrieving existing data, creating or modifying resources, and triggering automated actions. There are many methods available, but you will typically use just a few of them to perform a specific task. The API is based on the REST style and supports the JSON format. ## Endpoint (Base URL) ``` https://apiv2.ecos2.externis.com/ ``` ### Supported protocols #### HTTP ``` HTTP1.1, HTTP/2, HTTP/3 (QUIC) ``` #### Encryption ``` TLS 1.2, TLS 1.3 ``` #### Compression ``` Gzip, Deflate ``` ## OpenAPI specification The API is fully documented with the OpenAPI (Swagger) specification. [https://apiv2.ecos2.externis.com/swagger/v1/swagger.json](https://apiv2.ecos2.externis.com/swagger/v1/swagger.json) ## Swagger UI Swagger UI is provided, and it allows you to explore and interact with all the available methods and schemas. [https://apiv2.ecos2.externis.com/swagger/](https://apiv2.ecos2.externis.com/swagger/) ## Documentation for AI models (LLMs) A `llms.txt` file is available with the documentation in markdown format designed to be used with LLM models. [https://apiv2.ecos2.externis.com/docs/llms.txt](https://apiv2.ecos2.externis.com/docs/llms.txt) # Authentication Before you can use the available API methods, you must first get an authentication token. Additionally, many methods require the use of a token for a specific application context. The procedure to get this token is as follows: 1. [Logon](#logon) 2. [Logon application context](#logon-application-context) 3. Use the application context token to call any methods your task requires. 4. [Logout](#logout) (optional) Note: Except for the logon method or unless otherwise specified, you must include an authentication token in the request header `Token` of all API method calls. ## Logon To authenticate, you must provide the following credentials: ``` Username: Password: Customer reference: API-Key: ``` Tip: If you do not have the required information, please contact your administrator or Externis support. Replace all `` in the example request with your own credentials. Method: [POST /Auth/Logon](logon-to-the-ecos-api.html) Request: ```SHELL curl -X 'POST' \ 'https://apiv2.ecos2.externis.com/Auth/Logon' \ -H 'accept: application/json' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'username=&password=&customer=&apiKey=' ``` Response: ```JSON { "id": 47, "deliveryLocationHomeId": 150, "username": "john.doe", "password": null, "firstName": "John", "lastName": "Doe", "email": "john.doe@externis.com", "locale": "fr-FR", "timezone": "Romance Standard Time", "application": "ECOS", "roleId": 1, "role": "User", "customer": "TEST", "customerCode": "TEST", "organisationId": 1, "organisationLabel": "NATIONAL", "token": "", "isAdmin": true, "modifiedDate": "2022-05-27T11:23:42.74Z", "lastLogonDate": "2023-01-11T14:46:22.087Z" } ``` Note: The `"token"` field in the response, which holds the value `` contains the authentication token. ## Logon application context You typically use a token for a specific application context when calling methods, so this procedure should be done right after the initial logon using the `` you received. The example request uses the `SALBO` context, which is the most common one for calling "Sales" methods. Available contexts include: | Name |Description | --------------------- | SALBO |Sales back office | | ASSBO |Assort back office | | DOCBO |Docs back office | Replace `` in the example request with the token obtained from the [Logon](#logon) response. Method: [POST /Auth/LogonApplication](logon-to-an-application-context.html) Request: ```SHELL curl -X 'POST' \ 'https://apiv2.ecos2.externis.com/Auth/LogonApplication' \ -H 'accept: application/json' \ -H 'Token: ' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'application=SALBO' ``` Response: ```JSON { "id": 47, "deliveryLocationHomeId": 150, "username": "john.doe", "password": null, "firstName": "John", "lastName": "Doe", "email": "john.doe@externis.com", "locale": "fr-FR", "timezone": "Romance Standard Time", "application": "SALBO", "roleId": 3, "role": "Admins", "customer": "TEST", "customerCode": "TEST", "organisationId": 1, "organisationLabel": "NATIONAL", "token": "", "isAdmin": true, "modifiedDate": "2022-05-27T11:23:42.74Z", "lastLogonDate": "2024-10-17T08:34:26.947Z" } ``` ## Logout Logout is optional, but it is recommended that you call log out to invalidate the authentication token(s) after using the API. Replace `` in the example request with the token to be invalidated. Method: [POST /Auth/Logout](logout.html) Request: ```SHELL curl -X 'POST' \ 'https://apiv2.ecos2.externis.com/Auth/Logout' \ -H 'Token: ' \ -d '' ``` Response: ``` 200 Ok ``` # Important considerations ## Releases The eCOS® API is under continuous development, new methods and schemas are added frequently, and occasionally new fields may be added to existing schemas or additional parameters to existing methods. Existing parameters and fields are not removed or changed to prevent any breaking changes. Warning: You should not be strict on the total number of fields in a schema. New fields may be added on new releases. ## Modifying a resource When updating existing data, you should always send the complete schema with all the existing field values. If you omit fields, they will assume default values and possibly overwrite existing data. Methods that modify resources should be called shortly after getting the current data to avoid overwriting newer data modified by someone else. Warning: Always send the whole schema when modifying existing resources even if you only change a single field. Note: Make modifications in a reasonable amount of time after getting the current data from the system. ## Bulk operations Methods that allow you to create or modify a resource should always be called sequentially. This will ensure that your requests are processed predictably and that they are not blocked or end in error due to conflicts. A good rule of thumb is to apply this principle to all `POST` methods. Warning: Calling `POST` methods in parallel may result in blocked requests, errors or rate limiting. Always call these methods sequentially. # How to manage stores Stores (points of sales) are managed through delivery locations and related resources. A store is a specific type of delivery location. This article describes the resources that you should be aware of to manage stores. To create or modify stores, you will need to follow this procedure: 1. [Retrieve all associated resources](#retrieve-all-associated-resources) 2. [Retrieve all delivery locations](#retrieve-all-delivery-locations) 3. Determine stores to be created or modified based on your task 4. [Create new related resources (if required)](#create-new-related-resources) 5. [Create or modify stores (as needed)](#create-or-modify-stores) Note: You need to perform authentication before you can follow these steps. See [Authentication](authentication.html) for more information. All the methods mentioned here use the `SALBO` application context. ## Delivery location An example of a delivery location is shown below. See [DeliveryLocation](deliverylocation.html) for more details. Tip: Fields with the `Id` or `Uid` suffix usually represent relations to other resources, and you will need to get those resources to determine the correct value for the field. ```JSON { "id": 1265, "deliveryLocationTypeId": 2, "reference": "0000000312", "label": "CASINO 75012 PARIS PLACE DE LA NATION", "companyName": "CASINO 75012 PARIS", "firstname": null, "lastname": null, "email": null, "addressLine": "26 PLACE DE LA NATION", "addressLine2": null, "postcode": "75012", "city": "PARIS", "country": "France", "phoneNumber": "01 47 00 00 00", "phoneNumber2": null, "faxNumber": "01 47 00 00 99", "faxNumber2": null, "addressComment": null, "contactEmail": null, "modifiedDate": "2024-06-12T08:28:30.223Z", "groupId": 1, "channelId": 2, "potentialVal": 44551, "availability_Mon": "8,9", "availability_Tue": "9,10,11", "availability_Wed": "8,9", "availability_Thu": "8,9,10", "availability_Fri": "8,9,10", "availability_Sat": null, "availability_Sun": null, "open_Mon": null, "open_Tue": null, "open_Wed": null, "open_Thu": null, "open_Fri": null, "open_Sat": null, "open_Sun": null, "distributionChannel": 1, "accountId": 396, "clusteringId": 2, "nextAppointmentUid": "020bc204-7d69-4282-9c5c-e230e1e7ce8f", "nextAppointmentDate": "2024-06-13T06:30:00Z", "organisations": [ 80 ], "seasonalities": [], "addressModifiedDate": "2021-12-24T10:57:14.12Z", "posTypeId": 0, "geolocPermanentBypass": false, "identificationNumber": null, "newDeliveryLocationTypeId": 0, "deliveryDays": null } ``` ## Related resources The relevant relations between a delivery location and its related resources are shown in this table. Consult the schema of each resource to see all the available fields. | Delivery location field |Related resource field | --------------------------------------------------- | [DeliveryLocation](deliverylocation.html).organisations[] |[Organisation](organisation.html).id | | [DeliveryLocation](deliverylocation.html).accountId |[Account](account.html).id | | [DeliveryLocation](deliverylocation.html).deliveryLocationTypeId |[DeliveryLocationType](deliverylocationtype.html).id | | [DeliveryLocation](deliverylocation.html).channelId |[Channel](channel.html).id | | [DeliveryLocation](deliverylocation.html).groupId |[DeliveryLocationGroup](deliverylocationgroup.html).id | | [DeliveryLocation](deliverylocation.html).channelId |[Channel](channel.html).id | | [DeliveryLocation](deliverylocation.html).distributionChannel |[DistributionChannel](distributionchannel.html).id | ## Retrieve all associated resources Retrieve all the data required to manage delivery locations by calling the following methods. Tip: Organisations, accounts and delivery location types are required to create a delivery location of type `STORE`. [GET /Core/Organisations](retrieve-all-organisation-nodes.html) [GET /Distributor/Accounts](retrieve-all-accounts.html) [GET /Sales/DeliveryLocationTypes](retrieve-all-delivery-location-types.html) [GET /Sales/DeliveryLocationGroups](retrieve-all-delivery-location-groups.html) [GET /Distributor/Channels](retrieve-all-channels.html) [GET /Sales/DistributionChannels](retrieve-all-distribution-channels.html) ## Retrieve all delivery locations Tip: To retrieve only delivery locations of the type `STORE` use the `deliveryLocationTypeId` filter. [GET /Sales/DeliveryLocations](retrieve-all-delivery-locations.html) ## Create new related resources Depending on your requirements, you may need to automatically create a related resource that does not already exist in the system. For example, you might want to automatically create a [POS Type](postype.html). [POST /Sales/POSTypes](create-or-modify-a-pos-type.html) ## Create or modify stores [POST /Sales/DeliveryLocations](create-or-modify-a-delivery-location.html) ## EDI fields correspondence The following table illustrates the correspondence between the EDI specification and the corresponding fields in the API. Note: When a resource other than the delivery location is shown, this means that you should get the resource using the specified field and set the corresponding identifier in the delivery location. See [Related resources](#related-resources) for details on the relation fields. | Id |Description |Resource field | ----------------------------------- | 1 |Référence magasin |[DeliveryLocation](deliverylocation.html).reference | | 2 |Libellé magasin |[DeliveryLocation](deliverylocation.html).label | | 3 |Code enseigne |[Account](account.html).codeAccount | | 4 |Organisation |[Organisation](organisation.html).reference | | 5 |Raison Sociale |[DeliveryLocation](deliverylocation.html).companyName | | 6 |Telephone1 |[DeliveryLocation](deliverylocation.html).phoneNumber | | 7 |Telephone2 |[DeliveryLocation](deliverylocation.html).phoneNumber2 | | 8 |Fax1 |[DeliveryLocation](deliverylocation.html).faxNumber | | 9 |Fax2 |[DeliveryLocation](deliverylocation.html).faxNumber2 | | 10 |Adresse1 |[DeliveryLocation](deliverylocation.html).addressLine | | 11 |Adresse2 |[DeliveryLocation](deliverylocation.html).addressLine2 | | 12 |CP |[DeliveryLocation](deliverylocation.html).postcode | | 13 |Ville |[DeliveryLocation](deliverylocation.html).city | | 14 |Pays |[DeliveryLocation](deliverylocation.html).country | | 15 |Potentiel (valeur) |[DeliveryLocation](deliverylocation.html).potentialVal | | 16 |Circuit |[Channel](channel.html).name | | 17 |Groupe |[DeliveryLocationGroup](deliverylocationgroup.html).label | | 18 |Circuit de distribution |[DistributionChannel](distributionchannel.html).label | # Methods See [Swagger UI](introduction.html#swagger-ui) for all available methods. # Logon to the eCOS API OpenAPI endpoint: POST /Auth/Logon This method allows you to log on to the eCOS API and get an authentication token. After calling this method, you typically call LogonApplication to get a token for the desired application context. The API key is supplied by Externis. ## Request parameters ## Responses # Logon to an application context OpenAPI endpoint: POST /Auth/LogonApplication This method allows you to log on to an application context and get an authentication token for that context. ## Request parameters ## Responses # Logout OpenAPI endpoint: POST /Auth/Logout This method allows you to log out from the eCOS API. After calling this method, the authentication token will be invalidated across the system. ## Responses # Retrieve all organisation nodes OpenAPI endpoint: GET /Core/Organisations This method allows you to retrieve all organisation nodes. Use the applicationDomainId parameter for domain-specific organisations. By default, the global organisation is retrieved. ## Request parameters ## Responses # Retrieve all accounts OpenAPI endpoint: GET /Distributor/Accounts This method allows you to retrieve all accounts. ## Responses # Retrieve an account OpenAPI endpoint: GET /Distributor/Accounts/{id} This method allows you to retrieve an account. ## Request parameters ## Responses # Create or modify an account OpenAPI endpoint: POST /Distributor/Accounts This method allows you to create or modify an account. ## Request parameters ## Responses # Delete an account OpenAPI endpoint: DELETE /Distributor/Accounts/{id} This method allows you to delete an account. ## Request parameters ## Responses # Retrieve all channels OpenAPI endpoint: GET /Distributor/Channels This method allows you to retrieve all channels. ## Responses # Create or modify a channel OpenAPI endpoint: POST /Distributor/Channels This method allows you to create or modify a channel. ## Request parameters ## Responses # Retrieve all segments OpenAPI endpoint: GET /Assort/Segment This method allows you to retrieve all segments. Use the accountId parameter to filter by account. ## Request parameters ## Responses # Create or modify a segment OpenAPI endpoint: POST /Assort/Segment This method allows you to create or modify a segment. ## Request parameters ## Responses # Delete a segment OpenAPI endpoint: DELETE /Assort/Segment/{id} This method allows you to delete a segment. If the reassignChildren parameter is set to true (recommended), the segment's children will be reassigned to the deleted segment's parent. ## Request parameters ## Responses # Retrieve all delivery location groups OpenAPI endpoint: GET /Sales/DeliveryLocationGroups This method allows you to retrieve all delivery location groups. ## Responses # Retrieve a delivery location group OpenAPI endpoint: GET /Sales/DeliveryLocationGroups/{id} This method allows you to retrieve a delivery location group. ## Request parameters ## Responses # Create or modify a delivery location group OpenAPI endpoint: POST /Sales/DeliveryLocationGroups This method allows you to create or modify a delivery location group ## Request parameters ## Responses # Retrieve all delivery locations OpenAPI endpoint: GET /Sales/DeliveryLocations This method allows you to retrieve all delivery locations for the user. Use the optional parameters to filter the delivery locations. ## Request parameters ## Responses # Retrieve a delivery location OpenAPI endpoint: GET /Sales/DeliveryLocations/{id} This method allows you to retrieve a delivery location. ## Request parameters ## Responses # Create or modify a delivery location OpenAPI endpoint: POST /Sales/DeliveryLocations This method allows you to create or modify a delivery location. ## Request parameters ## Responses # Delete a delivery location OpenAPI endpoint: DELETE /Sales/DeliveryLocations/{id} This method allows you to delete a delivery location. ## Request parameters ## Responses # Retrieve all delivery location types OpenAPI endpoint: GET /Sales/DeliveryLocationTypes This method allows you to retrieve all delivery location types. ## Responses # Retrieve all distribution channels OpenAPI endpoint: GET /Sales/DistributionChannels This method allows you to retrieve all distribution channels. ## Responses # Retrieve a distribution channel OpenAPI endpoint: GET /Sales/DistributionChannels/{id} This method allows you to retrieve a distribution channel. ## Request parameters ## Responses # Create or modify a distribution channel OpenAPI endpoint: POST /Sales/DistributionChannels This method allows you to create or modify a distribution channel. ## Request parameters ## Responses # Delete a distribution channel OpenAPI endpoint: DELETE /Sales/DistributionChannels/{id} This method allows you to delete a distribution channel. ## Request parameters ## Responses # Retrieve all POS types OpenAPI endpoint: GET /Sales/POSTypes This method allows you to retrieve all POS types. ## Responses # Retrieve a POS type OpenAPI endpoint: GET /Sales/POSTypes/{id} This method allows you to retrieve a POS type by identifier. ## Request parameters ## Responses # Create or modify a POS type OpenAPI endpoint: POST /Sales/POSTypes This method allows you to create or modify a POS type. ## Request parameters ## Responses # Retrieve all delivery location segments OpenAPI endpoint: GET /Sales/DeliveryLocationSegments This method allows you to retrieve all delivery location segments. Use the optional deliveryLocationId parameter to filter by delivery location. ## Request parameters ## Responses # Create or modify delivery location segments OpenAPI endpoint: POST /Sales/DeliveryLocationSegments This method allows you to create or modify delivery location segments. ## Request parameters ## Responses # Delete a delivery location segment OpenAPI endpoint: DELETE /Sales/DeliveryLocationSegments This method allows you to delete a delivery location segment entry. ## Request parameters ## Responses # Retrieve all product tree items OpenAPI endpoint: GET /Core/ProductTree This method allows you to retrieve all product tree items. ## Responses # Retrieve a product tree item OpenAPI endpoint: GET /Core/ProductTree/{id} This method allows you to retrieve a product tree item. ## Request parameters ## Responses # Create or modify a product tree item OpenAPI endpoint: POST /Core/ProductTree This method allows you to create or modify a product tree item. ## Request parameters ## Responses # Delete a product tree item OpenAPI endpoint: DELETE /Core/ProductTree/{id} This method allows you to delete a product tree item. ## Request parameters ## Responses # Schemas See [Swagger UI](introduction.html#swagger-ui) for all available schemas. # User ## User # Organisation ## Organisation # Account ## Account # Channel ## Channel # Segment ## Segment # DeliveryLocationGroup ## DeliveryLocationGroup # DeliveryLocation ## DeliveryLocation # DeliveryLocationType ## DeliveryLocationType # DeliveryLocationSegment ## DeliveryLocationSegment # DistributionChannel ## DistributionChannel # POSType ## POSType # ProductTree ## ProductTree