# WeegoSoft AI Expense Builder - API Protocol

This document defines the data formatting protocol for developers and companies wishing to integrate their systems (ERP, SaaS, POS) with the AI Expense Builder application.

## 1. Integration Logic

The application synchronizes data to an external ERP system (e.g., WeegoSoft POS, Odoo, custom Webhook) via the **API / Webhook** configured in the advanced settings.
When the user clicks "Synchronisez avec POS / ERP", the application acts as an API Dispatcher. It formats the unsynced entries into a standard JSON payload and sends an HTTP `POST` request to the target URL.

## 2. Request Specification

- **Method**: `POST`
- **Content-Type**: `application/json`
- **Authorization**: `Bearer <token>` (Configured in settings)
- **Payload Format**: An object containing the integration metadata and an array of entries.

### Payload Structure

```json
{
  "user_id": 1,
  "source": "weegosoft_expense_builder",
  "timestamp": "2026-02-26T07:30:00+01:00",
  "integration_type": "webhook",
  "entries": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "dépense",
      "marchand": "Supermarché Express",
      "montant_ttc": 15000,
      "montant_ht": 12712,
      "tva": 2288,
      "frais": 0,
      "devise": "FCFA",
      "categorie": "repas",
      "description": "Achat de fournitures de bureau et café",
      "date": "2026-02-24",
      "source": "ocr",
      "synced": false
    }
  ]
}
```

## 3. Data Dictionary

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `id` | UUID | Yes | Globally unique identifier (v4) for the transaction. |
| `type` | String | Yes | `dépense` (expense) or `revenu` (income). |
| `marchand` | String | Yes | Name of the merchant or source of funds. |
| `montant_ttc` | Number | Yes | Total amount including taxes and fees. |
| `montant_ht` | Number | No | Amount excluding taxes. |
| `tva` | Number | No | Value Added Tax (TVA) amount. |
| `frais` | Number | No | Transaction fees (e.g., Mobile Money fees). |
| `devise` | String | Yes | Currency code (default: `FCFA`). |
| `categorie` | String | Yes | Category: `repas`, `transport`, `fournitures`, `hebergement`, `salaire`, `vente`, `loyer`, `autre`. |
| `description` | String | No | Detailed description or extracted text. |
| `date` | Date | Yes | Transaction date in `YYYY-MM-DD` format. |
| `source` | String | Yes | Extraction method: `text`, `voice`, `ocr`, `sms`. |
| `synced` | Boolean | Yes | Internal sync status (always `false` for new pushes). |

## 4. Idempotency (Anti-Duplicates)

Network requests can fail, timeout, or be duplicated. To prevent creating the same financial entry multiple times in your ERP, the receiving API **MUST implement idempotency**.

Every entry in the `entries` array contains a unique UUID in the `id` field.
When receiving the payload, your server should perform the following logic for each entry:

1. Look up the database to see if a transaction/payment with this `id` (as a primary key or reference column) already exists.
2. If it **exists**, ignore the insertion (or update the existing record if needed).
3. If it **does not exist**, insert the new transaction.

By strictly adhering to this logic, users can re-trigger synchronization as many times as they want without risking duplicate accounting entries.

## 5. Expected Response

The external API should return a `2xx` (e.g., `200 OK` or `201 Created`) status code to confirm successful receipt and processing. The response body is typically JSON.

{
  "status": "success",
  "message": "Data received successfully"
}

```

## 5. Batch Classification API (Internal)

The application uses an internal batch processing mechanism to reclassify large volumes of entries via AI without exceeding token limits.

### Endpoint Structure for `query_api.php`
- **Method**: `POST`
- **Action**: `command: "RECLASSIFY_ALL_OHADA"`
- **Batching**: The frontend (`script.js`) automatically splits entries into chunks of 15 and sends sequential requests.
- **Payload Example**:
```json
{
  "command": "RECLASSIFY_ALL_OHADA",
  "entries": [ /* Array of up to 15 entries */ ],
  "totals": { "income": 1000, "expense": 500, "net": 500 }
}
```

### AI Response Structure (Trimmed for efficiency)

To prevent JSON truncation, the AI is instructed to return *only* the modified IDs and categories:

```json
{
  "updates": [
    {"id": "550e8400-e29b-41d4-a716-446655440000", "categorie": "Achat de marchandises (60)"}
  ],
  "analysis": "Brief summary of changes."
}
```

## 6. Security Recommendations

- **HTTPS**: Your callback URL must use HTTPS to ensure data encryption.
- **Authentication**: We recommend implementing a token-based authentication (e.g., via a custom header or API key in the URL).