openapi: 3.1.0
info:
  title: Notreve Pay — API pública
  version: 3.0.0
  summary: Pagamentos, subcontas e movimentações PIX
  description: |
    Bem-vindo à API pública da Notreve Pay.

    Use esta API para integrar sua plataforma a contas BaaS, subcontas,
    chaves PIX, cobranças, pagamentos e extratos. Todas as rotas públicas
    estão versionadas em `/v3` e exigem uma chave de API no cabeçalho
    `Authorization: Bearer <sua-chave>`.

    ## Regras de integração
    - Datas usam ISO 8601 (`YYYY-MM-DD` ou `YYYY-MM-DDTHH:mm:ssZ`).
    - Listagens são paginadas e aceitam `page` e `per_page`.
    - Intervalos de relatório são limitados a no máximo 1 ano.
    - Nunca envie `client_secret` ou credenciais do provedor em respostas ou logs.
    - Rotas de painel, administração, sessão, migração, health interno e webhooks
      não fazem parte deste contrato e não são expostas nesta documentação.
  contact:
    name: Notreve Tecnologia
    url: https://notreve.com.br
    email: suporte@notreve.com.br
  license:
    name: Proprietary
servers:
  - url: https://api.pay.notreve.com.br/v3
    description: Produção
  - url: https://api-sandbox.pay.notreve.com.br/v3
    description: Sandbox
tags:
  - name: Subcontas
    description: Contas filhas e suas chaves PIX
  - name: PIX
    description: Cobranças e pagamentos instantâneos
  - name: Extrato
    description: Saldo e movimentações financeiras
  - name: Relatórios
    description: Totais agregados por período
  - name: Marca
    description: Dados públicos de identificação da marca
paths:
  /whitelabel:
    get:
      operationId: getPublicBrand
      summary: Obter identidade pública da marca
      tags: [Marca]
      security: []
      responses:
        '200':
          description: Configuração pública da marca
          content:
            application/json:
              schema: {$ref: '#/components/schemas/BrandConfig'}
        '500': {$ref: '#/components/responses/ServerError'}
  /subcontas:
    get:
      operationId: listSubaccounts
      summary: Listar subcontas
      tags: [Subcontas]
      parameters:
        - {$ref: '#/components/parameters/Page'}
        - {$ref: '#/components/parameters/PerPage'}
        - name: q
          in: query
          description: Busca por nome, documento ou identificador
          schema: {type: string, maxLength: 120}
      responses:
        '200':
          description: Lista paginada de subcontas
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PaginatedSubaccounts'}
        '401': {$ref: '#/components/responses/Unauthorized'}
    post:
      operationId: createSubaccount
      summary: Criar subconta com chave PIX
      tags: [Subcontas]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CreateSubaccount'}
      responses:
        '201':
          description: Subconta criada
          content:
            application/json:
              schema: {$ref: '#/components/schemas/SubaccountCreated'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '502': {$ref: '#/components/responses/ProviderError'}
  /subcontas/{id}/saldo:
    get:
      operationId: getSubaccountBalance
      summary: Consultar saldo da subconta
      tags: [Subcontas]
      parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
      responses:
        '200':
          description: Saldo atual
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Balance'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {$ref: '#/components/responses/NotFound'}
  /subcontas/{id}/pix-key/reset:
    post:
      operationId: resetPixKey
      summary: Resetar chave PIX
      tags: [Subcontas]
      parameters: [{name: id, in: path, required: true, schema: {type: string, format: uuid}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [pix_key_id]
              properties: {pix_key_id: {type: string, format: uuid}}
      responses:
        '200':
          description: Nova chave PIX criada
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PixKeyResponse'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '502': {$ref: '#/components/responses/ProviderError'}
  /pix/cobranca:
    post:
      operationId: createPixCharge
      summary: Criar cobrança PIX
      tags: [PIX]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CreateCharge'}
      responses:
        '201':
          description: Cobrança criada
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Charge'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '502': {$ref: '#/components/responses/ProviderError'}
  /pix/pagamento:
    post:
      operationId: createPixPayment
      summary: Realizar pagamento PIX
      tags: [PIX]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CreatePayment'}
      responses:
        '201':
          description: Pagamento criado
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Payment'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '502': {$ref: '#/components/responses/ProviderError'}
  /extrato:
    get:
      operationId: listStatement
      summary: Consultar extrato paginado
      tags: [Extrato]
      parameters:
        - {$ref: '#/components/parameters/DateFrom'}
        - {$ref: '#/components/parameters/DateTo'}
        - {$ref: '#/components/parameters/Page'}
        - {$ref: '#/components/parameters/PerPage'}
        - name: tipo
          in: query
          schema: {type: string, enum: [CASHIN, CASHOUT, TRANSFERENCIA, ESTORNO]}
      responses:
        '200':
          description: Movimentações paginadas
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PaginatedTransactions'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /relatorios/transacoes:
    get:
      operationId: transactionReport
      summary: Totais de transações por período
      tags: [Relatórios]
      parameters:
        - {$ref: '#/components/parameters/DateFrom'}
        - {$ref: '#/components/parameters/DateTo'}
        - name: agrupamento
          in: query
          schema: {type: string, enum: [dia, semana, mes], default: dia}
      responses:
        '200':
          description: Totais de cash-in, cash-out e transferências
          content:
            application/json:
              schema: {$ref: '#/components/schemas/TransactionReport'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401': {$ref: '#/components/responses/Unauthorized'}
components:
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Chave gerada no painel Notreve Pay.
  parameters:
    Page: {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
    PerPage: {name: per_page, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
    DateFrom: {name: dt_ini, in: query, required: true, description: Início inclusivo. O intervalo máximo é 365 dias., schema: {type: string, format: date}}
    DateTo: {name: dt_fim, in: query, required: true, description: Fim inclusivo. Deve ser maior ou igual a dt_ini., schema: {type: string, format: date}}
  responses:
    BadRequest: {description: Requisição inválida, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
    Unauthorized: {description: Chave ausente ou inválida, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
    NotFound: {description: Recurso não encontrado, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
    ProviderError: {description: Falha no provedor de pagamentos, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
    ServerError: {description: Erro interno, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
  schemas:
    Error: {type: object, required: [error], properties: {error: {type: string}, code: {type: string}, request_id: {type: string}}}
    BrandConfig: {type: object, properties: {app_name: {type: string}, trade_name: {type: string}, primary_color: {type: string, pattern: '^#[0-9A-Fa-f]{6}$'}, logo_url: {type: string, format: uri}, support_email: {type: string, format: email}}}
    CreateSubaccount: {type: object, required: [cliente_id, nome, documento, tipo_documento], properties: {cliente_id: {type: string}, nome: {type: string, minLength: 2}, documento: {type: string}, tipo_documento: {type: string, enum: [CPF, CNPJ]}, external_id: {type: string}}}
    SubaccountCreated: {type: object, properties: {wallet: {$ref: '#/components/schemas/Wallet'}, pix_key: {$ref: '#/components/schemas/PixKey'}}}
    Wallet: {type: object, properties: {account_id: {type: string}, agencia: {type: string}, conta: {type: string}, status: {type: string}}}
    PixKey: {type: object, properties: {id: {type: string}, chave: {type: string}, tipo: {type: string}, status: {type: string}}}
    PixKeyResponse: {type: object, properties: {message: {type: string}, pix_key: {$ref: '#/components/schemas/PixKey'}}}
    Balance: {type: object, properties: {wallet_id: {type: string}, saldo_centavos: {type: integer}, saldo: {type: number, format: double}}}
    CreateCharge: {type: object, required: [valor_centavos], properties: {valor_centavos: {type: integer, minimum: 1}, expiracao_segundos: {type: integer, minimum: 60}, descricao: {type: string}, wallet_id: {type: string}}}
    CreatePayment: {type: object, required: [valor_centavos, chave_pix], properties: {valor_centavos: {type: integer, minimum: 1}, chave_pix: {type: string}, descricao: {type: string}, wallet_id: {type: string}}}
    Charge: {type: object, properties: {id: {type: string}, status: {type: string}, valor_centavos: {type: integer}, pix_copia_cola: {type: string}}}
    Payment: {type: object, properties: {id: {type: string}, status: {type: string}, valor_centavos: {type: integer}}}
    Transaction: {type: object, properties: {id: {type: string}, tipo: {type: string}, canal: {type: string}, valor_centavos: {type: integer}, status: {type: string}, created_at: {type: string, format: date-time}}}
    PaginatedSubaccounts: {type: object, properties: {data: {type: array, items: {$ref: '#/components/schemas/Wallet'}}, page: {type: integer}, per_page: {type: integer}, pages: {type: integer}, total: {type: integer}}}
    PaginatedTransactions: {type: object, properties: {data: {type: array, items: {$ref: '#/components/schemas/Transaction'}}, page: {type: integer}, per_page: {type: integer}, pages: {type: integer}, total: {type: integer}}}
    TransactionReport: {type: object, properties: {periodo: {type: object}, total_transacoes: {type: integer}, cashin_centavos: {type: integer}, cashout_centavos: {type: integer}, transferencias_centavos: {type: integer}, serie: {type: array, items: {type: object}}}}
security:
  - apiKeyAuth: []
