Qvalia Developer Tools
Access APIs and technical requirements and get connected in no time!
Our APIs and onboarding team ensures a swift integration into your systems and processes. Qvalia integrates with major ERPs and accounting software.
All Qvalia API’s are REST based and we use both JSON and XML request and response payloads. All message formats are based upon UBL and our JSON format is a representation of the XML called UBL JSON by OASIS Open group. We strive to use the REST standards for response codes and “verbs” (e.g. GET and POST).
The Qvalia API has two separate endpoints for our Production and a Test (Quality Assurance) environment.
You must obtain a Qvalia account prior to using (or testing) the API!
Authentication
We use API keys for the Authentication of requests. You can get your API key from our Support team and you’ll get a separate key and URL for Production and Test environments. All requests are using HTTPS with a minimum of TLS 1.2
Parameters Some of our API's has the possibility to provide parameters for e.g. filtering. These parameters are sent as a query string and the options are listed per endpoint under the technical API documentation.
Error handling
We offer various error codes based upon the type of error, along with a descriptive error message (in JSON or XML). Like any other API codes in the range of 2xx is a successful request while a status of 4xx indicates an error that occurred because of the data sent or a parameter missing/in error. In the 5xx range indicate an error with our server/service and you should contact the Qvalia Support if you ever would end up getting any 5xx code as response.
Support
You can always contact Qvalia Support through your Qvalia Sales representative or by using our Support e-mail (see your Qvalia Account for details).
Coding
We use Node.js inhouse, and JSON is our format of choice, however, as many ERP and Financial systems are using XML we have opted to add support for both formats in our API. You can freely swap between XML and JSON, just by using different headers:
Omitting accept
or content-type
headers, we'll default to JSON!
XML | JSON (Default) |
GET requests: accept: application/xml POST requests: content-type: application/xml | GET requests: accept: application/json POST requests: content-type: application/json |
Node.js sample code for calling the API for sending a JSON request could look like:
async function httpsPost(registrationNumber, data) { return new Promise(async (resolve, reject) => { const options = { hostname: 'api.qvalia.com', path: `/transaction/${registrationNumber}/invoices/outgoing`, port: 443, method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: '412ee738......d3e469a7' } }; const body = []; const req = https.request(options, res => { res.on('data', d=> { body.push(d); }); res.on('end', () => { resolve(body); }); }); req.on('error', e => { reject(e); }); req.write(JSON.stringify(data)); req.end(); });}
Invoice APIs
APIs related to invoice handling
Endpoints
GET
POST
GET
GET
POST
Credit Note APIs
APIs related to credit note handing
Endpoints
GET
POST
GET
GET
POST
Order APIs
APIs related to order handing
Endpoints
GET
POST
GET
GET
POST
Order Response APIs
APIs related to order response handing
Endpoints
GET
POST
GET
GET
POST
Get incoming order responses
The response, in JSON, will always include the three latest messages, per default. Using XML you always only get one (as there's no "array" function for XML).
Use limit
parameter to change the number of returned messages and combine it with offset
to traverse down the list, e.g: https://api-qa.qvalia.com/transaction/{accountRegNo}/orderResponses/incoming?limit=10&offset=10
To get new messages only, use the "Get incoming read orderresponses"
endpoint instead.
Header Parameters
Either "application/json" (default) or "application/xml"
Query Parameters
YYYY-MM-DD, e.g. 2024-01-01
YYYY-MM-DD, e.g. 2024-01-01
YYYY-MM-DD, e.g. 2024-01-01
YYYY-MM-DD, e.g. 2024-01-01
Path Parameters
Responses
Response Attributes
Show child attributes
Response Attributes
Response Attributes
Response Attributes
Response Attributes
Response Attributes
Show child attributes
Response
{
"status": "success",
"data": [
""
]
}
Post incoming order response
Header Parameters
Either "application/json" (default) or "application/xml"
Path Parameters
Body Parameters
Responses
Response Attributes
Show child attributes
Response Attributes
Response Attributes
Response Attributes
Response Attributes
Response Attributes
Show child attributes
Response Attributes
Show child attributes
Response Attributes
Show child attributes
Response
{
"status": "success",
"data": {
"message": "order response 12335675 sent",
"order_response_id": "12335675"
}
}
Get incoming read order responses
Header Parameters
Either "application/json" (default) or "application/xml"
Query Parameters
Path Parameters
Responses
Response Attributes
Show child attributes
Response Attributes
Response Attributes
Response Attributes
Response Attributes
Response Attributes
Show child attributes
Response
{
"status": "success",
"data": [
""
]
}
Get outgoing order responses
The response, in JSON, will always include the three latest messages, per default. Using XML you always only get one (as there's no "array" function for XML).
Use limit
parameter to change the number of returned messages and combine it with offset
to traverse down the list, e.g: https://api-qa.qvalia.com/transaction/{accountRegNo}/orderResponses/incoming?limit=10&offset=10
To get new messages only, use the "Get outgoing read orderresponses"
endpoint instead.
Header Parameters
Either "application/json" (default) or "application/xml"
Path Parameters
Responses
Response Attributes
Show child attributes
Response Attributes
Response Attributes
Response Attributes
Response Attributes
Response Attributes
Show child attributes
Response
{
"status": "success",
"data": [
""
]
}
Post outgoing order response
Header Parameters
Either "application/json" (default) or "application/xml"
Path Parameters
Body Parameters
Responses
Response Attributes
Response Attributes
Response Attributes
Response Attributes
Response Attributes
Show child attributes
Response Attributes
Show child attributes
Response Attributes
Show child attributes
Response
{
"statusCode": 400,
"error": "E_INVALID_PARAMETER",
"message": "Invalid parameters from client"
}
Order Change APIs
APIs related to order change handing
Order Change is part of Advanced Ordering 3.0: https://docs.peppol.eu/poacc/upgrade-3/profiles/65-advanced-ordering/
Message Syntax: https://docs.peppol.eu/poacc/upgrade-3/syntax/OrderChange/tree/
Endpoints
GET
POST
GET
GET
POST
Order Cancellation APIs
APIs related to order cancellation handing
Order Change is part of Advanced Ordering 3.0: https://docs.peppol.eu/poacc/upgrade-3/profiles/65-advanced-ordering/
Message Syntax: https://docs.peppol.eu/poacc/upgrade-3/syntax/adv-order-cancellation-3.0/tree/
Endpoints
GET
POST
GET
GET
POST
Catalogue APIs
APIs related to catalogue handing
Endpoints
GET
POST
GET
GET
POST
Despatch Advice
APIs related to catalogue handing
Endpoints
GET
POST
GET
GET
POST
GET
Account Functions
A collection of endpoints where Qvalia account information is gathered, such as Invoice status, and automation tasks, e.g. creating an outgoing Invoice from an incoming Order.
Endpoints
POST
POST
Enrichment API
This documentation covers only Enrichment endpoint. Please use this alongside Qvalia API documentation at https://api.qvalia.com. API for uploading and enriching invoices (PDF, XML - later). PDFs are converted to digital format and presented as a Peppol XML document. Supports single and batch file processing with asynchronous polling.
Base URL
Production server.:
https://api.qvalia.com
Sandbox server for testing.:
https://api-test.qvalia.com
Sample Data
As the request and response sample data are quite big, and scrolling through each sample on every endpoint would get quite tedious, we've opted to add sample data for the various messages here instead of in the actual Endpoint data.
Regardless if you are POST'in or GET'ing data the message structure of the messages will be the same.
As stated in the API
section of the documentation, and under JSON/XML or JSON to XML
all our transaction messages are bidirectional and can be transformed to/from JSON/XML.f
JSON | XML |
json
| xml
|
SFTP-Integration
The Qvalia SFTP integration handles all Peppol XML Document types by default but we also support "custom" formats.
The SFTP setup is done by our helpdesk, and you will require a Qvalia account prior to being able to test the SFTP integration.
Qvalia hosts an SFTP Server, and both sending and receiving is done through an SFTP client from your environment.
Operator
For Swedish operators Qvalia can offer support for the legacy formats Svefaktura 1.0 (Basic Invoice) as well as Svefaktura 2 (Peppol BIS2/4A).
Qvalia is primarily using the protocol SFTI Transportprofil Bas 2.0
over HTTP POST
for the Swedish legacy formats. SFTP transportation can also be accepted, and configured, for any Operator who wants to send legacy formats.
We strongly encourage the usage of Peppol instead of legacy formats, but we do understand that some older systems still needs to fall back on older versions of specifications, and we try our best to meet the needs of our customers.
Please reach out to peppol@qvalia.com if you are an Operator who wants to use any of the legacy formats!
SFTI Transportprofil Bas 2.0 is an old and not supported standard, but as some companies and Operators in Sweden still cling to it Qvalia has the option of POST'ing Transportprofil Bas 2.0 over HTTP.
As we would like to follow the recommendation of the Swedish Government and the IT authorities of Sweden we have deprecated the usage of Svefaktura, and try to move all our customers over to Peppol.
After the 1st of March 2021, no new established Svefaktura connections should be added according to DIGG's recommendations and mandate MDFFS 2021:1
. See article from SFTI/DIGG here (in Swedish) for more information: https://sfti.se/sfti/standarder/rekommenderadestandarder/avfordameddelanden.52834.html
|
|
|
|
xml
|
Partner
The Partner API contains endpoints for usage of accounts and setup of accounts
Under the Partner API section you'll find information about the endpoints used by Partners to Qvalia and how to handle the various functions offered.
The Partner API is JSON only, so only content-type: application/json
is used!