# Integration Guide: Accounting

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 URL`https://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:<br>-   `CASH`: Payment at the POS/Kiosk.<br>-   `PREPAYMENT`: Use of E-Wallet funds (or Reload).<br>-   `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.