Overview

Authentication

There are two ways to authenticate with the APIstax endpoints.

Authorization Header

The API key is provided as the Authorization header:

curl -X GET https://api.apistax.io/v1/vat-verification?vatId=ATU16370905 \
  -H 'Authorization: Bearer API_KEY_HERE'

The API key must be prefixed with Bearer.

Query Parameter

The API key is passed as query parameter:

curl -X GET https://api.apistax.io/v1/vat-verification?vatId=ATU16370905&apikey=API_KEY_HERE

Handling errors

The first digit of the HTTP status code indicates the success of a request. The following codes are relevant to the APIstax endpoints:

  • A status code in the 2xx range indicates a success.
  • A status code in the 4xx range is an error code returned where the client seems to be causing the error. This is your responsibility and can only be fixed by changing the request. For troubleshooting, we recommend consulting the documentation of the respective endpoint.
  • A status code in the 5xx range is an error caused by the APIstax endpoints. In rare cases, such errors can be produced by the endpoints. If a reproducible error occurs, please contact our support.

For status codes in the range 4xx and 5xx the endpoints provide detailed error messages in the form of a JSON object:

{
  "messages": [
    "message.forbidden"
  ]
}

In some cases, especially regarding validation, more than one error message can be returned.

{
  "messages": [
    "message.ibanMustBeValid",
    "message.recipientMustNotBeLongerThan70Characters"
  ]
}

Possible errors

These common errors can affect any endpoint. Specific errors can be found in the documentation of the respective endpoint.

Identifier Description
message.forbidden Access is not allowed. The API key may be missing from the request or the API key may have been revoked. Read more about this in the Authentication section.
message.apiUnavailable The endpoint is temporarily unavailable, either due to planned maintenance or outage. Please retry the request at a later time.
message.quotaExceeded Your remaining quota is not sufficient to perform the request.
message.resourceNotFound The requested endpoint does not exist.
message.unknownError An unexpected error occurred on the server side. Please retry the request at a later time.
message.wrongAcceptHeader Wrong Accept HTTP header was sent. The EPC QR Code API for example needs a Accept=image/png header.

Available client libraries

To write application using the APIstax endpoints, you don't need to implement the API calls and models yourself. You can use a available client library for the programming language you are using.

Language / Framework Library location
Java https://github.com/apistax/client-java
PHP https://github.com/apistax/client-php
Quarkus https://github.com/quarkiverse/quarkus-apistax

Generate client from OpenAPI document

APIstax provides an OpenAPI document, formerly known as a Swagger document. Based on this file clients for various programming languages can be generated.

To generate an OpenAPI client the openapi-generator-cli must be installed. More information about this can be found at https://openapi-generator.tech/docs/installation/.

With a simple command, a client can then be generated in the desired programming language.

openapi-generator-cli generate -i https://api.apistax.io/q/openapi.json \
  -g java \
  --additional-properties=dateLibrary=java8,apiPackage=io.apistax.client \
  -o /tmp/output/

A complete list of supported programming languages and frameworks can be found at https://openapi-generator.tech/docs/generators/.

Documentation
Overview of general topics related to each API, authentication, error handling and the OpenAPI documentation.