openapi: 3.0.3
info:
  title: SpinBank API (Cliente)
  version: 1.0.0
  description: Documentação dos endpoints para clientes (sem rotas administrativas).
servers:
  - url: http://localhost:8088
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
tags:
  - name: Cobranças
    description: Operações de criação e consulta de cobranças (Pix In)
  - name: Pagamentos
    description: Operações de criação, aprovação e consulta de pagamentos (Pix Out)
  - name: Transações
    description: Consulta de transações do cliente autenticado
x-tagGroups:
  - name: Cliente
    tags: [Cobranças, Pagamentos, Transações]
paths:
  /v1/charge:
    post:
      tags: [Cobranças]
      summary: Criar cobrança (Pix In)
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                value: { type: integer, example: 1000 }
                correlationID: { type: string, example: order-123 }
                customer:
                  type: object
                  properties:
                    name: { type: string, example: Cliente Teste }
                    taxID: { type: string, example: '00000000000' }
      responses:
        '201':
          description: Criado
  /v1/charge/{id}:
    get:
      tags: [Cobranças]
      summary: Consultar cobrança
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        '200': { description: OK }
  /v1/payment:
    post:
      tags: [Pagamentos]
      summary: Criar pagamento (PIX_KEY)
      description: Valida subconta e pode aprovar automaticamente conforme configuração.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type: { type: string, example: PIX_KEY }
                value: { type: integer, example: 1000 }
                destinationAlias: { type: string, example: '+5511888888888' }
                destinationAliasType: { type: string, enum: [CPF, CNPJ, EMAIL, PHONE, RANDOM], example: PHONE }
                correlationID: { type: string, example: payout-123 }
      responses:
        '201': { description: Criado }
  /v1/payment/{id}:
    get:
      tags: [Pagamentos]
      summary: Consultar pagamento
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        '200': { description: OK }
  /v1/payment/approve:
    post:
      tags: [Pagamentos]
      summary: Aprovar pagamento
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [correlationID]
              properties:
                correlationID: { type: string }
      responses:
        '200': { description: OK }
  /v1/transactions:
    get:
      tags: [Transações]
      summary: Listar transações do cliente autenticado
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: type
          schema: { type: string, enum: [IN, OUT] }
        - in: query
          name: status
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, default: 50 }
        - in: query
          name: offset
          schema: { type: integer, default: 0 }
      responses:
        '200': { description: OK }



