openapi: 3.1.0
info:
  title: EKSP v1 — Provedor (Encantra Knowledge & Signals Protocol)
  version: "1.0"
  summary: Contrato que um provedor implementa para alimentar a Encantra com conhecimento e sinais de clientes.
  description: |
    Especificação normativa: spec-v1.md. Os schemas detalhados estão em schemas/*.json (JSON Schema 2020-12).
    A URL base é a raiz que serve /.well-known/encantra.json.
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    name: Encantra
    email: master@inspire4u.com.br
servers:
  - url: https://api.seuproduto.com/eksp
    description: Exemplo de URL base do provedor
security:
  - bearer: []
tags:
  - name: descoberta
  - name: conhecimento
  - name: clientes
  - name: operacao
paths:
  /.well-known/encantra.json:
    get:
      tags: [descoberta]
      summary: Manifesto do provedor
      security: []
      responses:
        "200":
          description: Manifesto
          content:
            application/json:
              schema: { $ref: "./schemas/manifest.schema.json" }
  /content:
    get:
      tags: [conhecimento]
      summary: Lista documentos (incremental)
      parameters:
        - $ref: "#/components/parameters/updatedSince"
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - { name: locale, in: query, schema: { type: string }, description: "Filtra por idioma (BCP 47)" }
      responses:
        "200":
          description: Página de documentos
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./schemas/list.schema.json"
                  - type: object
                    properties:
                      data: { type: array, items: { $ref: "./schemas/document.schema.json" } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /catalog:
    get:
      tags: [conhecimento]
      summary: Produtos, serviços e planos
      responses:
        "200":
          description: Catálogo
          content:
            application/json:
              schema: { $ref: "./schemas/catalog.schema.json" }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /customers:
    get:
      tags: [clientes]
      summary: Lista clientes (contas) com contatos
      parameters:
        - $ref: "#/components/parameters/updatedSince"
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: Página de clientes
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./schemas/list.schema.json"
                  - type: object
                    properties:
                      data: { type: array, items: { $ref: "./schemas/customer.schema.json" } }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /customers/{external_id}/context:
    get:
      tags: [clientes]
      summary: Contexto ao vivo do cliente (≤ 1,5 s)
      parameters:
        - { name: external_id, in: path, required: true, schema: { type: string } }
        - { name: user_external_id, in: query, schema: { type: string } }
      responses:
        "200":
          description: Contexto
          content:
            application/json:
              schema: { $ref: "./schemas/context.schema.json" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
  /usage:
    get:
      tags: [clientes]
      summary: Eventos de uso (incremental por occurred_at)
      parameters:
        - { name: since, in: query, schema: { type: string, format: date-time } }
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: Página de eventos
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./schemas/list.schema.json"
                  - type: object
                    properties:
                      data: { type: array, items: { $ref: "./schemas/usage-event.schema.json" } }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /status:
    get:
      tags: [operacao]
      summary: Status do serviço e incidentes
      responses:
        "200":
          description: Status
          content:
            application/json:
              schema: { $ref: "./schemas/status.schema.json" }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /actions:
    get:
      tags: [operacao]
      summary: Catálogo de ações executáveis com confirmação humana
      responses:
        "200":
          description: Ações
          content:
            application/json:
              schema: { $ref: "./schemas/actions.schema.json" }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /actions/{name}:
    post:
      tags: [operacao]
      summary: Executa uma ação
      parameters:
        - { name: name, in: path, required: true, schema: { type: string } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 80 } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [customer_external_id, input]
              properties:
                customer_external_id: { type: string }
                input: { type: object }
                requested_by:
                  type: object
                  properties: { name: { type: string }, email: { type: string, format: email } }
      responses:
        "200":
          description: Resultado
          content:
            application/json:
              schema: { $ref: "./schemas/action-result.schema.json" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Error" }
        "422": { $ref: "#/components/responses/Error" }
webhooks:
  eksp-push:
    post:
      summary: "Push do provedor para a Encantra: POST {encantra}/eksp/v1/push/{connector_uuid}"
      parameters:
        - name: X-EKSP-Signature
          in: header
          required: true
          description: "t=<unix>,v1=<hex(hmac_sha256(segredo, t + '.' + corpo))>"
          schema: { type: string }
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "./schemas/push-event.schema.json"
                - type: object
                  required: [events]
                  properties:
                    events: { type: array, maxItems: 500, items: { $ref: "./schemas/push-event.schema.json" } }
      responses:
        "202": { description: "Aceito: {data:{accepted, rejected[]}}" }
        "401": { description: Assinatura inválida ou expirada }
        "404": { description: Conector inexistente ou pausado }
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
  parameters:
    updatedSince: { name: updated_since, in: query, schema: { type: string, format: date-time } }
    cursor: { name: cursor, in: query, schema: { type: string }, description: Cursor opaco retornado em next_cursor }
    limit: { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 50 } }
  responses:
    Error:
      description: Erro
      content:
        application/json:
          schema: { $ref: "./schemas/error.schema.json" }
    BadRequest:
      description: Parâmetro ou cursor inválido
      content:
        application/json:
          schema: { $ref: "./schemas/error.schema.json" }
    Unauthorized:
      description: Token ausente ou inválido
      content:
        application/json:
          schema: { $ref: "./schemas/error.schema.json" }
    NotFound:
      description: Recurso inexistente
      content:
        application/json:
          schema: { $ref: "./schemas/error.schema.json" }
    RateLimited:
      description: Limite de taxa excedido (ver Retry-After)
      headers:
        Retry-After: { schema: { type: integer } }
      content:
        application/json:
          schema: { $ref: "./schemas/error.schema.json" }