## Conventions
- Base URL: {url}
- Auth: Bearer token in Authorization header (see Authentication)
- Versioning: v1
- Placeholders:
- {url}: base API origin
- {access_token}: token from token generation endpoint
- {member_id}: unique member identifier (e.g., gr_70001)
- {amount}: positive integer hearts to credit or debit
- {reason}: short audit text
- {bit_id}: client correlation ID for the request
- {server_bit_id}: server authoritative transaction ID
- {new_balance}: integer balance after operation
- {occurred_at_iso8601}: UTC timestampx, e.g., 2025-09-04T12:00:00Z

## Authentication – Generate Token
- Method: POST
- URL: {url}/cdn/v1/generate/token
- Body: none
- Required headers:
- client_id: {client_id}
- oneapp_token: {oneapp_token}

#### cURL

curl -X POST '{url}/cdn/v1/generate/token' \
  -H 'client_id: {client_id}' \
  -H 'oneapp_token: {oneapp_token}'

#### Success response

{
  "access_token": "{access_token}",
  "expires_in": {expires_in_seconds},
  "refresh_expires_in": {refresh_expires_in_seconds},
  "refresh_token": {refresh_token_or_null},
  "token_type": "{token_type}",
  "id_token": "{id_token}",
  "not-before-policy": {not_before_epoch_seconds},
  "session_state": {session_state_or_null},
  "scope": "{scope}"
}

#### Status codes
| HTTP | Meaning |
|---|---|
| 200 | Token issued; use access_token until expires_in |
| 400 | Missing/invalid headers (client_id/oneapp_token) |
| 401 | Invalid credentials |
| 403 | Client recognized but not permitted to generate tokens |
| 429 | Rate limited |
| 500 | Server error |

## Balance Check
- Method: GET
- URL: {url}/v1/members/{member_id}/balances
- Required headers:
- Authorization: Bearer {access_token}
- Content-Type: application/json

#### cURL

curl -X GET '{url}/v1/members/{member_id}/balances' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json'

#### Success response

{
  "success": true,
  "message": "Balance retrieved.",
  "data": {
    "memberId": "{member_id}",
    "balances": {
      "hearts": {hearts_balance}
    }
  }
}

#### Error response (example)

{
  "success": false,
  "error": {
    "code": "MEMBER_NOT_FOUND",
    "httpStatus": 404,
    "message": "Member not found."
  }
}

#### Status codes
| HTTP | Meaning |
|---|---|
| 200 | Balance returned |
| 400 | Bad path parameter (member_id) |
| 401 | Missing/invalid Authorization |
| 404 | Member not found |
| 500 | Server error |

## Give Hearts (Credit)
- Method: POST
- URL: {url}/v1/hearts/credits
- Required headers:
- Authorization: Bearer {access_token}
- Content-Type: application/json
- Request body:
- memberId: {member_id}
- amount: {amount} (positive integer)
- reason: {reason}
- bitId: {bit_id}
- metadata: optional object (e.g., {"source":"{source}"})

#### cURL

curl -X POST '{url}/v1/hearts/credits' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "memberId": "{member_id}",
    "amount": {amount},
    "reason": "{reason}",
    "bitId": "{bit_id}",
    "metadata": { "source": "{source}" }
  }'

#### Success response

{
  "success": true,
  "message": "Hearts credited.",
  "data": {
    "bitId": "{server_bit_id}",
    "memberId": "{member_id}",
    "transaction": {
      "type": "credit",
      "amount": {amount},
      "heartsAdded": {amount},
      "heartsDeducted": 0,
      "newBalance": {new_balance},
      "occurredAt": "{occurred_at_iso8601}"
    }
  }
}

#### Error response (examples)
- Validation

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "httpStatus": 400,
    "message": "amount must be a positive integer."
  }
}

- Authorization

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "httpStatus": 401,
    "message": "Missing or invalid token."
  }
}

#### Status codes
| HTTP | Meaning |
|---|---|
| 200 | Credit applied |
| 400 | Validation error (e.g., amount <= 0, malformed JSON) |
| 401 | Missing/invalid Authorization |
| 404 | Member not found |
| 500 | Server error |

## Deduct Hearts (Debit)
- Method: POST
- URL: {url}/v1/hearts/debits
- Required headers:
- Authorization: Bearer {access_token}
- Content-Type: application/json
- Request body:
- memberId: {member_id}
- amount: {amount} (positive integer; must be <= available balance)
- reason: {reason}
- bitId: {bit_id}
- metadata: optional object (e.g., {"source":"{source}"})

#### cURL

curl -X POST '{url}/v1/hearts/debits' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "memberId": "{member_id}",
    "amount": {amount},
    "reason": "{reason}",
    "bitId": "{bit_id}",
    "metadata": { "source": "{source}" }
  }'

#### Success response

{
  "success": true,
  "message": "Hearts debited.",
  "data": {
    "bitId": "{server_bit_id}",
    "memberId": "{member_id}",
    "transaction": {
      "type": "debit",
      "amount": {amount},
      "heartsAdded": 0,
      "heartsDeducted": {amount},
      "newBalance": {new_balance},
      "occurredAt": "{occurred_at_iso8601}"
    }
  }
}

#### Error response (examples)
- Business rule

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "httpStatus": 400,
    "message": "Insufficient balance."
  }
}

- Validation

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "httpStatus": 400,
    "message": "amount must be a positive integer."
  }
}

#### Status codes
| HTTP | Meaning |
|---|---|
| 200 | Debit applied |
| 400 | Validation/business error (e.g., insufficient balance) |
| 401 | Missing/invalid Authorization |
| 404 | Member not found |
| 500 | Server error |

### Validation Rules
- amount must be a positive integer for both credit and debit.
- Debit amount must not exceed current hearts balance.
- bitId is a client correlation ID; the server returns an authoritative bitId in data.bitId.
- memberId must identify an existing member.