Guides: Accounting Integration · Innovorder API Documentation

This guide details how to retrieve aggregated financial and treasury data from the Innovorder platform for accounting purposes. There are three primary methods depending on your needs: retrieving a consolidated report (recommended), batching individual orders, or listening to real-time webhooks.

1. Authentication

As with all integrations, you must first authenticate using your Service Account credentials.

POST`/oauth/login`Get Access Token

Authenticate using your service account credentials. The access token is valid for 24 hours (14 days when rememberMe is true); when it expires the API responds with a 401 error (token_expired) and you must authenticate again.

Request Body

json

{
  "username": "service.account@brand.com",
  "password": "YOUR_SECURE_PASSWORD",
  "grant_type": "password"
}

Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

Property	Type	Example	Description
username	string	"service.account@brand.com"	The username value.
password	string	"YOUR_SECURE_PASSWORD"	The password value.
grant_type	string	"password"	The grant type value.

Response

json

{
  "access_token": "eyJhbGciOiJIUzI1...",
  "status": 201,
  "code": "token_created",
  "message": "You have successfully logged in.",
  "data": {
    "user": {
      "userId": 1,
      "email": "service.account@brand.com",
      "role": "brand",
      "brandId": 100
    }
  },
  "token_type": "Bearer"
}

Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

Property	Type	Example	Description
access_token	string	"eyJhbGciOiJIUzI1..."	The access token value.
status	integer	201	HTTP status code returned by the API.
code	string	"token_created"	Machine-readable application code for the result.
message	string	"You have successfully logged in."	Human-readable result message. Do not use this value for program logic.
data	object	{…}	Endpoint-specific response payload.
data.user	object	{…}	Object containing user fields.
data.user.userId	integer	1	Identifier of the user.
data.user.email	string	"service.account@brand.com"	Email address.
data.user.role	string	"brand"	The role value.
data.user.brandId	integer	100	Identifier of the brand.
token_type	string	"Bearer"	The token type value.

2. Retrieve Consolidated Treasury Report

The ATLAS Innovorder Data Platform provides a specialized endpoint to get a flat, JSON-formatted treasury report. This is the most efficient way to get accounting data for a specific period.

Base URLhttps://io-data-platform-prod-9666874309.europe-west1.run.app

GET`/reports/treasury`Get Treasury Report

Retrieve consolidated treasury and revenue data for a given period.

Parameters

Name	Type	Required	Description
startDate	string	Yes	Start date (YYYY-MM-DD).
endDate	string	Yes	End date (YYYY-MM-DD).
brandId	string	No	Filter by Brand ID.
exportJson	boolean	Yes	Must be true to get JSON format.

Response

json

{
  "metadata": {
    "period": {
      "startDate": "2025-09-01",
      "endDate": "2025-09-30"
    },
    "filters": {
      "brandId": "1760",
      "brandName": "INRAE IDF - NEWREST"
    },
    "generatedAt": "2025-11-18T14:24:30.140Z"
  },
  "walletBalances": {
    "beginningBalance": 4351752,
    "endingBalance": 4580504
  },
  "treasury": [
    {
      "operationType": "cashPayments",
      "guestPaymentType": "CASH",
      "count": 29,
      "amount": 14043
    },
    {
      "operationType": "creditCard",
      "guestPaymentType": "PREPAYMENT",
      "count": 1857,
      "amount": 6012834
    }
  ],
  "revenue": [
    {
      "category": "entranceFees",
      "label": "Admission",
      "guestPaymentType": "PREPAYMENT",
      "vatRate": 1000,
      "count": 16662,
      "amountExclTax": 601891,
      "amountTax": 60189,
      "amountInclTax": 662080
    }
  ]
}

Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

Property	Type	Example	Description
metadata	object	{…}	Additional metadata supplied with the response.
metadata.period	object	{…}	Object containing period fields.
metadata.period.startDate	string	"2025-09-01"	Date or timestamp for start.
metadata.period.endDate	string	"2025-09-30"	Date or timestamp for end.
metadata.filters	object	{…}	Object containing filters fields.
metadata.filters.brandId	string	"1760"	Identifier of the brand.
metadata.filters.brandName	string	"INRAE IDF - NEWREST"	The brand name value.
metadata.generatedAt	string	"2025-11-18T14:24:30.140Z"	Date or timestamp for generated.
walletBalances	object	{…}	Object containing wallet balances fields.
walletBalances.beginningBalance	integer	4351752	The beginning balance value.
walletBalances.endingBalance	integer	4580504	The ending balance value.
treasury	array	[…]	List of treasury entries.
treasury[]	object	{…}	Object containing treasury fields.
treasury[].operationType	string	"cashPayments"	The operation type value.
treasury[].guestPaymentType	string	"CASH"	The guest payment type value.
treasury[].count	integer	29	Total number of matching records.
treasury[].amount	integer	14043	The amount value.
revenue	array	[…]	List of revenue entries.
revenue[]	object	{…}	Object containing revenue fields.
revenue[].category	string	"entranceFees"	The category value.
revenue[].label	string	"Admission"	The label value.
revenue[].guestPaymentType	string	"PREPAYMENT"	The guest payment type value.
revenue[].vatRate	integer	1000	The vat rate value.
revenue[].count	integer	16662	Total number of matching records.
revenue[].amountExclTax	integer	601891	The amount excl tax value.
revenue[].amountTax	integer	60189	The amount tax value.
revenue[].amountInclTax	integer	662080	The amount incl tax value.

Response Data Dictionary

Wallet Balances

Global E-Wallet balance snapshot for the period. Note: Filtering by restaurant is not yet supported for this specific field.

Field	Description
beginningBalance	Total balance in cents at the start of the period.
endingBalance	Total balance in cents at the end of the period.

Treasury (Payments)

Breakdown of all financial flows (in/out).

Field	Description
operationType	The payment method or operation. E.g., `cashPayments`, `creditCard`, `refundCash`.
guestPaymentType	Classification of the payment: `CASH`: Payment at the POS/Kiosk. `PREPAYMENT`: Use of E-Wallet funds (or Reload). `POSTPAYMENT`: Paid later (invoice).
amount	Total value in cents.

Revenue (Sales)

Breakdown of what was sold (Items, Admissions, Grants).

Field	Description
category	Main category: `entranceFees`, `items`, `grants`, `discounts`.
vatRate	VAT rate in basis points (1000 = 10%).
amountExclTax	Amount excluding tax (HT) in cents.
amountTax	Tax amount (TVA) in cents.
amountInclTax	Total amount including tax (TTC) in cents.

3. Alternative Integration Methods

Method A: Order Batching

Use the GET /v1/orders endpoint to retrieve individual orders for a day and aggregate them on your side.

Pros: Highest granularity (line items, customer details).
Cons: Requires heavy pagination and data processing.

Method B: Real-time Webhooks

Subscribe to orders.paid webhook events to receive transaction data instantly as it happens.

Pros: Real-time updates, event-driven.
Cons: Requires robust infrastructure to handle retries and potential downtime.