Register for the Accounting as a Service - APIs

Welcome to the API Registration Guide for Accounting as a Service! This page will walk you through the steps to create a user account, obtain your subscription keys, and set up notifications to get started with integrating your systems.

Authentication

When working with the REST API of Accounting as a Service, you will have to use one of your subscription keys as the form of authentication for all API related requests that you are going to make.

You will be provided with a primary and secondary subscription key for each of the following environments.

Step 1: Request Your Free Test Account

Before integrating with Accounting as a Service, you need a test account. This account will allow you to connect to our TEST environment, explore the API, and start testing without any cost or obligation.

How to Subscribe for a Test Account:

  1. Visit the API Explorer

  2. Click the "Sign up" button on the top right corner

  3. Follow the instructions to fill out the subscription form with your details. Ensure all required fields are completed accurately.

  4. After submitting the form, you will receive a confirmation email. This email contains a link to the API Explorer, where you can manage your subscription and access your API keys.

  5. After confirmation of your account, log in to the API Explorer and click on "Products" in the main navigation

  6. Select Sandbox client

  7. Define your own name for the subscription and then click "Susbcribe" button. It will generate an API key to use the API

Done! now you are registered to the Accounting as a Service AQI.

Step 2: Access the API Explorer

The API Explorer is a crucial tool that provides technical details on all available interfaces and allows you to test them in a controlled environment. Please find below a step by step documentation how to find the relevant information:

  1. Log into the API Explorer
  2. Use the credentials provided in your confirmation email to log into the API Explorer.
  3. Click on "APIs" in the main navigation
  4. Click on "Accounting -v1"

Browse through the API documentation, which covers all incoming interfaces, including:

  • Create Order - used to hand over orders to Accounting as a service. This interface is the prerequisite for all following processes.
  • Cancel Order - used to cancel an entire order or an order position (only entire line items can be cancelled)
  • Create Invoice - used to hand over created invoices or initiate the invoice creation for orders that have been fulfilled
  • Update Invoice - used to update a previously sent invoice (The price cannot be increased for an existing invoice)
  • Add Goodwill - used to book a goodwill and initiate refund for an existing invoice (goodwills cannot be grated for orders that have not been invoiced)
  • Return Order - used to book a return for an existing invoice (a return can only be booked if the order has been fulfilled/invoiced)
  • Add Payment - used to provide payment details especially for omnichannel orders (replaces a settlement file) Each API endpoint includes detailed information about field lengths, required fields, dependencies, and allowed values. Use the "Try-it" Section:

The API Explorer features a "Try-it" section where you can input data to test the APIs directly. You can view requests in various programming languages, making it easier to implement the APIs in your systems. Send test requests to see responses and validate the setup.

Step 3: Retrieve Your Subscription Key

Your subscription key is essential for authenticating API requests and connecting your systems to Accounting as a Service.

API-Key_in_Profile

  1. Locate Your Subscription Key:
    • Go to your user profile within the API Explorer.
    • The primary key for communication with Accounting as a Service will be displayed there.
  2. Copy and Secure Your Key:
    • Copy the subscription key and keep it secure. This key will be used in your API integration setup.

During the onboarding, you will be provided with a dedicated product that will be made available to you in the product list of the API Explorer. The product will contain specific configuration tailored to your setup. You will need to subscribe to this product (first in TEST, later in PROD environment) by following the same procedure as for the subscription related to the sample client.

Please note: Your subscription keys are sensitive data that should be securely stored in your system. If one of your subscription key is lost or compromised, a new subscription key will need to be generated. In case you require the replacement (new generation) of one of your subscription keys, you can do so via the user profile page in the API Explorer of the affected environment.

How to use your subscription key

When indicating the subscription key for making requests, you will have to provide the key by using the request header attribute X-Subscription-Key as shown in the following sample request using the endpoint /payments/{version}/token of the TEST environment and the sample subscription key 321123ab544047e795db43e5123423tz:

GET /payments/v1/token HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: 321123ab544047e795db43e5123423tz

Step 4: Subscribe to Notifications

Notifications help keep your systems updated on events within Accounting as a Service, enabling you to respond proactively to key processes like payment management, reconciliation, and error handling. It is mandatory to subscribe to the EDI Error Sent notification to ensure that you receive essential validation feedback on the data you send.

Why the EDI Error Sent Notification is a Must-Have

Accounting as a Service handles all incoming requests through an asynchronous processing approach. When you send a request to any endpoint within the accounting module, the REST API will initially respond with an internalRequestId. This ID confirms receipt of your request but does not mean that the data provided could be processed.

Validation is the first critical step in processing your request in Accounting as a Service. Upon completion of the validation process, the system will issue a notification of type accounting/EdiErrorSent, which provides detailed results of the validation. This feedback is crucial as it allows you to promptly address any errors or issues that may have arisen during the validation but also confirms eventually, that your request could be processed.

To Trigger an EDI Error Sent Notification

To receive an accounting/EdiErrorSent notification:

  • Send a request to any of the accounting module endpoints as outlined in the API Explorer.
  • The action will automatically trigger the validation process, followed by an EDI Error Sent notification that informs you of the validation outcome. This option can already be used in the sandbox client.

Register for notifications

To register a callback for the EDI Error Sent notifications (this process can also be used for other notifications but for the start, this notification is the most important as it is mandatory):

  1. Make a POST Request to Subscribe:

To subscribe to notifications, make a POST request to the following endpoint:

{
POST /administration/v1/notification-callbacks
}
  1. Set Up Notification Types:

In the request body, specify the notification types you wish to subscribe to. For the mandatory EDI Error Sent notification, use accounting/EdiErrorSent as the value in the notificationTypes array.

Example Request Body:

{
    "callbackUrl": "https://webhook.site/4ad3c92c-2ac1-4587-9e5e-98877195ec88",
    "description": "Validation feedback from Accounting as a Service for my requests",
    "id": "5b2efc5d-eb64-43eb-99fb-69728c3d2ce0",
    "notificationTypes": ["accounting/EDIErrorSent"]
}

IMPORTANT In case your callback URL is not freely accessible from the internet, please make sure to have a suitable firewall opening in place.

  1. Testing Notifications:

Use the "Try-it" section in the API Explorer to simulate notifications and ensure your system can receive and process them correctly. By subscribing to the EDI Error Sent notification, you are ensuring that you receive timely and detailed feedback on every request, allowing for immediate action and smooth integration with Accounting as a Service. This is a crucial step to complete before moving on to the next phase of your integration.

Step 5: Build and Test Your Integration in the Sandbox Environment

The sandbox environment (sandbox client) is a crucial tool for building and testing your integration with Accounting as a Service. This environment allows you to set up connections, configure your interfaces, and validate your integration before going live.

Build Your Integration Using the Sandbox:

  1. Set Up Your Connection: Use the sandbox environment to establish your initial connection using your subscription key. This environment mirrors the live setup, enabling you to configure each required interface (e.g., create order, cancel order, create invoice) as you would in the real-world application.
  2. Develop Your Integration: Use the sandbox to build out your integration by connecting your systems to the relevant endpoints of Accounting as a Service. The sandbox provides a safe space to work through the technical setup and refine your configurations.

Test Your Integration:

  1. Send Test Requests and Receive Feedback: Test each interface by sending requests through the sandbox environment. Each request will be processed asynchronously, returning an internalRequestId as an initial response. Subscribe to the EDI Error Sent notifications to receive validation feedback for each request. These notifications will confirm whether your data meets the required standards or if any corrections are needed.
  2. Validate Your Integration: Continue testing until you receive successful confirmation notifications for all relevant interfaces. Use the "Try-it" feature in the API Explorer to simulate real-world scenarios and validate that your setup responds correctly.

By building and testing your integration thoroughly in the sandbox environment, and then transitioning with the guidance of your onboarding manager, you can ensure a seamless and effective implementation of Accounting as a Service.