openapi: 3.1.0
info:
  title: RISITECH API
  version: 1.0.0-draft
  description: |
    Contrato público de integração RISITECH. Estado: homologação.
    A disponibilidade de cada recurso depende da capacidade efetivamente homologada.
servers:
  - url: https://sandbox.api.risitech.com.br/v1
    description: Sandbox — endereço reservado, liberação controlada
  - url: https://api.risitech.com.br/v1
    description: Produção — não liberada até homologação
security:
  - bearerAuth: []
paths:
  /merchants:
    post:
      summary: Cadastrar estabelecimento
      operationId: createMerchant
      x-risitech-status: homologation
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '202':
          description: Cadastro aceito para processamento
        '400':
          $ref: '#/components/responses/ApiError'
        '401':
          $ref: '#/components/responses/ApiError'
        '409':
          $ref: '#/components/responses/ApiError'
  /merchants/{id}:
    get:
      summary: Consultar estabelecimento
      operationId: getMerchant
      x-risitech-status: homologation
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Estabelecimento encontrado
        '404':
          $ref: '#/components/responses/ApiError'
  /terminals:
    get:
      summary: Consultar terminais
      operationId: listTerminals
      x-risitech-status: homologation
      responses:
        '200':
          description: Lista de terminais no escopo autorizado
  /transactions:
    get:
      summary: Consultar transações confirmadas
      operationId: listTransactions
      x-risitech-status: provider-dependent
      responses:
        '200':
          description: Registros confirmados por infraestrutura homologada
  /receivables:
    get:
      summary: Consultar recebíveis
      operationId: listReceivables
      x-risitech-status: provider-dependent
      responses:
        '200':
          description: Agenda baseada em registros oficiais conciliados
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2 access token
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        format: uuid
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
  responses:
    ApiError:
      description: Erro padronizado RISITECH com request_id
x-risitech-environment-status:
  public_api: HOMOLOGATION
  sandbox_external_clients: CONTROLLED_ENABLEMENT
  production: NOT_RELEASED