1. Home
  2. Docs
  3. Documentation
  4. How-to guides
  5. Swagger

Swagger

Swagger is our interactive documentation that gives you an overview of our available endpoints, how their response model is set up and also gives you the opportunity to test requests directly in your web browser.

Keep in mind that there are two instances of Swagger. One for tripletex.no and one for api.tripletex.io. Make sure that you use the one where your credentials are created.

If you want to report an issue to us we recommend that you test the same request in Swagger to rule out any issues in your code.

Note: Due to how our DTOs are built you might notice that sub-object have mandatory fields in them. These mandatory fields are only required to create new objects. If you want to reference and existing object you can do so by using the id attribute.

Authenticating in Swagger

To authenticate in Swagger you need your consumer and employee token. These are either given to you when you register for access to api.tripletex.io or you get your consumer token in production from us and your employee token for production from the end users Tripletex account. You can read more about tokens and authentication in general here.

To create a session token you need to run a request to PUT /session/token/:create

This endpoint requires no authentication – Click “Try it out” and provide your consumer token, employee token and an expiration date. Your are free to set any date here, given that it is later than todays date. The session token expires at midnight on the date given.

Once you press Execute you will find your session token in the response body as “token”, below expirationDate.

With your session token now created we can go ahead and authenticate. You can do this by either clicking the padlock-icon on an endpoint that requires authentication, or via the Authorize button on the top of the page. Here you enter “0” (zero) as username, and your session token as password.

Note: If you are using an accountant token there is a slightly different route to authenticate towards the client account you want to reach. After authenticating with 0 + sessiontoken you need to run GET company/>withClientAccess to get a list of all clients that the token has access to, then use the companyId of the company you want to access as username with the same sessiontoken. This is also explained at the top of the page in Swagger.

Performing a request

To perform a request in Swagger all you have to do is locate the endpoint and method you would like to use after authenticating, then click on “Try it out” to unlock the attributes. After you have filled in the attributes you would like (mandatory ones being marked with an asterisk) you press “Execute” to run it. The response is then displayed below.

Possible error codes

Some requests return with an error code. Here you will find a list explaining what they mean. This is also explained at the top of the page in Swagger:

  • 200 OK
  • 201 Created – From POSTs that create something new.
  • 204 No Content – When there is no answer, ex: “/:anAction” or DELETE.
  • 400 Bad request –
    • 4000 Bad Request Exception
    • 11000 Illegal Filter Exception
    • 12000 Path Param Exception
    • 24000 Cryptography Exception
  • 401 Unauthorized – When authentication is required and has failed or has not yet been provided
    • 3000 Authentication Exception
  • 403 Forbidden – When AuthorisationManager says no.
    • 9000 Security Exception
  • 404 Not Found – For resources that does not exist.
    • 6000 Not Found Exception
  • 409 Conflict – Such as an edit conflict between multiple simultaneous updates
    • 7000 Object Exists Exception
    • 8000 Revision Exception
    • 10000 Locked Exception
    • 14000 Duplicate entry
  • 422 Bad Request – For Required fields or things like malformed payload.
    • 15000 Value Validation Exception
    • 16000 Mapping Exception
    • 17000 Sorting Exception
    • 18000 Validation Exception
    • 21000 Param Exception
    • 22000 Invalid JSON Exception
    • 23000 Result Set Too Large Exception
  • 429 Too Many Requests – Request rate limit hit
  • 500 Internal Error – Unexpected condition was encountered and no more specific message is suitable
    • 1000 Exception

If you encounter an error that you are not quite sure how to solve then please check if this is already explained in our FAQ.