Unprocessed expense claims (toPrepare)

# Instructions — Unprocessed expense claims (expenseClaim + toPrepare)

## ✅ Compound AND filter: resolved (verified 2026-07-22)

An `AND` filter combining `payableType=expenseClaim` and `bookkeepingStatus=toPrepare` now works normally — replayed live, no more `"Unable to get payables"` error. The compound filter can be used directly, no post-filtering step needed.

```json
{
  "companyId": "...",
  "filters": {
    "operator": "and",
    "subfilters": [
      { "field": "payableType", "operator": "=", "value": ["expenseClaim"] },
      { "field": "bookkeepingStatus", "operator": "=", "value": ["toPrepare"] }
    ]
  },
  "pageSize": 100
}
```

Paginate if `meta.pagination.hasNextPage=true` (use `cursor` for the next page).

## ⚠️ Returned field: `bookkeepingStatus` (not `state`)

The returned payable exposes the accounting status via `bookkeepingStatus` directly (verified live — no `state` field in the response):
- `bookkeepingStatus: "toPrepare"` → not yet processed
- `bookkeepingStatus: "toExport"` → ready for the ERP
- `bookkeepingStatus: "exported"` → already exported

## Alternative approach (simple filter + post-filtering)

If you'd rather avoid the compound filter (e.g. to reuse a single filter across several use cases):

### Option A — Filter by payableType, post-filter by bookkeepingStatus

```json
// Call 1: get_payables with payableType only
{
  "companyId": "...",
  "filters": { "field": "payableType", "operator": "=", "value": ["expenseClaim"] },
  "pageSize": 100
}
```
→ Post-filter client-side: `payables.filter(p => p.bookkeepingStatus === "toPrepare")`

### Option B — Filter by bookkeepingStatus, post-filter by payableType

```json
// Call 1: get_payables with bookkeepingStatus only
{
  "companyId": "...",
  "filters": { "field": "bookkeepingStatus", "operator": "=", "value": ["toPrepare"] },
  "pageSize": 100
}
```
→ Post-filter client-side: `payables.filter(p => p.payableType === "expenseClaim")`

**Option B is preferred** when the total number of `toPrepare` items is small — the `toPrepare` list is generally smaller than the total list of expense claims.

## Key fields of the expenseClaim payable

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique ID of the expense claim |
| `bookkeepingStatus` | string | Accounting status: `toPrepare` \| `toExport` \| `exported` |
| `payableType` | string | `"expenseClaim"` |
| `memberId` | string | ID of the requesting employee (= `counterparty.memberId`) |
| `description` | string | Description of the expense |
| `amount` | {amount, currency, precision} | Total amount (integer coefficient, divide by 10^precision) |
| `spendingAmount` | {amount, currency, precision} | Amount in the original currency (may differ from `amount`) |
| `spendingCurrency` | string | Currency of the original expense (can be MAD, GBP, USD, etc.) |
| `functionalAmount` | {amount, currency, precision} | Equivalent in functional currency (EUR) |
| `itemLines[].analyticalFieldAssociations` | array | Assigned cost center + analytical fields |
| `allocations[].amount` | amount | Amount already reimbursed to the employee |
| `documentaryEvidence.validity.valid` | bool | Valid receipt |
| `creationDate` | ISO datetime | Date the expense was declared |
| `firstCreatedAt` | ISO datetime | Date of entry into Spendesk |

## ⚠️ Multi-currency case

An expense claim can be in a local currency (MAD, GBP, USD…):
- `spendingCurrency` = currency of the expense
- `currency` = `functionalCurrency` = EUR (generally)
- `spendingExchangeRate` = conversion rate applied
- Always use `functionalAmount` for EUR comparisons

Real example:
```json
{
  "currency": "EUR",
  "spendingCurrency": "MAD",
  "functionalExchangeRate": 1,
  "spendingExchangeRate": 10.8821,
  "amount": { "amount": 1213, "currency": "EUR", "precision": 2 },
  "spendingAmount": { "amount": 13200, "currency": "MAD", "precision": 2 }
}
// Expense of 132.00 MAD = 12.13 EUR
```

## ⚠️ allocations present even on toPrepare

`toPrepare` expense claims often have non-empty `allocations[]` — the reimbursement to the employee (payment) has already been made, but the item has not yet been validated for ERP export. Payment ≠ accounting export.

## Live example (real data, first 20 expense claims with no status filter)

Out of the first 20 `expenseClaim` items returned:
- 11 in `toPrepare` (to process)
- 9 in `exported` (already in accounting)
- `hasNextPage: true` → more exist

`toPrepare` examples:
| Description | Amount | Requester |
|-------------|---------|-----------|
| "Dinner" | 14.10 EUR | `__zal3grncttvu` |
| "Billet de train aller 08/01/2023" | 84.00 EUR | `-8zlmfu9gm8-ag` |
| "flight to Berlin Feb 21st 2022" | 248.67 EUR | `HJHszqYeW` |
| "Spendesk Connect 2022" | 69.00 EUR | `9a74l4w9ams5lv` |
| "Breakfast for Raji and I" | 12.13 EUR (= 132 MAD) | `-88mp0xaj8r_r_` |

## Example prompts

- "List expense claims pending review" → compound filter payableType=expenseClaim AND bookkeepingStatus=toPrepare
- "Which expense claims do I need to process before closing?" → bookkeepingStatus=toPrepare + post-filtering payableType=expenseClaim
- "Foreign-currency expense claims not yet exported" → expenseClaim + toPrepare + spendingCurrency != EUR
- "Total amount of pending expense claims" → sum(functionalAmount) on expenseClaim where bookkeepingStatus=toPrepare