Using the Routty API

Introduction: What is the Routty API used for

The Public Routty API provides a flexible way to integrate any ERP or accounting system with Routty. This connection can be set up in a middleware layer or through custom integrations. With the Routty API, you can:

Receive/Send Documents: Transfer documents between systems and Routty.
Synchronize your Masterdata: Ensure your master data is consistent with Routty for efficient processing.

Quick Start: Swagger UI

The Routty API swagger documentation is available at https://connector-api.routty.io/swagger/index.html .
The swagger documentation can easily be imported in your codebase or toolkit (e.g. postman) to access our API.

The base url for all api calls is:

CODE

https://connector-api.routty.io

Authentication

Authentication and authorization for accessing the Routty API are managed using API keys. These keys should be included in the Authorization header with the prefix ApiKey.

Example request using curl:

CODE

curl -X 'POST' \
  'https://connector-api.routty.io/connector-api/input-api/input-documents' \
  -H 'accept: text/plain' \
  -H 'x-correlation-id: 123456' \
  -H 'Authorization: ApiKey [INSERT_API_KEY_HERE]' \
  -H 'Content-Type: application/json' \
  -d '{
  "receivedOn": "2024-11-25T09:12:50.796Z"
}'

How to get an API Key

API keys can be generated by implementation partners for each tenant via the creation of connector configurations. Please contact your implementation partner to generate or manage your API keys.

Different API Keys types

Each API key in Routty is created with a specific set of parameters that determine its capabilities. Refer to the comparison table below for details:

Parameter	Possible values	Description
Environment	Production, Test	Defines the environment to which the API Key connects (Production or Test).
Direction	Input, Output	Input: Upload Documents to Routty Output: Download Documents from Routty
Flow	Inbound, Outbound	Inbound: For receiving processes (e.g. Purchase Invoice) Outbound: For sending processes (e.g. Sales Invoice)
Feedback expected	True, False	Defines whether the receiving system will send feedback on the status of the document. NOTE: Only applicable to OUTPUT API Keys

Production vs Test

For both the production as the test environment the same base url is used (https://connector-api.routty.io/).

Based on your API Key the production or test system is used. Which environment should be used is configured when creating a new API Key

Best practices

Secure API Keys: API keys should be stored securely. If exposed, unauthorized users could access your data or misuse the system.

If an API key is compromised or needs to be regenerated, you can request a reset of your keys at any time through your implementation partner.

Key Rotation: Routty does not enforce a mandatory key rotation policy. However, it is recommended that you rotate your API keys at least once every 6 months to ensure optimal security.
Error Handling: Ensure your integration handles errors gracefully. Build in retry mechanisms and ensure the processing of documents is idempotent (i.e., repeated actions will not result in duplicate data or unintended behavior).
API Downtime: Although Routty APIs are designed to be available at all times, ensure your system can handle potential short periods of unavailability.

Key regeneration

How to regenerate and create a new API key

API keys can be regenerated by implementation partners for each tenant via the connector configurations. Please contact your implementation partner to generate or manage your API keys.

Why or when should an API key be regenerated

For security reasons it is best to rotate your API keys at least once every 6 months. If a key should get compromised, it will no longer be valid after regeneration of a new key, thus blocking further unauthorized access to the API. During the generation process of a new key, the key is only shown once and then it is no longer possible to retrieve it. If during this process the key is lost, you can safely regenerate a new key and start using that one.

What happens with the old key

Old keys are disabled and removed from the system from the moment a new key is generated, blocking access to the API for all parties using the old key.

API Key functionality comparison

	API Input Outbound	API Input Inbound	API Output Outbound	API Output Inbound
Upload masterdata	✅	✅	✅	✅
Upload document	✅	✅	❌	❌
Download document	❌	❌	✅	✅
Retrieve document status	✅	✅	❌	❌
Connect to ERP	❌	✅	✅	❌
Connect to Channels (i.e. Peppol)	✅, can be used to build a mock channel	❌	❌	✅, can be used to build a mock channel
Can send feedback on document	❌	❌	✅, only if Expect feedback	✅, only if Expect feedback

Domains & IP Addresses

The following domains are used by the Routty platform for API communication, file exchange, and system integrations.
All domains currently resolve to the same fixed public IP address: 20.76.113.251 (HTTPS, port 443).

Domain	Purpose / Service	Status
`connector-api.routty.io`	Base URL for the Routty REST API (all primary API calls)	ACTIVE
`files.routty.io`	File download domain for `/files` endpoints	ACTIVE
`import.routty.io`	File upload domain for import-related endpoints	ACTIVE
`export.routty.io`	File download domain for `/output-api` endpoints	ACTIVE

IP Address: 20.76.113.251
Protocol: HTTPS (TCP 443)