{"openapi":"3.0.3","info":{"title":"三千客 Gmail API","version":"0.4.0","description":"注册用户使用 API Key 申请 Gmail、查询验证码、申请下一码、退款和完成订单。"},"servers":[{"url":"https://gmail.sanqianke.xyz/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"gmp_live_*"}},"schemas":{"Product":{"type":"object","required":["id","name","domain","duration_hours","max_codes","price_cents","currency","available"],"properties":{"id":{"type":"string","example":"gmail_24h"},"name":{"type":"string"},"domain":{"type":"string","example":"gmail.com"},"duration_hours":{"type":"integer","example":24},"max_codes":{"type":"integer","example":3},"price_cents":{"type":"integer","description":"当前 API Key 所属注册用户的售价，单位为分"},"currency":{"type":"string","example":"CNY"},"available":{"type":"boolean"},"pricing_source":{"type":"string","enum":["DEFAULT","CUSTOM"]}}},"Mailbox":{"type":"object","required":["id","status","price_cents","currency","received_codes","max_codes","created_at","expires_at"],"properties":{"id":{"type":"string","example":"mbx_xxx"},"status":{"type":"string","enum":["ALLOCATING","ACTIVE","CODE_RECEIVED","WAITING_NEXT_CODE","COMPLETED","REFUNDED","CANCELED","FAILED","EXPIRED"]},"email":{"type":"string","format":"email","example":"example@gmail.com"},"price_cents":{"type":"integer","description":"下单时采用的注册用户售价，单位为分"},"currency":{"type":"string","example":"CNY"},"received_codes":{"type":"integer","example":0},"max_codes":{"type":"integer","example":3},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"error_message":{"type":"string"}}},"VerificationCode":{"type":"object","required":["sequence","code","received_at"],"properties":{"sequence":{"type":"integer","minimum":1,"example":1},"code":{"type":"string","example":"482913"},"received_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","example":"INSUFFICIENT_BALANCE"},"message":{"type":"string","example":"账户余额不足"},"request_id":{"type":"string","example":"req_xxx"}}}}}},"parameters":{"MailboxId":{"in":"path","name":"mailbox_id","required":true,"description":"创建邮箱时返回的 mailbox.id","schema":{"type":"string","pattern":"^mbx_[A-Za-z0-9]+$"}}},"responses":{"MailboxResponse":{"description":"订单状态","content":{"application/json":{"schema":{"type":"object","properties":{"mailbox":{"$ref":"#/components/schemas/Mailbox"}}}}}},"NotFound":{"description":"订单不存在或不属于当前 API Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/product":{"get":{"summary":"查询商品","operationId":"getProduct","responses":{"200":{"description":"实时商品配置","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"description":"API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balance":{"get":{"summary":"查询账户余额","operationId":"getBalance","responses":{"200":{"description":"余额","content":{"application/json":{"schema":{"type":"object","properties":{"balance_cents":{"type":"integer","example":1000},"frozen_balance_cents":{"type":"integer","example":0},"currency":{"type":"string","example":"CNY"}}}}}}}}},"/mailboxes":{"post":{"summary":"申请 Gmail","operationId":"createMailbox","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":200,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"client_reference":{"type":"string","maxLength":120}}}}}},"responses":{"201":{"description":"邮箱已分配并完成账户扣款","content":{"application/json":{"schema":{"type":"object","properties":{"mailbox":{"$ref":"#/components/schemas/Mailbox"}}}}}},"400":{"description":"请求或幂等键错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"余额或 Key 消费限额不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"幂等冲突","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"售卖暂停或上游分配失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mailboxes/{mailbox_id}":{"get":{"summary":"查询订单详情","operationId":"getMailbox","parameters":[{"$ref":"#/components/parameters/MailboxId"}],"responses":{"200":{"$ref":"#/components/responses/MailboxResponse"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/mailboxes/{mailbox_id}/codes":{"get":{"summary":"查询验证码","operationId":"getMailboxCodes","parameters":[{"$ref":"#/components/parameters/MailboxId"}],"responses":{"200":{"description":"当前订单及已收到的验证码","content":{"application/json":{"schema":{"type":"object","properties":{"mailbox":{"$ref":"#/components/schemas/Mailbox"},"items":{"type":"array","items":{"$ref":"#/components/schemas/VerificationCode"}},"poll_after_seconds":{"type":"integer","example":5}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/mailboxes/{mailbox_id}/next-code":{"post":{"summary":"申请下一码","operationId":"requestNextCode","parameters":[{"$ref":"#/components/parameters/MailboxId"}],"responses":{"200":{"$ref":"#/components/responses/MailboxResponse"},"409":{"description":"首码尚未收到、订单已结束或已达到三条","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mailboxes/{mailbox_id}/cancel":{"post":{"summary":"无码取消并退款","operationId":"cancelMailbox","parameters":[{"$ref":"#/components/parameters/MailboxId"}],"responses":{"200":{"$ref":"#/components/responses/MailboxResponse"},"409":{"description":"验证码已交付或订单已结束","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mailboxes/{mailbox_id}/complete":{"post":{"summary":"完成订单","operationId":"completeMailbox","parameters":[{"$ref":"#/components/parameters/MailboxId"}],"responses":{"200":{"$ref":"#/components/responses/MailboxResponse"},"409":{"description":"尚未收到验证码或订单已结束","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}