Make my first API call

Select an API endpoint

Select the business service you want to test given your need. All services and endpoints details are available in the Reference API Documentation section.

You can test either Staging or Production APIs endpoints provided you are using the correct credentials.

For the sake of this test, we will select for example the followin endpoint from the eInvoicing validation service:
POST Transform Format
A test file is provided below if you want to reproduce this test (see "Test File content Example" section at the end of this document).

Test an API endpoint

Below examples on how to :

  1. test directly from our API Portal reference API documentation
  2. test using an external application (Postman)

1- Testing directly from our API documentation

1.1 Acces API Swagger in the portal

  • Go to API Reference documentation main section
  • Identify the API you want to test. In our case format transformation API
  • You will find the Swagger definition for all available version of this API
    image.png
  • on the top left, select the option "Routing" and make sure you select "Routing via secure proxy" instead of via browser
    image.png
    image.png

1.2 Select environment and Authenticate

in this section you will need your OAuth2 credentials and API Key values. See Retrieve my credentials section to have more detais how to rectrieve them.

  • Select your environement Staging or Production, and your version example v1.
    image.png
  • Before testing the endpoint, you will need to Authenticate otherwise you'll have 401 or 403 errors. Click on Authorize button
    image.png
  • Enter your OAuth2 credentials (ClientId and ClientSecret) in the OAuth2 fields of the environment you selected in the previous step. If for example you selected Staging, then fill client id and secret of Staging.
    image.png

  • Click Authorize. If your credentials are correct, you will see a "Logout" button showing. This means you have successfully authenticated and the generated token has been saved in your browser session. Do not click "close" button as you still need to enter your API Key in the section below.
    image.png

  • If you don't see the Logout button and you see the previous screen instead with Authorize button, this means your authentication has failed. You need to check your credentials value or contact the Support for help.

  • On the same Authorize screen, scroll down to "MyApiKey (apiKey)" section and enter your API Key value.
    image.png
  • Click Authorize, you will see a "Logout" button showing. This means you have successfully saved the API Key your browser session.
  • Click close. You can start testing your endpoint.
    image.png

1.3 Make the API call using Swagger

  • Select the endpoint you want to test. In this example POST Transform Format. Click "Try it out" to enable the section below and be able to select request parameters and body values.
    image.png
  • Fill the parameters and body needed for your request. Refer to each API documentation to have full details about what exact values to set. In this transform example, we can see that we have selected
    • the transformation or mapping value (transform an invoice from ERP AGI format to CII XML standard)
    • we can see that the API allows to select the Request Boby type. In this example we selected multipart/form-data to allow user to test easily from the browser by selecting a file from his file system (the other option is application/json)
    • we selected an invoice file from our local machine using the "choose file" button
    • we can see that the API allows to get the result as application/octet-stream (the other option is application/json). We keep it as application/octet-stream as this gives the user ability to download the file directly from the browser to make the testing easier.
    • once all set we can hit "Execute" button
      image.png
  • If the response is 200. We can see a "Download" button next to the result.
    image.png
  • This allows us to download the transformation result as a file
    image.png

2- Testing using an external application (Postman)

In this section we will show only how to call the API without detailing configuration options of Postman. When you test from Postman, use your favorite method to create the endpoints and manage the credentials. You can also use your favorite method to create variable or environments.

1.1 Retrieve API definition from the portal

Even when you use Postman, you still need to get the details about the API definition from our portal

1.2 Make the API call using Swagger

  • create new POST request and type full API url
    image.png
  • Enter your request parameters. In our example we enter the transformation value
    image.png
  • Enter headers values
    • Authorization header will contain the OAuth2 bearer token (you can either create it separately and copy it here, or use Postman OAuth2 capability to automatically generate it your from client id and secret)
    • API Key header will contain your API Key value
    • in this example we are passing the Content-Type as application/json as we want our input request body to be in json format
    • we are passing as well Accept header as application/json as we want our response to be in json format as well
      image.png
  • As we wanted the request body to be json, we will copy our json request in the body section
    image.png
  • our request is ready. we can hit the send button
  • If the response is 200. We can see a json result in the buttom section.
    image.png

Test File content Example (copy this content in your test file)

coming soon