GAGA Game Server API (0.1)

First consumer: Funtap (VN) web top-up. The player pays on nap.funtap.games; Funtap calls the GAGA backend; the GAGA backend calls this API.

The same contract will be reused later for GAGA Web Shop direct delivery (other item types in items[]), so implement items as a list, not a single G Coin field.

Field names follow the Funtap S2S guide (v2.7) on purpose — server_id, server_name, account_id, role_id, role_name, os, invoice_id, product_id, created_at — so values pass through GAGA unchanged.

Every request carries two headers. Credentials are issued by GAGA, one pair per environment (staging and production never share a key).

Transport and network rules:

• HTTPS only (TLS 1.2+). Reject plain HTTP.
• IP allowlist: accept calls only from GAGA backend egress IPs (GAGA provides the list per environment). Required on production — POST /mails creates in-game value, and the API key alone is the only other control.
• Key rotation: GAGA sends a new key; the game server accepts both old and new for an agreed window, then drops the old one.
• Never log the full X-Api-Key.

Wrong or missing credentials → HTTP 401, code: 401. Source IP not allowed → HTTP 403, code: 403.

All responses are JSON:

{ "code": 200, "message": "OK", "data": { } }

• code is an integer and equals the HTTP status (200 on success). There is no code: 0.
• message is human-readable, English, for logs only. GAGA never parses it.
• data is present on success; it may be omitted on error.

invoice_id (GAGA's transaction id) is the idempotency key for POST /mails.

1. Store invoice_id with a unique constraint in the same transaction that creates the mail.
2. Same invoice_id + same payload again → do not send another mail; return 200 with the original mail_id and "duplicate": true.
3. Same invoice_id + different account_id / server_id / role_id / items → 409.
4. Keep invoice_id records for at least 90 days.

GAGA retry behaviour (so you know what to expect):

• Timeout: 10 s per call.
• On timeout, network error, 500 or 503: GAGA first calls GET /mails/{invoice_id}. If 200 → done. If 404 → GAGA re-sends POST /mails with the same invoice_id.
• Back-off: 30 s, 2 min, 10 min, 1 h, then every 6 h up to 72 h, then manual handling.

The game server provides two base URLs (staging and production), as Funtap requires separate test and live endpoints. Paths below are fixed; only the base URL changes.

1. Base URLs (staging, production).
2. G Coin item_id (and any other item_id GAGA may send), with max quantity per mail.
3. Mailbox expiry rule (how long an unclaimed mail stays) and attachment limit per mail.
4. A staging server with test accounts that have characters, for joint testing.

• GAGA SDK, game client changes, Google Play / App Store purchases.
• Funtap "check item condition" / "list item available" — answered by the GAGA backend, not the game server.
• Refund / item removal (to be agreed separately).

Lookups used while the player fills the Funtap top-up form.

Deliver purchased items to a character's mailbox, and check delivery status.