What is a folder in X3?
A folder is a structure that stores data related to a set of companies willing to share the same common tables (business partners, products) and to have the ability to create reports aggregating the data on groups of companies with database queries on a single schema. It is implemented as a unique database user with a set of tables storing parameters and user data.
What is a scope in X3 API?
As a developer, when you create a pairing request you need to pass a Scope. Scope represents the authorization that will be associated with your access tokens. It must include the list of APIs you want to consume. Actually these APIs are:
Note : API related to token management, folder listing are not part of the scope since it’s a requirement for developer to have access to it.
What about folders?
Folder will be added to the scope by the end-user in X3. When he reviews your pairing request, he selects the X3 folders he want to associated your access token with. There are 2 ways for you to know the folder you can access to once you have your tokens. First way is to review the scope returned by token API, second way is to call the folder API since only the authorized folders will be part of the response.
Example of valid scopes
- “api.dataIngestion api.dataDelivery”
What is a regional API endpoint in X3?
At the end of pairing process, if the regional API endpoint you are using is not associated to the customer configuration, a parameter called endpoint will be present in the callback that gives you the access code to convert into tokens. The 3rd party application has to use this endpoint for further calls instead of its known regional root API endpoint.
Why does the Data Ingestion API have 2 steps to upload a file?
Our cloud architecture is currently based on Amazon AWS and all uploaded files are transiting in S3 storages before landing into the X3 customer configuration. This service allows us to upload a large file (350MB). That is why we use the presigned upload URL from AWS S3 service. In development process, the developer just needs to follow the url from the first call to chain up these 2 steps.
The second step (using a presigned AWS S3 URL) is managed by AWS S3, then the current policy from AWS S3 is that you can upload as many time as you want the file for the entire lifetime of this URL (1h). The upload call with presigned URL returns always 200 when it is successfully executed. However, please remind that the latest version will be copied to the X3 configuration.
It is the responsibility of the developer to manage the upload process correctly (otherwise, there is no warranty on which version will be copied to X3).
Maximum file size limit for Data Ingestion API
The file ingestion API allows 3rd party application to upload file to X3. The uploaded file will be scanned for any security threat and stored on the corresponding X3 storage. Only text files are allowed and their size cannot exceed 350 MB.