Add claude-generated openapi spec
This commit is contained in:
415
openapi.yaml
Normal file
415
openapi.yaml
Normal file
@@ -0,0 +1,415 @@
|
|||||||
|
openapi: 3.1.0
|
||||||
|
info:
|
||||||
|
title: Payouts Service API
|
||||||
|
description: API for managing user registrations, authentication, and payouts via YooKassa.
|
||||||
|
version: 1.0.0
|
||||||
|
|
||||||
|
servers:
|
||||||
|
- url: /
|
||||||
|
|
||||||
|
tags:
|
||||||
|
- name: user
|
||||||
|
description: User registration and authentication
|
||||||
|
- name: payout
|
||||||
|
description: Payout operations
|
||||||
|
- name: system
|
||||||
|
description: Health and version endpoints
|
||||||
|
|
||||||
|
paths:
|
||||||
|
/api/v1/user/register:
|
||||||
|
post:
|
||||||
|
tags: [user]
|
||||||
|
summary: Register a new user
|
||||||
|
operationId: userRegister
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/UserRegisterRequest'
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: User created successfully
|
||||||
|
'400':
|
||||||
|
description: Invalid input (empty fields or password mismatch)
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'500':
|
||||||
|
description: Internal server error
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/api/v1/user/login:
|
||||||
|
post:
|
||||||
|
tags: [user]
|
||||||
|
summary: Authenticate a user and obtain a session token
|
||||||
|
operationId: userLogin
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/UserLoginRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Login successful
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/UserLoginResponse'
|
||||||
|
'400':
|
||||||
|
description: Invalid input (empty phone or password)
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'401':
|
||||||
|
description: Invalid credentials
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/api/v1/payout/sbp/banks:
|
||||||
|
get:
|
||||||
|
tags: [payout]
|
||||||
|
summary: Get list of SBP (Fast Payment System) banks
|
||||||
|
operationId: getSbpBanks
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: List of SBP banks
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/SBPBankListResponse'
|
||||||
|
'400':
|
||||||
|
description: Bad request (YooKassa API error)
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'500':
|
||||||
|
description: Internal server error
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/api/v1/payout/create:
|
||||||
|
post:
|
||||||
|
tags: [payout]
|
||||||
|
summary: Create a new payout
|
||||||
|
operationId: createPayout
|
||||||
|
security:
|
||||||
|
- bearerAuth: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/PayoutRequest'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Payout created successfully
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/PayoutResponse'
|
||||||
|
'400':
|
||||||
|
description: Invalid payout data
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'401':
|
||||||
|
description: Unauthorized (missing or invalid token)
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'500':
|
||||||
|
description: Internal server error
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/api/v1/payout/callback:
|
||||||
|
post:
|
||||||
|
tags: [payout]
|
||||||
|
summary: Receive payout status callback from YooKassa
|
||||||
|
description: |
|
||||||
|
Called by YooKassa to notify of payout status changes.
|
||||||
|
If IP validation is enabled, the request must originate from an allowed subnet.
|
||||||
|
Status updates are processed asynchronously.
|
||||||
|
operationId: payoutCallback
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/PayoutResponse'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Callback received and queued for processing
|
||||||
|
'400':
|
||||||
|
description: Invalid JSON payload
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'403':
|
||||||
|
description: Forbidden (IP address not in allowed subnets)
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/payout/widget:
|
||||||
|
get:
|
||||||
|
tags: [payout]
|
||||||
|
summary: Serve the payout widget HTML page
|
||||||
|
operationId: getPayoutWidget
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Widget HTML page
|
||||||
|
content:
|
||||||
|
text/html:
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
'500':
|
||||||
|
description: Template rendering error
|
||||||
|
|
||||||
|
/health:
|
||||||
|
get:
|
||||||
|
tags: [system]
|
||||||
|
summary: Health check
|
||||||
|
description: Verifies database connectivity.
|
||||||
|
operationId: healthCheck
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Service is healthy
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/HealthResponse'
|
||||||
|
'503':
|
||||||
|
description: Service unavailable (database connection failed)
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/HealthResponse'
|
||||||
|
|
||||||
|
/version:
|
||||||
|
get:
|
||||||
|
tags: [system]
|
||||||
|
summary: Get service version
|
||||||
|
operationId: getVersion
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Version string (optionally including git commit hash)
|
||||||
|
content:
|
||||||
|
text/plain:
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
example: v1.2.3
|
||||||
|
|
||||||
|
components:
|
||||||
|
securitySchemes:
|
||||||
|
bearerAuth:
|
||||||
|
type: http
|
||||||
|
scheme: bearer
|
||||||
|
description: UUID session token obtained from the login endpoint
|
||||||
|
|
||||||
|
schemas:
|
||||||
|
UserRegisterRequest:
|
||||||
|
type: object
|
||||||
|
required: [tin, phone, password, password_cfm]
|
||||||
|
properties:
|
||||||
|
tin:
|
||||||
|
type: string
|
||||||
|
description: Taxpayer Identification Number
|
||||||
|
example: "1234567890"
|
||||||
|
phone:
|
||||||
|
type: string
|
||||||
|
description: User phone number
|
||||||
|
example: "+79001234567"
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
format: password
|
||||||
|
description: User password
|
||||||
|
password_cfm:
|
||||||
|
type: string
|
||||||
|
format: password
|
||||||
|
description: Password confirmation (must match password)
|
||||||
|
|
||||||
|
UserLoginRequest:
|
||||||
|
type: object
|
||||||
|
required: [phone, password]
|
||||||
|
properties:
|
||||||
|
phone:
|
||||||
|
type: string
|
||||||
|
description: Registered phone number
|
||||||
|
example: "+79001234567"
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
format: password
|
||||||
|
|
||||||
|
UserLoginResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
description: Session token (UUID)
|
||||||
|
example: "550e8400-e29b-41d4-a716-446655440000"
|
||||||
|
token_ttl:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
description: Token expiration as Unix timestamp
|
||||||
|
example: 1711958400
|
||||||
|
|
||||||
|
SBPBankListResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
type:
|
||||||
|
type: string
|
||||||
|
example: "list"
|
||||||
|
items:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/SBPBank'
|
||||||
|
|
||||||
|
SBPBank:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
bank_id:
|
||||||
|
type: string
|
||||||
|
description: Bank identifier
|
||||||
|
example: "100000000111"
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
description: Human-readable bank name
|
||||||
|
example: "Sberbank"
|
||||||
|
bic:
|
||||||
|
type: string
|
||||||
|
description: Bank Identification Code
|
||||||
|
example: "044525225"
|
||||||
|
|
||||||
|
PayoutType:
|
||||||
|
type: string
|
||||||
|
enum: [spb, yoo_money, bank_card, widget]
|
||||||
|
description: |
|
||||||
|
Payout method:
|
||||||
|
- `spb` — Fast Payment System (SBP)
|
||||||
|
- `yoo_money` — YooMoney wallet
|
||||||
|
- `bank_card` — bank card
|
||||||
|
- `widget` — card via widget
|
||||||
|
|
||||||
|
PayoutRequest:
|
||||||
|
type: object
|
||||||
|
required: [payout_type, amount]
|
||||||
|
properties:
|
||||||
|
payout_type:
|
||||||
|
$ref: '#/components/schemas/PayoutType'
|
||||||
|
payout_token:
|
||||||
|
type: string
|
||||||
|
description: Payment token (used for widget/card payouts)
|
||||||
|
example: "pt_xxxxxxxxxxxxxxxxxxxx"
|
||||||
|
account_number:
|
||||||
|
type: string
|
||||||
|
description: Account/phone number for SBP or YooMoney payouts
|
||||||
|
example: "+79001234567"
|
||||||
|
bank_id:
|
||||||
|
type: string
|
||||||
|
description: Bank identifier (required for SBP payouts)
|
||||||
|
example: "100000000111"
|
||||||
|
card_number:
|
||||||
|
type: string
|
||||||
|
description: Card number (for bank_card payout type)
|
||||||
|
example: "4111111111111111"
|
||||||
|
amount:
|
||||||
|
type: number
|
||||||
|
format: float
|
||||||
|
description: Payout amount in RUB
|
||||||
|
example: 1000.00
|
||||||
|
|
||||||
|
PayoutStatus:
|
||||||
|
type: string
|
||||||
|
enum: [created, pending, succeeded, canceled, failed]
|
||||||
|
|
||||||
|
Amount:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
value:
|
||||||
|
type: string
|
||||||
|
description: Amount as a decimal string
|
||||||
|
example: "1000.00"
|
||||||
|
currency:
|
||||||
|
type: string
|
||||||
|
description: ISO 4217 currency code
|
||||||
|
example: "RUB"
|
||||||
|
|
||||||
|
PayoutDestination:
|
||||||
|
type: object
|
||||||
|
description: Payout destination details (structure depends on payout type)
|
||||||
|
additionalProperties: true
|
||||||
|
|
||||||
|
PayoutResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
description: YooKassa payout ID
|
||||||
|
example: "po_1da5c87d-0984-50e8-a7f3-8de646dd9ec9"
|
||||||
|
status:
|
||||||
|
$ref: '#/components/schemas/PayoutStatus'
|
||||||
|
amount:
|
||||||
|
$ref: '#/components/schemas/Amount'
|
||||||
|
payout_destination:
|
||||||
|
$ref: '#/components/schemas/PayoutDestination'
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
example: "Payout for order #42"
|
||||||
|
created_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
example: "2024-04-02T12:00:00Z"
|
||||||
|
succeeded_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
example: "2024-04-02T12:01:00Z"
|
||||||
|
metadata:
|
||||||
|
type: object
|
||||||
|
additionalProperties: true
|
||||||
|
description: Arbitrary key-value metadata
|
||||||
|
test:
|
||||||
|
type: boolean
|
||||||
|
description: Whether this is a test payout
|
||||||
|
example: false
|
||||||
|
|
||||||
|
HealthResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
OK:
|
||||||
|
type: boolean
|
||||||
|
description: Whether the service is healthy
|
||||||
|
Error:
|
||||||
|
type: string
|
||||||
|
description: Error message (only present when OK is false)
|
||||||
|
|
||||||
|
ErrorResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
status:
|
||||||
|
type: integer
|
||||||
|
description: HTTP status code
|
||||||
|
example: 400
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
description: Human-readable error message
|
||||||
|
example: "Bad Request"
|
||||||
Reference in New Issue
Block a user