{"openapi":"3.1.0","info":{"version":"0.0.1","title":"0Wallet External Operator API","description":"Operator-facing integration surface: one **inbound** dispatcher endpoint\n(us → operator, fire-and-forget) for player events.\n\n---\n\n## Inbound — `POST api/v1/external/{tenantId}`\n\nA single endpoint. The request body's `module` field selects which\nhandler runs; `accessToken` (also in the body, not a header) authenticates\nthe call as a Sanctum personal access token bound to an `ExternalOperator`.\nAll module-specific request and response fields use `camelCase`.\n\n| module | Purpose |\n|---|---|\n| `/user/manualAngPao` | Credit a manual bonus (ang pao) to a user's bonus wallet |\n| `/user/getAllUsers` | Search / list users |\n| `/transactions/getAllTransactions` | List deposit + withdrawal transactions |\n| `/transactions/getBetHistory` | List a user's bet history for a date range |\n\n---\n\n## Response envelope\n\nSuccess: `{ status: true, message, data, timestamps }`\nError: `{ status: false, message, code, timestamps }` (`errors` present for validation failures)\n\nThe `VerifyExternalAccess` middleware's own auth failures (401/403) are\nthe exception — they return `{ status, message, code }` with no\n`timestamps`/`data` key.\n"},"paths":{"/api/v1/external/{tenantId}":{"post":{"summary":"External operator command dispatcher","description":"One endpoint, many modules. Validation is two-layered: `ExternalApiRequest` always requires `module` + `accessToken`; each module's own FormRequest then adds its specific fields. An unknown `module` returns 422 before any field-level validation of the module-specific payload runs.\n","tags":["External / Inbound"],"parameters":[{"name":"tenantId","in":"path","required":true,"description":"Tenant identifier; resolves tenancy for this request.","schema":{"type":"string","example":"tenant_acme"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ManualAngPaoRequest"},{"$ref":"#/components/schemas/GetAllUsersRequest"},{"$ref":"#/components/schemas/GetAllTransactionsRequest"},{"$ref":"#/components/schemas/GetBetHistoryRequest"}],"discriminator":{"propertyName":"module","mapping":{"/user/manualAngPao":"#/components/schemas/ManualAngPaoRequest","/user/getAllUsers":"#/components/schemas/GetAllUsersRequest","/transactions/getAllTransactions":"#/components/schemas/GetAllTransactionsRequest","/transactions/getBetHistory":"#/components/schemas/GetBetHistoryRequest"}}},"examples":{"manualAngPao":{"summary":"Credit a manual bonus","value":{"module":"/user/manualAngPao","accessToken":"1|abcdef0123456789abcdef0123456789abcdef01","userId":"01JCHG2M8S2ABCDE0987654321","amount":50.0,"promotionId":"01JCHG2M8S2ABCDE1234567890"}},"getAllUsers":{"summary":"Search users","value":{"module":"/user/getAllUsers","accessToken":"1|abcdef0123456789abcdef0123456789abcdef01","name":"John","sortBy":"register","sortType":"DESC","includeBetInfo":true}},"getAllTransactions":{"summary":"List transactions","value":{"module":"/transactions/getAllTransactions","accessToken":"1|abcdef0123456789abcdef0123456789abcdef01","userId":"abc123","type":"DEPOSIT","pageIndex":1}},"getBetHistory":{"summary":"Get bet history","value":{"module":"/transactions/getBetHistory","accessToken":"1|abcdef0123456789abcdef0123456789abcdef01","userId":"abc123","sTime":"2026-06-01","eTime":"2026-06-18","pageIndex":1,"perPage":10}}}}}},"responses":{"200":{"description":"Module executed successfully. `data` shape depends on `module` (see examples).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"examples":{"manualAngPao":{"value":{"status":true,"message":null,"data":[],"timestamps":"2026-06-18T10:00:00.000000Z"}},"getAllUsers":{"value":{"status":true,"message":null,"data":{"users":[{"id":"01JCHG2M8S2ABCDE0987654321","username":"abc123","name":"John Doe","phone":"+60123456789","email":"john@example.com","status":"ACTIVE","registerDate":"2026-01-10T08:00:00.000000Z","lastLoginAt":"2026-06-17T09:00:00.000000Z","cash":"120.00","bankAccount":{"bankName":"Maybank","accountNumber":"1234567890","accountHolderName":"John Doe"},"referrer":null}],"totalPage":1,"totalCount":1,"currentPage":1},"timestamps":"2026-06-18T10:00:00.000000Z"}},"getAllTransactions":{"value":{"status":true,"message":null,"data":{"transactions":[{"id":"01JCHG2M8S2ABCDE1234567890","adminId":null,"type":"DEPOSIT","details":"{\"method\":\"Gateway\",\"bank\":\"Maybank\",\"amount\":200}","cash":"200.00","createdDateTime":"2026-06-18T02:48:10+00:00","processedDateTime":null,"endDateTime":"2026-06-18T02:50:00+00:00","status":"COMPLETED","bankId":1,"bank":{"id":1,"name":"Maybank"},"user":{"id":"01JCHG2M8S2ABCDE0987654321","username":"abc123","name":"John Doe"}}],"totalDeposit":"200.00","netDeposit":"200.00","totalCount":1,"totalAmount":"200.00","totalPage":1},"timestamps":"2026-06-18T10:00:00.000000Z"}},"getBetHistory":{"value":{"status":true,"message":null,"data":{"history":[{"betId":"BET-0001","gameCode":"SLOT001","gameName":"Fortune Tiger","betAmount":"10.00","payoutAmount":"0.00","winLoss":"-10.00","validTurnover":"10.00","betTime":"2026-06-18T03:00:00+00:00","settleTime":"2026-06-18T03:00:05+00:00","status":"SETTLED"}],"totalRecords":"1","totalPages":1,"currentPage":1,"pageSize":10,"stats":{"totalRound":"1","totalBetAmount":"10.00","totalPayoutAmount":"0.00","totalAmount":"10.00","totalResult":"-10.00"}},"timestamps":"2026-06-18T10:00:00.000000Z"}}}}}},"401":{"description":"Missing or invalid `accessToken`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"missingToken":{"value":{"status":false,"message":"Unauthorized","code":"MISSING_TOKEN"}},"invalidToken":{"value":{"status":false,"message":"Unauthorized","code":"INVALID_TOKEN"}}}}}},"403":{"description":"Operator deactivated, or caller IP not in the operator's allowlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"},"examples":{"inactive":{"value":{"status":false,"message":"Inactive","code":"INACTIVE"}},"ipNotAllowed":{"value":{"status":false,"message":"Forbidden","code":"IP_NOT_ALLOWED"}}}}}},"422":{"description":"Unknown `module`, or module-specific field validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknownModule":{"value":{"status":false,"message":"Unknown module: /user/doesNotExist","code":null,"timestamps":"2026-06-18T10:00:00.000000Z"}}}}}}}}}},"components":{"schemas":{"SuccessEnvelope":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","nullable":true,"example":null},"data":{"type":"object"},"timestamps":{"type":"string","format":"date-time"}}},"ErrorEnvelope":{"type":"object","properties":{"status":{"type":"boolean","example":false},"message":{"type":"string"},"code":{"type":"string","nullable":true},"errors":{"type":"object","nullable":true},"timestamps":{"type":"string","format":"date-time"}}},"AuthErrorResponse":{"type":"object","description":"Raised by VerifyExternalAccess before the response envelope trait is reached — no `timestamps`/`data` key.","properties":{"status":{"type":"boolean","example":false},"message":{"type":"string"},"code":{"type":"string","enum":["MISSING_TOKEN","INVALID_TOKEN","INACTIVE","IP_NOT_ALLOWED"]}}},"BaseRequest":{"type":"object","required":["module","accessToken"],"properties":{"module":{"type":"string"},"accessToken":{"type":"string","description":"Sanctum plaintext personal access token issued to the ExternalOperator (`{id}|{40-char-token}`).","example":"1|abcdef0123456789abcdef0123456789abcdef01"}}},"ManualAngPaoRequest":{"allOf":[{"$ref":"#/components/schemas/BaseRequest"},{"type":"object","required":["module","accessToken","userId","amount","promotionId"],"properties":{"module":{"type":"string","enum":["/user/manualAngPao"]},"userId":{"type":"string","description":"Must match an existing user's internal `id` (ULID) — not `member_id`.","example":"01JCHG2M8S2ABCDE0987654321"},"amount":{"type":"number","format":"float","minimum":0.01,"example":50.0},"promotionId":{"type":"string","description":"Must match an existing `promotions.id`.","example":"01JCHG2M8S2ABCDE1234567890"}}}]},"GetAllUsersRequest":{"allOf":[{"$ref":"#/components/schemas/BaseRequest"},{"type":"object","required":["module","accessToken"],"properties":{"module":{"type":"string","enum":["/user/getAllUsers"]},"id":{"type":"string","nullable":true,"description":"Filters by exact username."},"name":{"type":"string","nullable":true},"mobile":{"type":"string","nullable":true},"agent":{"type":"string","nullable":true,"description":"Matches referrer name/username."},"bank":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"enum":["ACTIVE","INACTIVE"]},"sortBy":{"type":"string","nullable":true,"enum":["register","login"]},"sortType":{"type":"string","nullable":true,"enum":["ASC","DESC"]},"includeBetInfo":{"type":"boolean","nullable":true},"pageIndex":{"type":"integer","minimum":1,"default":1},"perPage":{"type":"integer","minimum":1,"maximum":50,"default":10}}}]},"GetAllTransactionsRequest":{"allOf":[{"$ref":"#/components/schemas/BaseRequest"},{"type":"object","required":["module","accessToken"],"properties":{"module":{"type":"string","enum":["/transactions/getAllTransactions"]},"pageIndex":{"type":"integer","minimum":1,"default":1},"perPage":{"type":"integer","minimum":1,"maximum":50,"default":10},"sDate":{"type":"string","format":"date","nullable":true},"eDate":{"type":"string","format":"date","nullable":true},"userId":{"type":"string","nullable":true,"description":"Filters by the user's username."},"id":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"enum":["DEPOSIT","WITHDRAW"]},"status":{"type":"string","nullable":true,"enum":["COMPLETED","REJECTED","FAILED","EXPIRED","PROCESSING","PENDING"]}}}]},"GetBetHistoryRequest":{"allOf":[{"$ref":"#/components/schemas/BaseRequest"},{"type":"object","required":["module","accessToken","userId"],"properties":{"module":{"type":"string","enum":["/transactions/getBetHistory"]},"userId":{"type":"string","description":"The user's username.","example":"abc123"},"sTime":{"type":"string","format":"date","nullable":true,"example":"2026-06-01"},"eTime":{"type":"string","format":"date","nullable":true,"example":"2026-06-18"},"pageIndex":{"type":"integer","minimum":1,"default":1,"description":"1-based — matches the game service's page numbering directly, no shift applied."},"perPage":{"type":"integer","minimum":1,"maximum":50,"default":10}}}]}}}}