Skip to Main Content
Riverty Docs
    riverty logo Docs

    Register to AQI

    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.

    Look here for the registration process.

    Step 2: Review interfaces and use cases

    It is crucial to understand the Accounting as a Service interfaces. For this, please visit the details pages for the different interfaces and also look up the use cases (at the end of the pages):

    Each API endpoint includes detailed information about field lengths, required fields, dependencies, and allowed values.

    Step 3: Retrieve Your Subscription Key

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

    1. Locate Your Subscription Key:
    • Go to your user profile
    • The primary key for communication with Accounting as a Service will be displayed there.
    1. 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 Qualitative Response notification to ensure that you receive essential validation feedback on the data you send.

    Why the Qualiative Response 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 Qualitative Response, 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 Subscribe to the Qualitative Response Notification please look here.

    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 Qualitative Response 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.