🤝 API Reference: Association & Tontine Service (association-service)

The association-service microservice exposes the full set of REST endpoints required to manage the lifecycle of tontines, group contributions, governance, and association treasuries.

🔑 Authentication & Header Security

All API requests require the following HTTP headers:

Authorization: Bearer <access_token>
Content-Type: application/json

For sensitive endpoints requiring PIN verification, the pin field in the JSON body MUST contain the RSA-OAEP encrypted string generated by the frontend.

📋 Core API Endpoints

1. Associations & Member Management

POST /association-service/api/v1/associations

Creates a new association workspace.

Request Body:

{
  "name": "United Friends Tontine",
  "description": "Monthly rotary tontine",
  "type": "tontine",
  "currency": "XOF",
  "contribution_amount": 10000,
  "contribution_frequency": "monthly",
  "max_members": 20,
  "is_public": true
}

GET /association-service/api/v1/associations/my

Retrieves associations joined by the authenticated user.

GET /association-service/api/v1/associations/:id/members

Retrieves association member list and assigned roles (president, treasurer, secretary, member).

2. Meetings & Meeting Contributions

POST /association-service/api/v1/associations/:id/meetings/:meeting_id/contribute

Submits a meeting contribution.

Request Body:

{
  "wallet_id": "w_12345",
  "amount": 10000,
  "pin": "BASE64_RSA_ENCRYPTED_PIN"
}

POST /association-service/api/v1/associations/:id/meetings/:meeting_id/settle

Settles a meeting and redistributes pool funds (Restricted to board admins/treasurers).

3. Treasury & Physical Cash Contributions

POST /association-service/api/v1/associations/:id/cash-contribution

Records a physical cash deposit into the association cash ledger.

Request Body:

{
  "member_id": "mem_987",
  "amount": 25000,
  "reason": "Physical cash contribution",
  "pin": "BASE64_RSA_ENCRYPTED_PIN"
}

POST /association-service/api/v1/associations/:id/distributions

Requests a treasury distribution to a beneficiary member.

4. Governance & Elections

POST /association-service/api/v1/associations/:id/governance/approve

Approves a governance proposal or cash deposit by a board executive.

Request Body:

{
  "approval_id": "gov_555",
  "pin": "BASE64_RSA_ENCRYPTED_PIN"
}