# Samity360 API Guide

The current browser APIs use authenticated sessions, CSRF tokens, tenant middleware, feature middleware, and RBAC. The `api_tokens` table provides the foundation for stateless bearer-token APIs.

## Response format

Success:

```json
{
  "success": true,
  "message": "Collection posted successfully",
  "data": {}
}
```

Failure:

```json
{
  "success": false,
  "message": "Permission denied",
  "errors": {}
}
```

## Main endpoints

| Method | Endpoint | Permission |
|---|---|---|
| POST | `/login` | Guest |
| GET | `/api/dashboard/stats` | Authenticated |
| GET | `/api/members/search?q=` | `members.view` |
| GET | `/api/members/{id}` | `members.view` |
| POST | `/api/members` | `members.create` |
| POST | `/api/savings/accounts` | `savings.manage` |
| POST | `/api/loans/calculate` | `loans.view` |
| POST | `/api/loans` | `loans.apply` |
| POST | `/api/loans/{id}/approve` | `loans.approve` |
| POST | `/api/loans/{id}/disburse` | `loans.disburse` |
| POST | `/api/collections` | `collections.create` |
| GET | `/api/collections` | `collections.view` |
| POST | `/api/accounting/transactions` | `accounting.create` |
| POST | `/api/accounting/close-day` | `accounting.close` |
| GET | `/api/reports/summary?type=overview|members|savings|loans|collections|financial` | `reports.view` |
| GET | `/reports/export?type=...` | `reports.export` |
| GET | `/reports/pdf?type=...` | `reports.export` |
| GET | `/reports/print?type=...` | `reports.view` |
| POST | `/api/notifications/send` | `notifications.send` |
| POST | `/api/settings` | `settings.manage` plus visible/editable database flags |
| POST | `/api/developer/features` | `developer.access` |

## Collection payload

```json
{
  "member_id": 1,
  "collector_id": 4,
  "payment_method": "cash",
  "payment_reference": null,
  "notes": "Field collection",
  "savings": [
    {"account_id": 1, "amount": 500}
  ],
  "installments": [
    {"loan_id": 1, "schedule_id": 4, "amount": 4766.67}
  ]
}
```

The server ignores client-calculated balances and reloads every account, member, loan, and installment under a row lock in the current company.

## REST extension pattern

For public/mobile APIs, add a bearer-token middleware that hashes incoming tokens with SHA-256, checks `api_tokens`, enforces expiry/revocation, loads abilities, and establishes the token's `company_id`. Do not accept a company ID supplied by the client as the tenant source.