openapi: 3.0.3
info:
  title: AIFAM Pay API v1
  version: 1.1.0
  description: API publica para cobranca PIX e saque PIX. A autenticacao oficial e por X-Api-Key, com compatibilidade para Authorization Bearer usando o mesmo token.
servers:
  - url: http://localhost/pay/api/v1
    description: Ambiente local com prefixo /pay
  - url: http://localhost/api/v1
    description: Ambiente local sem prefixo /pay
  - url: https://seu-dominio.com/api/v1
    description: Producao
tags:
  - name: Health
  - name: Charges
  - name: Withdrawals
paths:
  /ping:
    get:
      tags: [Health]
      summary: Healthcheck da API v1
      responses:
        "200":
          description: API online
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  timestamp:
                    type: string
                    format: date-time
                  versao:
                    type: string
                    example: v1
  /charges:
    post:
      tags: [Charges]
      summary: Criar cobranca PIX
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      parameters:
        - in: header
          name: X-Idempotency-Key
          required: false
          schema:
            type: string
          description: Chave opcional para evitar criacao duplicada de cobrancas.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChargeCreateRequest"
      responses:
        "201":
          description: Cobranca criada
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChargeResponse"
        "202":
          description: Requisicao idempotente ainda em processamento
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdempotencyProcessingResponse"
        "401":
          description: API key ausente ou invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Conflito de idempotencia
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Erro de validacao
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /charges/{id}:
    get:
      tags: [Charges]
      summary: Consultar cobranca PIX por ID
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Cobranca encontrada
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChargeResponse"
        "401":
          description: API key ausente ou invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Cobranca nao encontrada para o usuario autenticado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Falha ao sincronizar status com a infraestrutura de pagamento
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /withdrawals:
    post:
      tags: [Withdrawals]
      summary: Criar saque PIX
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      parameters:
        - in: header
          name: X-Idempotency-Key
          required: false
          schema:
            type: string
          description: Chave opcional para evitar criacao duplicada de saques.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WithdrawalCreateRequest"
      responses:
        "201":
          description: Saque criado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WithdrawalResponse"
        "202":
          description: Requisicao idempotente ainda em processamento
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdempotencyProcessingResponse"
        "401":
          description: API key ausente ou invalida
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: Conflito de idempotencia
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: Erro de validacao ou regra de negocio
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
  schemas:
    ChargeCreateRequest:
      type: object
      required:
        - valor
        - cliente
        - callback
      properties:
        valor:
          type: integer
          minimum: 1
          description: Valor em centavos. Ex. 2500 = R$ 25,00.
          example: 2500
        cliente:
          type: object
          description: Objeto do pagador. CPF deve ser valido com 11 digitos numericos; o backend remove pontuacao de CPF e telefone automaticamente.
          required:
            - nome
            - email
            - cpf
          properties:
            nome:
              type: string
              minLength: 3
              maxLength: 120
              example: Maria Souza
            email:
              type: string
              format: email
              maxLength: 160
              example: maria@email.com
            cpf:
              type: string
              pattern: "^[0-9]{11}$"
              example: "12345678909"
            telefone:
              type: string
              maxLength: 20
              nullable: true
              example: "11999999999"
        moeda:
          type: string
          enum: [BRL]
          default: BRL
        descricao:
          type: string
          maxLength: 255
          nullable: true
          example: Pedido #123
        callback:
          type: string
          format: uri
          maxLength: 255
          description: URL obrigatoria para callback da cobranca.
          example: https://sualoja.com/webhook/pagamento
        callback_secret:
          type: string
          minLength: 8
          maxLength: 255
          nullable: true
        metodos:
          type: array
          items:
            type: string
            enum: [pix]
          description: Atualmente apenas pix.
          example: [pix]
    WithdrawalCreateRequest:
      type: object
      required:
        - valor
        - pix_chave
        - pix_tipo
        - cliente
      properties:
        valor:
          type: integer
          minimum: 1
          description: Valor em centavos. Ex. 1000 = R$ 10,00.
          example: 1000
        pix_chave:
          type: string
          maxLength: 140
          example: "12345678909"
        pix_tipo:
          type: string
          enum: [cpf, cnpj, email, celular, aleatoria]
          description: Para celular, o backend converte e pode retornar telefone no status.
          example: cpf
        descricao:
          type: string
          maxLength: 255
          nullable: true
          example: Saque do cliente
        callback:
          type: string
          format: uri
          maxLength: 255
          nullable: true
          description: URL opcional para callback do saque.
        callback_secret:
          type: string
          minLength: 8
          maxLength: 255
          nullable: true
        cliente:
          type: object
          required:
            - nome
            - email
            - cpf
          properties:
            nome:
              type: string
              maxLength: 150
              example: Maria Souza
            email:
              type: string
              format: email
              maxLength: 160
              example: maria@email.com
            cpf:
              type: string
              pattern: "^[0-9]{11}$"
              example: "12345678909"
    ChargeResponse:
      type: object
      properties:
        id:
          type: integer
          example: 42
        status:
          type: string
          example: pendente
        valor:
          type: integer
          example: 2500
        moeda:
          type: string
          example: BRL
        metodo:
          type: string
          example: pix
        descricao:
          type: string
          example: Pedido #123
        cliente:
          type: object
          properties:
            nome: { type: string, example: Maria Souza }
            email: { type: string, example: maria@email.com }
            cpf: { type: string, example: "12345678909" }
        callback_url:
          type: string
          format: uri
          nullable: true
        idempotency:
          type: string
          nullable: true
        referencia:
          type: string
          example: ch_a1b2c3d4
        gateway:
          type: object
          properties:
            qr_code:
              type: string
            qr_code_url:
              type: string
              nullable: true
            expira_em:
              type: string
              nullable: true
              description: Data de expiracao gerada pela plataforma. Nao e um campo de entrada da API publica.
              example: "2026-12-31 23:59:59"
        criado_em:
          type: string
          nullable: true
          example: "2026-03-26 10:00:00"
        atualizado_em:
          type: string
          nullable: true
          example: "2026-03-26 10:00:00"
    WithdrawalResponse:
      type: object
      properties:
        id:
          type: integer
          example: 91
        status:
          type: string
          example: processando
        valor:
          type: integer
          example: 1000
        moeda:
          type: string
          example: BRL
        metodo:
          type: string
          example: pix
        tipo:
          type: string
          example: pix
        pix_chave:
          type: string
          example: "12345678909"
        pix_tipo:
          type: string
          description: Pode retornar telefone quando a entrada foi celular.
          example: cpf
        referencia:
          type: string
          example: wd_a1b2c3d4
        gateway:
          type: object
          properties:
            status:
              type: string
              example: PROCESSANDO
        cliente:
          type: object
          properties:
            nome: { type: string, example: Maria Souza }
            email: { type: string, example: maria@email.com }
            cpf: { type: string, example: "12345678909" }
        callback_url:
          type: string
          format: uri
          nullable: true
    IdempotencyProcessingResponse:
      type: object
      properties:
        mensagem:
          type: string
          example: Requisicao idempotente em processamento.
        idempotency:
          type: string
    ErrorResponse:
      type: object
      properties:
        mensagem:
          type: string
          example: API key invalida.