openapi: 3.1.0
info:
  title: Beacon API
  version: 0.1.0
  description: >-
    OpenAPI parcial da Beacon para as áreas críticas de billing, stripe connect,
    webhooks, fiscal e observability.
servers:
  - url: https://api.beacon.pt
    description: Produção
  - url: https://staging-api.beacon.pt
    description: Staging
security:
  - bearerAuth: []
tags:
  - name: billing
    description: Checkout e subscrições
  - name: stripe-connect
    description: Onboarding Stripe Connect
  - name: webhooks
    description: Ingestão de eventos e replay
  - name: fiscal
    description: Operação fiscal e reconciliação
  - name: observability
    description: Health, métricas e alertas
paths:
  /v1/billing/subscription-checkouts:
    post:
      tags: [billing]
      summary: Cria sessão de checkout para subscrição
      responses:
        '200':
          description: Sessão criada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSessionResponse'
  /v1/connect/accounts/onboarding-links:
    post:
      tags: [stripe-connect]
      summary: Inicia onboarding Connect Standard
      responses:
        '200':
          description: URL de onboarding pronta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectStartResponse'
  /v1/webhooks/stripe:
    post:
      tags: [webhooks]
      summary: Recebe eventos Stripe gerais
      security: []
      responses:
        '200':
          description: Evento aceite para processamento assíncrono
  /v1/fiscal/overview:
    get:
      tags: [fiscal]
      summary: Resumo operacional fiscal
      responses:
        '200':
          description: Estado fiscal agregado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FiscalOverview'
  /v1/health:
    get:
      tags: [observability]
      summary: Estado global da plataforma
      security: []
      responses:
        '200':
          description: Beacon operacional
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CheckoutSessionResponse:
      type: object
      properties:
        checkoutSessionId:
          type: string
        checkoutUrl:
          type: string
          format: uri
      required: [checkoutSessionId, checkoutUrl]
    ConnectStartResponse:
      type: object
      properties:
        onboardingUrl:
          type: string
          format: uri
      required: [onboardingUrl]
    FiscalOverview:
      type: object
      properties:
        status:
          type: string
        pendingDocuments:
          type: integer
          minimum: 0
      required: [status, pendingDocuments]
    HealthResponse:
      type: object
      properties:
        ok:
          type: boolean
        timestamp:
          type: string
          format: date-time
      required: [ok, timestamp]
