openapi: 3.0.3
info:
  title: Enkurta API
  version: "1.0"
  description: |
    API REST v1 para gestão de links. Autenticação via header `Authorization: Bearer <api_key>`.

    **Produção** (`/api/v1/...`): exige plano com integração API (flag `api` no catálogo, p. ex. Escala).

    **Sandbox** (`/api/sandbox/v1/...`): mesmos endpoints de links e mesma chave; não exige a flag `api`.
    Continua a aplicar-se `PlanEntitlementService` (quotas, Smart OG, etc.). As respostas incluem o cabeçalho `X-Enkurta-Api-Mode: sandbox`.

    Nos paths abaixo que começam por `/api/v1`, substitua o prefixo por `/api/sandbox/v1` para o sandbox.
servers:
  - url: https://{host}
    variables:
      host:
        default: enkurta.io
    description: |
      Paths de links documentados sob `/api/v1`. Para sandbox, use `/api/sandbox/v1` com o mesmo sufixo (ex.: `/api/sandbox/v1/links`).
paths:
  /health:
    get:
      summary: Health check
      responses:
        "200":
          description: OK ou degradado
  /api/v1/links:
    get:
      summary: Lista links do projeto
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: per_page
          schema: { type: integer, default: 20, maximum: 100 }
      responses:
        "200":
          description: Página de links
    post:
      summary: Cria link
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [destination_url]
              properties:
                destination_url: { type: string, format: uri }
                slug: { type: string, nullable: true }
                smart_og_enabled: { type: boolean }
                redirect_status: { type: integer, enum: [301, 302] }
      responses:
        "201": { description: Criado }
        "422": { description: Validação }
  /api/v1/links/{slug}:
    get:
      summary: Detalhe e total de cliques
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: slug
          required: true
          schema: { type: string }
      responses:
        "200": { description: OK }
        "404": { description: Não encontrado }
    put:
      summary: Atualiza destino
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: slug
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [destination_url]
              properties:
                destination_url: { type: string, format: uri }
                redirect_status: { type: integer, enum: [301, 302], nullable: true }
      responses:
        "200": { description: Atualizado }
    delete:
      summary: Remove link (soft delete)
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: slug
          required: true
          schema: { type: string }
      responses:
        "200": { description: Removido }
  /api/v1/links/{slug}/analytics:
    get:
      summary: Cliques agregados por dia
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: slug
          required: true
          schema: { type: string }
        - in: query
          name: days
          schema: { type: integer, default: 30, maximum: 366 }
      responses:
        "200":
          description: Série clicks_by_day
        "404": { description: Não encontrado }
  /api/v1/links/{slug}/analytics/summary:
    get:
      summary: Resumo (referrers, dispositivo, hora, país)
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: slug
          required: true
          schema: { type: string }
        - in: query
          name: days
          schema: { type: integer, default: 30, maximum: 366 }
        - in: query
          name: include_bots
          schema: { type: string, enum: ["0", "1", "true", "false"] }
      responses:
        "200": { description: Agregados }
        "404": { description: Não encontrado }
  /api/v1/ai/enrich:
    post:
      summary: Sugestões de enriquecimento (IA) para URL
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url: { type: string, format: uri }
      responses:
        "200": { description: OK }
        "502": { description: Falha upstream }
  /api/v1/webhooks/stripe:
    post:
      summary: Webhook Stripe (assinatura obrigatória; eventos incl. invoice.paid)
      responses:
        "200": { description: received }
        "400": { description: Erro de validação }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
