This API document describes the Scrada API.

1.20

• Peppol outbound Send self-billing invoice added.

1.19

• Add sales invoice endpoint also supports amounts including VAT.
• Peppol outbound Send sales invoice endpoint also supports amounts including VAT.
• Peppol inbound Get PDF of inbound document added.
• Rate limiting documentation added.

1.18

• New Add sales invoice endpoint added.
• Existing Add invoice endpoint marked as deprecated.
• Peppol outbound Send sales invoice endpoint added.

1.17

• Peppol functionality is added. Companies of type 'Peppol Only' can register customers on Peppol, receive inbound documents and put documents on Peppol.

1.16

• Add invoice lines extended with ItemGroup.

1.15

• Add lines to journal extended with CashBookTransactions.

1.14

• Journal returns MinimumPossibleLineDate and MaximumPossibleLineDate.
• Journal has a setting AllowMultipleEntries.
• Cash book returns MinimumPossibleLineDate and MaximumPossibleLineDate.

1.13

• Journal AddFiguresApi has a new option 5.

1.12

• Company invoice extended with InvoiceSend, PartyLanguageCode, PartyTaxNumberType, PartyTaxNumber, and PartyGlnNumber.
• Company invoice support payment method 1 Unknown, 9 Debit Card.

1.11

• Add cash book lines extended with optional properties ExternalReference and ExternalData.

1.10

• Add invoice lines extended with AccountingAnalytical1 till AccountingAnalytical5.
• Add lines to the journal response extended with Message.

1.9

• Company invoice PartyAccountingCode added.
• Company invoice line AccountingGeneralLedger added.

1.8

• Company invoice VAT types added.

1.7

• Add AllowMultiple to Payment method.

1.6

• Company invoices added.
• Add lines to the journal extended with InvoiceID, InvoiceReference ExternalReference and ExternalData.

1.5

• Cash book, Company, VAT period and Journal API's added.

1.4

• Extended add lines to the cash book with additional (optional) fields.

1.3

• Minor fixes.

1.2

• Add lines to the cash book added.

Test environment:

• URL API: https://apitest.scrada.be/v1/...
• URL web client: https://mytest.scrada.be
  • If you want an account for the test environment, please send an email to info@scrada.be
  • In the test environment everything is working except the e-mail service. Because of that it is not possible to change you password, create new user accounts, ...

Production environment:

• URL API: https://api.scrada.be/v1/...
• URL web client: https://my.scrada.be

Postman collection: https://www.postman.com/scrada

Authentication on the Scrada API is handled using API keys. The API Key and corresponding password are added to every request on the API using the following header keys:

• X-API-KEY
• X-PASSWORD

The API key and password are unique for each company in Scrada.

To obtain an API key go to the Scrada web client. In the menu go to 'Settings' > 'API Keys'.

Here you can either create an API Key or see existing API keys of your company.

The Scrada API expects data in the following way.

The API is, like the Scrada Mobile app and web client, multilingual. To change the response language you can set the header key Language, the following values can be used:

English will be used when no language key is provided.

⚠️ Note: Rate limiting is currently not strictly enforced in the production environment.
A significantly higher limit is in place until January 1, 2026, after which the standard rate limiting rules described below will apply.

To ensure fair usage and maintain optimal performance, our API enforces rate limiting using a token bucket algorithm.

• Maximum Requests per Minute: 60
• Token Replenishment: Every 10 seconds, your bucket is refilled with 10 tokens

This allows for short bursts of activity while maintaining a steady request rate over time. If your token bucket is empty, additional requests will be rate-limited until new tokens are added.

Each API response includes the following headers to help you monitor your usage:

We recommend implementing logic in your client to respect these headers and avoid hitting the rate limit.

If you exceed the allowed request rate, the API will respond with:

• HTTP Status Code: 429 Too Many Requests

When this occurs, you should wait until the x-ratelimit-reset time has passed before retrying your request.

This examples show how you can add a sales invoice in Scrada and add a payment to one invoice.

1. Add the invoice

Add a sales invoice in Scrada by using the Add sales invoice API.

https://api.scrada.be/v1/company/{companyID}/salesInvoice

Fore more information about this API call go to the Invoice > Add sales invoice section.

{
  "bookYear": "2023",
  "journal": "Store1",
  "number": "123",
  "creditInvoice": false,
  "invoiceDate": "2023-01-01",
  "invoiceExpiryDate": "2023-01-08",
  "customer": {
    "code" : "CUST01",
    "name": "Customer 01",
    "address": {
      "street": "Customer street",
      "streetNumber": "1",
      "city": "Fropus",
      "zipCode": "1000",
      "countryCode": "BE"
    },
    "email": "info@scrada.be",
    "vatNumber": "BE0793904121"
  },
  "totalInclVat": 200.00,
  "totalVat": 34.71,
  "totalExclVat": 165.29,
  "payableRoundingAmount": 0,
  "note": "",
  "lines": [
    {
      "lineNumber": "1",
      "itemName": "Demo item",
      "quantity": 1,
      "unitType": 1,
      "itemExclVat": 165.29,
      "vatType": 1,
      "vatPercentage": 21,
      "totalDiscountExclVat": 0,
      "totalExclVat": 165.29
    }
  ],
  "vatTotals": [
    {
      "vatType": 1,
      "vatPercentage": 21,
      "totalExclVat": 165.29,
      "totalVat": 34.71,
      "totalInclVat": 200.00
    }    
  ],
  "paymentMethods": [
    {
      "paymentType": 9,
      "paymentReference": "+++022/0126/70950+++",
      "name": "Bancontact",
      "totalPaid": 0,
      "totalToPay": 200
    }
  ]
}

This will return a GUID, for example cac6315f-ef7a-4405-b1cf-1ccccc2cc007. We will use this GUID in the next step to add a payment to the sales invoice.

2. Add journal lines

Now we will add €500,00 of dailyreceipts to the journal, of which €400,00 was paid by Bancontact and €100,00 cash, and add a payment of €200,00 paid by Bancontact to the invoice we created in step 1. We add the lines using the Add lines to the journal API.

https://api.scrada.be/v1/company/{companyID}/journal/{journalID}/lines

{
  "date": "2023-01-01",
  "lastJournalLineID": "{lastJournalLineID}", // Optional GUID from your previous add journal lines call
  "lines": [
    {
      "lineType": 1,
      "vatTypeID": "8424d909-78b9-483c-9b1d-4584fb537846",
      "vatPerc": 21,
      "amount": 500,
      "categoryID": "{categoryID}", // 21% VAT category
      "externalReference": "", // Additional reference from your system
      "externalData": "" // Additional information from your system like receipts numbers and their individual amounts
    }
  ],
  "paymentMethods": [
    {
      "paymentMethodID": "{paymentMethodID}", // Bancontact payment method ID
      "amount": 600.00, // Total received 600.00 by Bancontact
      "remark": "",
      "externalReference": "", // Additional reference from your system
      "externalData": "" // Additional information from your system like receipts numbers and their individual amounts
    },
    {
      "paymentMethodID": "{paymentMethodID}", // Cash payment method ID
      "amount": 100.00, // Received 100.00 cash
      "remark": "",
      "externalReference": "", // Additional reference from your system
      "externalData": "" // Additional information from your system like receipts numbers and their individual amounts
    },
    {
      "paymentMethodID": "{paymentMethodID}",  // Invoice payed payment method ID
      "amount": -200.00, // Deduct paid invoice amount
      "remark": "string",
      "invoiceID": "cac6315f-ef7a-4405-b1cf-1ccccc2cc007", // GUID of the invoice created in step 1
      "invoiceReference": "+++022/0126/70950+++", // Optional invoice reference, when invoiceID is provided Scrada will add a payment reference if provided on the invoice
      "externalReference": "", // Additional reference from your system
      "externalData": "" // Additional information from your system like receipts number and its amount
    }
  ]
}

This will return a GUID for the journalLInes, the last journalLines GUID can be used in your next add journal lines call lastJournalLineID.

Webhooks are organized into topics. Your app subscribes to one or more topics to receive webhooks. Once configured, your app will receive webhooks each time that type of event is triggered for that company.

The webhook topic defines the kind of event messages that your app receives. For example, your app can subscribe to the journal/linesMissing topic to be notified when you are behind on journal entries. The topic name identifies the nature of the event that's occurred.

journal/linesMissing

The topic journal/linesMissing is triggered once a day if a journal has missing lines. This is triggered at the same time that Scrada also send emails if journal lines are missing. Normally this is around 12:30. A formatted payload of this topic looks like:

{
  "companyID":"da31b6ec-ba3e-448c-b808-f3a7f8a53859",
  "companyCode":"",
  "companyName":"Example company",
  "journalID":"48dbd6cf-42a7-4565-be6b-f41544a56b28",
  "journalCode":"003",
  "journalName":"jounal4",
  "journalDateOfLastEntry":"2021-01-10"
}

peppolOutboundDocument/statusUpdate

The topic peppolOutboundDocument/statusUpdate is triggered when the status of an outbound Peppol document is changed. More information about the properties of the webhook can can be found in the section Peppol Outbound > Get outbound document status. The API call and the webhook return the same information.

A formatted payload of a status Created:

{
  "id": "21a076e5-ee44-47a4-a21b-a7b45682d54f",
  "createdOn": "2024-12-24T12:00:06.187Z",
  "externalReference": "test-invoice-scrada-1",
  "status": "Created",
  "attempt": 0,
  "errorMessage": "",
  "peppolSenderID": "9915:test-sender",
  "peppolReceiverID": "0208:0793904121",
  "peppolC1CountryCode": "BE",
  "peppolC2Timestamp": null,
  "peppolC2SeatID": "PBE000659",
  "peppolC2MessageID": null,
  "peppolC3Timestamp": null,
  "peppolC3SeatID": null,
  "peppolC3MessageID": null,
  "peppolConversationID": null,
  "peppolSbdhInstanceID": null,
  "peppolDocumentTypeScheme": "busdox-docid-qns",
  "peppolDocumentTypeValue": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
  "peppolProcessScheme": "cenbii-procid-ubl",
  "peppolProcessValue": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
  "salesInvoiceID": "21a076e5-ee44-47a4-a21b-a7b45682d54g"
}

A formatted payload of a status Processed:

{
  "id": "21a076e5-ee44-47a4-a21b-a7b45682d54f",
  "createdOn": "2024-12-24T12:00:06.187Z",
  "externalReference": "test-invoice-scrada-1",
  "status": "Processed",
  "attempt": 1,
  "errorMessage": "",
  "peppolSenderID": "9915:test-sender",
  "peppolReceiverID": "0208:0793904121",
  "peppolC1CountryCode": "BE",
  "peppolC2Timestamp": "2024-12-24T12:00:23.039Z",
  "peppolC2SeatID": "PBE000659",
  "peppolC2MessageID": "21a076e5-ee44-47a4-a21b-a7b45682d54f@scrada",
  "peppolC3Timestamp": "2024-12-24T12:00:23.743Z",
  "peppolC3SeatID": "PBE000659",
  "peppolC3MessageID": "3f34cb91-afc6-4a0f-8b13-90ff6c99e28a@phase4",
  "peppolConversationID": "conv-21a076e5-ee44-47a4-a21b-a7b45682d54f@scrada",
  "peppolSbdhInstanceID": "21a076e5-ee44-47a4-a21b-a7b45682d54f",
  "peppolDocumentTypeScheme": "busdox-docid-qns",
  "peppolDocumentTypeValue": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
  "peppolProcessScheme": "cenbii-procid-ubl",
  "peppolProcessValue": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
  "salesInvoiceID": "21a076e5-ee44-47a4-a21b-a7b45682d54g"
}

A formatted payload of a status error:

{
  "id": "b91a383b-0c96-467a-b791-ffe971b6c52d",
  "createdOn": "2024-12-24T12:16:18.958Z",
  "externalReference": "test-invoice-scrada-2",
  "status": "Error",
  "attempt": 1,
  "errorMessage": "[error] [SAX] cvc-complex-type.2.4.a: Invalid content was found starting with element '{\"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2\":DueDatee}'. ...",
  "peppolSenderID": "9915:test-sender",
  "peppolReceiverID": "0208:0793904121",
  "peppolC1CountryCode": "BE",
  "peppolC2Timestamp": null,
  "peppolC2SeatID": "PBE000659",
  "peppolC2MessageID": "b91a383b-0c96-467a-b791-ffe971b6c52d@scrada",
  "peppolC3Timestamp": null,
  "peppolC3SeatID": null,
  "peppolC3MessageID": null,
  "peppolConversationID": "conv-b91a383b-0c96-467a-b791-ffe971b6c52d@scrada",
  "peppolSbdhInstanceID": "b91a383b-0c96-467a-b791-ffe971b6c52d",
  "peppolDocumentTypeScheme": "busdox-docid-qns",
  "peppolDocumentTypeValue": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
  "peppolProcessScheme": "cenbii-procid-ubl",
  "peppolProcessValue": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
  "salesInvoiceID": "21a076e5-ee44-47a4-a21b-a7b45682d54g"
}

salesInvoice/sendStatusUpdate

The topic salesInvoice/sendStatusUpdate is triggered when the send status to customer of a sales invoice is changed. This is only triggered if a full subscription of Scrada is active. It is not trigged when you have a Peppol Only subscription. In case of Peppol Only subscription you have to use the topic peppolOutboundDocument/statusUpdate.

More information about the properties of the webhook can can be found in the section Invoice > Get sales invoice send status. The API call and the webhook return the same information.

A formatted payload of a status Created:

{
  "id": "916ae8fa-2531-4cad-9c64-6218187f1db4",
  "createdOn": "2025-02-20T17:14:58.755Z",
  "externalReference": "DB_1|46a5e373-4337-4d68-92be-30ec6d2c7d90",
  "peppolSenderID": null,
  "peppolReceiverID": null,
  "peppolC1CountryCode": null,
  "peppolC2Timestamp": null,
  "peppolC2SeatID": null,
  "peppolC2MessageID": null,
  "peppolC3MessageID": null,
  "peppolC3Timestamp": null,
  "peppolC3SeatID": null,
  "peppolConversationID": null,
  "peppolSbdhInstanceID": null,
  "peppolDocumentTypeScheme": null,
  "peppolDocumentTypeValue": null,
  "peppolProcessScheme": null,
  "peppolProcessValue": null,
  "status": "Created",
  "attempt": 0,
  "errorMessage": "",
  "peppolOutboundDocumentID": "851afd33-ad37-4538-9456-4297f133e724",
  "sendMethod": "Peppol",
  "receiverEmailAddress": null,
  "receiverEmailTime": null,
  "receiverEmailStatus": "Not sent"
}

A formatted payload of a status Processed and send by Peppol:

{
  "id": "916ae8fa-2531-4cad-9c64-6218187f1db4",
  "createdOn": "2025-02-20T17:14:58.755Z",
  "externalReference": "DB_1|46a5e373-4337-4d68-92be-30ec6d2c7d90",
  "peppolSenderID": "0208:0793904121",
  "peppolReceiverID": "0208:0793904121",
  "peppolC1CountryCode": "BE",
  "peppolC2Timestamp": "2025-02-20T17:15:24.119Z",
  "peppolC2SeatID": "PBE000659",
  "peppolC2MessageID": "916ae8fa-2531-4cad-9c64-6218187f1db4@scrada",
  "peppolC3MessageID": "aa3e293c-70a5-491a-a317-8e884bd6a628@phase4",
  "peppolC3Timestamp": "2025-02-20T17:15:24.430Z",
  "peppolC3SeatID": "PBE000659",
  "peppolConversationID": "conv-916ae8fa-2531-4cad-9c64-6218187f1db4@scrada",
  "peppolSbdhInstanceID": "916ae8fa-2531-4cad-9c64-6218187f1db4",
  "peppolDocumentTypeScheme": "busdox-docid-qns",
  "peppolDocumentTypeValue": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
  "peppolProcessScheme": "cenbii-procid-ubl",
  "peppolProcessValue": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
  "status": "Processed",
  "attempt": 1,
  "errorMessage": "",
  "peppolOutboundDocumentID": "851afd33-ad37-4538-9456-4297f133e724",
  "sendMethod": "Peppol",
  "receiverEmailAddress": null,
  "receiverEmailTime": null,
  "receiverEmailStatus": "Not sent"
}

A formatted payload of a status Processed and send by email:

{
  "id": "916ae8fa-2531-4cad-9c64-6218187f1db4",
  "createdOn": "2025-02-20T17:09:25.509Z",
  "externalReference": "DB_1|46a5e373-4337-4d68-92be-30ec6d2c7d90",
  "peppolSenderID": "0208:0793904121",
  "peppolReceiverID": "0208:0793904121",
  "peppolC1CountryCode": "BE",
  "peppolC2Timestamp": null,
  "peppolC2SeatID": null,
  "peppolC2MessageID": "916ae8fa-2531-4cad-9c64-6218187f1db4@scrada",
  "peppolC3MessageID": null,
  "peppolC3Timestamp": null,
  "peppolC3SeatID": null,
  "peppolConversationID": "conv-916ae8fa-2531-4cad-9c64-6218187f1db4@scrada",
  "peppolSbdhInstanceID": "916ae8fa-2531-4cad-9c64-6218187f1db4",
  "peppolDocumentTypeScheme": null,
  "peppolDocumentTypeValue": null,
  "peppolProcessScheme": null,
  "peppolProcessValue": null,
  "status": "Processed",
  "attempt": 1,
  "errorMessage": "",
  "peppolOutboundDocumentID": null,
  "sendMethod": "Email",
  "receiverEmailAddress": "info@scrada.be",
  "receiverEmailTime": "2025-02-20T17:09:30.509Z",
  "receiverEmailStatus": "Successfully sent"
}

peppolInboundDocument/new

The topic peppolInboundDocument/new is triggered when a new document arrives by Peppol in Scrada and you have a Peppol Ony Subscription. In case of a full subscription you have to use the topic purchaseInvoice/new.

This webhook has some extra headers:

The content of the payload is the received document from Peppol. This depends of the document type. If registred on certain document type then these document types can be received.

purchaseInvoice/new

The topic purchaseInvoice/new is triggered when a new purchase invoice arrives in Scrada. This is only triggered if a full subscription of Scrada is active. It is not trigged when you have a Peppol Only subscription. In case of Peppol Only subscription you have to use the topic peppolInboundDocument/new. This can also be triggered if a new purchase invoice arrives in Scrada from an other channel then Peppol.

This webhook has some extra headers:

If the purchase invoice arrived by Peppol then also the headers of peppolInboundDocument/new are available in this topic.

The content of the payload depends from the channel that was used to deliver the purchase invoice to Scrada. If it is Peppol then most of the times this is an XML document. But it can also be a PDF if a PDF was uploaded manually by the user.

A webhook subscription declares the app’s intention to receive webhooks for a topic. A subscription is defined by:

• The topic name
• The subscription endpoint: The endpoint is the destination that Scrada sends the webhooks to. This can be either HTTP or HTTPS.

A webhook can be configured on company or on partner company level using the Scrada web client. In the menu go to 'Settings' > 'Integrations', click on the 'Activate'/'Edit' button in the 'Webhook' tile. If configured on partner company then this subscription will be active for all companies linked to this partner company.

Each webhook is made up of headers and a payload. Headers contain metadata about the webhook.

HMAC stands for Hash-based Message Authentication Code (HMAC) that can be used to determine whether a message sent over an insecure channel has been tampered with, provided that the sender and receiver share a secret key. The sender computes the hash value for the original data and sends both the original data and the HMAC as a single message. The receiver recomputes the hash value on the received message and checks that the computed hash value matches the transmitted hash value.

The secret key used to calculate the HMAC can be found in Scrada using the Scrada web client. In the menu go to 'Settings' > 'Company' and click on the eye icon next to 'Secret key'. If you ever need to generate a new secret key this can be done by clicking on the generate icon next to the eye icon.

If no secret key is present on the company the x-scrada-hmac-sha256 will be empty. Generate a new secret as described above.

Scrada uses the algorithm SHA-256.

Here are a few links to popular languages with HMAC capabilities:

• NodeJS
• Python
• PHP
• .NET C#

Sample calculation HMAC by Scrada:

• Input:
  • Payload:

    {"companyID":"da31b6ec-ba3e-448c-b808-f3a7f8a53859","companyCode":"","companyName":"Example company","journalID":"48dbd6cf-42a7-4565-be6b-f41544a56b28","journalCode":"003","journalName":"jounal4","journalDateOfLastEntry":"2021-01-10"}
    

  • Secret key: s4%^>>s8Ov$fB+szc3H&(_N@NVmOiy6&
  • Algorithm: SHA-256
• Output: 8e60bd58050f2b7846f6b9df1a3ee523b88dfb7805ef6d30f5a8162a9132c66d
• Online tool to calculate a HMAC is https://www.freeformatter.com/hmac-generator.html.

As with other webhook systems, Scrada doesn't guarantee ordering within a topic, or across different topics for the same resource. For example, it's possible that a salesinvoice/update webhook might be delivered before a salesinvoice/create webhook. Scrada recommends using timestamps provided in the header x-scrada-triggered-at to organize webhooks.

A http status success response 200 till 299 is considered successful. If your webhook didn't respond with a 200 till 299 http status code, then the delivery failed. If the delivery fails, then it's retried up to 10 times.

All webhooks executed with their status can be found in the Scrada web client. In the menu go to 'Settings' > 'Integrations', click on the 'History' button in the 'Webhook' tile. A webhook that is retrying can be cancelled using the Scrada web client.

In rare instances, your app may receive the same webhook event more than once. Scrada recommends detecting duplicate webhook events by comparing the x-scrada-event-id header to previous events x-scrada-event-id header.

x-scrada-topic: journal/linesMissing
x-scrada-hmac-sha256: 9c57b3a7e877c7d0f1116c6c4a399354a380b9a461ff1a8c07c9855464757b04
x-scrada-api-version: 1.0
x-scrada-company-id: da31b6ec-ba3e-448c-b808-f3a7f8a53859
x-scrada-event-id: 116445c1-f6f7-4fa1-809b-c69d91724713
x-scrada-triggered-at: 2024-10-10T19:10:35.815Z
x-scrada-attempt: 1

The website https://webhook.site/ can be used to see the headers and body of a webhook that is called by Scrada. Add the unique URL that is generated by https://webhook.site/ to the webhooks configuration in Scrada and see the webhooks called by Scrada.