BMEcat ETIM Validator 1.3

Verify if your BMEcat ETIM file is well formed and valid against the xsd schema and BMEcat ETIM International Guidelines.

API introduction

In addition to the validations run by users in the graphical interface (GUI), it is possible to run validations via the application programming interface (API). An API user allows BMEcat file validations to be run automatically. The API user is created on mail demand and is assigned to an existing GUI account having a validation packet purchased. Both: the API user and the GUI user share the same validation space (package of available validations, validation period, previous validation results), but unlike a GUI user, an API user cannot run free validations when a purchased validation package runs out.

When requesting an API user, you should deliver the IP address that will be allowed to use API (all requests coming from other IPs are rejected). There's a rule: "1 API user = 1 external system = 1 IP address". Activation of an API user is paid (one-time payment: 99 EUR). It is possible to assign more API user to the same GUI account: every additional API user costs 49 EUR.

The application uses the 24-hour Central European Time (CET). All time indications (such as validation-date) are given according to CET.

Please contact us if you are interested in using API.

API URL format

https://etim-validator.com/api/resource?parameters

  • api - the beginning of the address pointing to the API resource
  • resource - the resource the request refers to
  • parameters (optional) - parameters of the request

API authentication

Each request requires authentication, which is performed using the HTTP basic authentication method. The header contains the authentication data in the form "Basic username:password" where the phrase "username:password" is Base64 encoded. Username and password are set individually for each external system.

BMEcat validation

Start the BMEcat validation with automatic detection of guidelines

https://etim-validator.com/api/validate

Method: POST  •  BMEcat ETIM Validator automatically detects the guidelines of the received file and starts the validation. In response, we receive a progress key to track the validation process. Note: The BMEcat ETIM Validator expects exactly one zip compressed xml file.

Examples of requests (curl):

curl -X POST "https://etim-validator.com/api/validate" -u username:password -H "Content-Type: application/zip" --data-binary "@bmecat_etim.zip"

Example of response (JSON):

{ "validation-id":514, "progress-key":"e83d750aab4ac5af62339d2c5943e57b19e61b51044ad4afc15a509f073ccd4f" }

Start the BMEcat validation with specified guidelines

https://etim-validator.com/api/validate?gv={guidelines-version}&gc={guidelines-country-specific}

Method: POST  •  BMEcat ETIM Validator starts the validation of the file according to the specified guidelines. In response, we receive a progress key to track the validation process. Note: The BMEcat ETIM Validator expects exactly one zip compressed xml file.

The following {guidelines-version} and {guidelines-country-specific} variants are supported:

  • 5_0 (general, at, be, ch, de, dk, ee, es, fi, fr, hu, it, lt, na, nl, no, no_hvac, pl, pt, ru, se, si, uk)
  • 4_0 (general, at, be, ch, de, dk, es, fi, fr, it, lt, na, nl, no, pl, ru, se, uk)
  • 3_1 (general, at, be, ch, de, dk, es, fi, fr, nl, no, pl, se)
  • 3_0 (general)
  • 2_2 (general)

Examples of requests (curl):

curl -X POST "https://etim-validator.com/api/validate?gv=4_0&gc=general" -u username:password -H "Content-Type: application/zip" -data-binary "@bmecat_etim.zip"

Example of response (JSON):

{ "validation-id":489, "progress-key":"a338ec96031b4c3b062ac470fee146a016e16ad0389c5996898f7b9e6cd93c2d" }

Track the BMEcat validation process

https://etim-validator.com/api/validate/key/{progress-key}

Method: GET  •  BMEcat ETIM Validator responds with a status and progress (0-100) of the validation or a final report.

Examples of requests (curl):

  • curl -X GET "https://etim-validator.com/api/validate/key/e83d750aab4ac5af62339d2c5943e57b19e61b51044ad4afc15a509f073ccd4f" -u username:password
  • curl -X GET "https://etim-validator.com/api/validate/key/a338ec96031b4c3b062ac470fee146a016e16ad0389c5996898f7b9e6cd93c2d" -u username:password

Examples of responses (JSON):

  • { "validation-id":514, "validation-status":"Step 2/5: XML syntax validation", "progress":4 }
  • { "validation-id":489, "validation-status":"Step 4/5: XML against XSD validation", "progress":47 }
  • { "validation-id":514, "validation-status":"Validation complete", "validation-date":"2018-06-24 12:14:27", "valid":false, "validation-info":"XML IS NOT VALID", "filename":"bmecat_etim.xml", "file-size":16681, "guidelines-detection":true, "guidelines-version":"3.0", "guidelines-country-specific":"general", "validation-errors":[ "Error 1871: Element '{http:\/\/www.etim-international.com\/bmecat\/30} UDX.EDXF.DISCOUNT_GROUP_MANUFACTURER': This element is not expected. Expected is one of ({http:\/\/www.etim-international.com\/bmecat\/30} UDX.EDXF.MANUFACTURER_ACRONYM, {http:\/\/www.etim-international.com\/bmecat\/30} UDX.EDXF.DESCRIPTION_VERY_SHORT, {http:\/\/www.etim-international.com\/bmecat\/30} UDX.EDXF.TENDER_TEXT, {http:\/\/www.etim-international.com\/bmecat\/30} UDX.EDXF.VALID_FROM, {http:\/\/www.etim-international.com\/bmecat\/30} UDX.EDXF.EXPIRATION_DATE, {http:\/\/www.etim-international.com\/bmecat\/30} UDX.EDXF.DISCOUNT_GROUP, {http:\/\/www.etim-international.com\/bmecat\/30} UDX.EDXF.BONUS_GROUP_SUPPLIER, {http:\/\/www.etim-international.com\/bmecat\/30} UDX.EDXF.PKWIU, {http:\/\/www.etim-international.com\/bmecat\/30} UDX.EDXF.DECLARATION, {http:\/\/www.etim-international.com\/bmecat\/30} UDX.EDXF.ADDITIONAL_FACTORS). Occurrences: 2. First in line: 237." ] }
  • { "validation-id":489, "validation-status":"Validation complete", "validation-date":"2018-05-02 12:45:16", "valid":true, "validation-info":"XML IS WELL-FORMED AND VALID", "filename":"bmecat_etim.xml", "file-size":3321, "guidelines-detection":false, "guidelines-version":"4.0", "guidelines-country-specific":"PL" }

Previous validations

Get up to 200 previous validations (with status "Validation complete")

https://etim-validator.com/api/previous-validations

Method: GET  •  BMEcat ETIM Validator responds with a list containing basic data for up to 200 previous validations (with status "Validation complete").

Example of request (curl):

  • curl -X GET "https://etim-validator.com/api/previous-validations" -u username:password

Example of response (JSON):

[ { "validation-id":489, "validation-date":"2018-05-02 12:45:16", "valid":true, "validation-info":"XML IS WELL-FORMED AND VALID", "filename":"bmecat_etim.xml" }, { "validation-id":501, "validation-date":"2018-05-23 14:44:57", "valid":false, "validation-info":"XML IS NOT VALID", "filename":"bmecat_etim2.xml" }, ... ]

Get full data of the specified previous validation (with status "Validation complete")

https://etim-validator.com/api/previous-validations/id/{validation-id}

Method: GET  •  BMEcat ETIM Validator responds with a full data of the specified previous validation (with status "Validation complete").

Example of request (curl):

  • curl -X GET "https://etim-validator.com/api/previous-validations/id/501" -u username:password

Example of response (JSON):

{ "validation-id":501, "validation-date":"2018-05-23 14:44:57", "valid":false, "validation-info":"XML IS NOT VALID", "filename":"bmecat_etim2.xml", "file-size":5874, "guidelines-detection":false, "guidelines-version":"3.1", "guidelines-country-specific":"PL", "validation-errors":[ ... ] }

Available validations

https://etim-validator.com/api/available-validations

Method: GET  •  BMEcat ETIM Validator responds with information about available validations for the user account.

Example of request (curl):

  • curl -X GET "https://etim-validator.com/api/available-validations" -u username:password

Example of response (JSON):

{ "available-validations":47, "till":"2019-04-01" }

Error handling

If an error occurs, the "status" field in the response is set to false and a description of the error is available in the "message" field.

Example (JSON):

{ "status":false, "message":"Please upload a zip file" }