API access¶
Under Settings → API access you give an external system access to the subscription's invoices, and decide what that system should be told about. The page is available to customer administrators and support only.
The page has two tabs: API keys and Webhooks.
API keys¶
An API key is the credential the external system sends with every request. It covers every company in the subscription — it is not tied to a user or to a single company. What it may use in those companies is what you choose under Access.
Create a key¶
- Choose Create API key.
- Give the key a name that says which system it is for.
- Under Access, choose what the key may use. See below.
- Choose Save.
The key is now shown in full. Copy it straight away — it is shown only this once and cannot be retrieved again. The list afterwards shows only its opening characters. If the key is lost, delete it and create a new one.
Access¶
For each area, choose No access, Read or Read and change:
- Purchase invoices — read the invoices and their lines, and with Read and change also correct them.
- Sales invoices, Expenses and Bank files — can only be read.
- Webhooks — see the subscription's webhooks, and with Read and change also create and delete them.
- PMS setup — read hotel integrations, PMS codes and PMS dimensions, and with Read and change also change them.
A new key has no access until you choose it. Every key can always read the companies and their accounts, dimensions, VAT combinations and vendors, though, because nothing else can be used without them.
You can change the access at any time by opening the key. The change applies from the system's next request. If the system asks for something the key has no access to, it is refused with an answer that says which access is missing.
Keys that existed before access could be chosen were given access to everything they could use before — but not to the PMS setup. That has to be chosen on the key.
Pause an integration¶
Switch Enabled off on the key. The system using it is refused immediately, exactly as if the key were unknown, but the row stays. Switch it back on and the integration works as before.
The Last used column shows when the key was last used, so a key nothing uses any more is easy to spot. The time is updated at most every five minutes.
Delete a key¶
Deleting cannot be undone, and integrations using the key stop working immediately.
Webhooks¶
A webhook is an address the platform sends a message to when something happens to an invoice. Instead of the external system asking again and again, it is told.
Create a webhook¶
- Choose Create webhook.
- Give it a name.
- Enter the Endpoint — the address the message is sent to. It must begin with
https://. - Choose the events the address should be told about:
- Invoice created — an invoice has arrived.
- Invoice updated — an invoice that already existed has changed.
- Optionally set a signing secret. See below.
- Choose Save.
A newly created webhook starts from the moment it was created. It reports what happens from then on and does not go through the invoices the subscription already holds.
An invoice that arrives and is changed shortly afterwards triggers Invoice created only.
The signing secret¶
If you set a signing secret, the platform sends a digest of the message content with every request.
The receiver can compute the same digest and thereby see that the message came from us and was not
altered on the way. The digest is in the X-2CA-Signature header.
The secret is never shown again once saved. Leave the field empty to keep the one you have, and type a new one to replace it.
Recent deliveries¶
Opening a webhook shows its most recent attempts at the bottom: time, event, which invoice it concerned, and what the address answered.
- A green status code means the message was received.
- A red code, or No response, means it was not.
A failed attempt is not repeated. If the address was down for a while, the failed attempts are listed and those messages have not been sent again.
Pause a webhook¶
Switch Enabled off. Nothing is sent while it is off. Switch it back on and it continues from where it stopped, sending what has arrived in the meantime.
Delete a webhook¶
The delivery history is deleted with the webhook.