openapi: 3.1.0
info:
  title: API Click2Call
  version: 1.0.0
  description: API de mise en relation téléphonique d'un workspace Click2Call.
  contact: {email: support@click2call.app}
servers:
  - {url: 'https://api.click2call.app/v1', description: Production}
security:
  - bearerAuth: []
paths:
  /health:
    get:
      security: []
      operationId: getHealth
      responses:
        '200': {description: Service disponible}
  /workspace:
    get:
      operationId: getWorkspace
      responses:
        '200': {$ref: '#/components/responses/Workspace'}
        '401': {$ref: '#/components/responses/Error'}
  /agents:
    get:
      operationId: listAgents
      responses:
        '200': {description: Agents du workspace}
    post:
      operationId: createAgent
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AgentInput'}
      responses:
        '201': {description: Agent créé}
        '422': {$ref: '#/components/responses/Error'}
  /agents/{id}/verifications:
    post:
      operationId: startAgentVerification
      parameters: [{$ref: '#/components/parameters/Id'}]
      responses:
        '202': {description: Appel de vérification lancé}
  /agent-verifications/{id}/confirm:
    post:
      operationId: confirmAgentVerification
      parameters: [{$ref: '#/components/parameters/Id'}]
      responses:
        '200': {description: Numéro vérifié}
        '422': {$ref: '#/components/responses/Error'}
  /calls:
    get:
      operationId: listCalls
      responses:
        '200': {description: Historique des appels}
  /calls/{id}:
    get:
      operationId: getCall
      parameters: [{$ref: '#/components/parameters/Id'}]
      responses:
        '200': {description: Appel}
        '404': {$ref: '#/components/responses/Error'}
  /calls/{id}/cancel:
    post:
      operationId: cancelCall
      parameters: [{$ref: '#/components/parameters/Id'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      responses:
        '202': {description: Annulation demandée}
  /callback-leads:
    get:
      operationId: listCallbackLeads
      responses:
        '200': {description: Demandes de rappel}
  /webhook-endpoints:
    get:
      operationId: listWebhookEndpoints
      responses:
        '200': {description: Endpoints webhook}
    post:
      operationId: createWebhookEndpoint
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      responses:
        '201': {description: Endpoint créé}
  /widget/call-requests:
    post:
      security: []
      operationId: requestCall
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/WidgetRequest'}
      responses:
        '202': {description: Appel accepté}
        '422': {$ref: '#/components/responses/Error'}
  /widget/call-requests/{id}/status:
    get:
      security: []
      operationId: getWidgetCallStatus
      parameters: [{$ref: '#/components/parameters/Id'}]
      responses:
        '200': {description: Statut courant}
  /widget/callback-leads:
    post:
      security: []
      operationId: requestCallback
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      responses:
        '201': {description: Demande enregistrée}
components:
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer}
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema: {type: string, pattern: '^[0-9A-HJKMNP-TV-Z]{26}$'}
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema: {type: string, maxLength: 128}
  schemas:
    Workspace:
      type: object
      required: [id, name, public_key, allowed_origins, timezone]
      properties:
        id: {type: string}
        name: {type: string}
        public_key: {type: string, pattern: '^c2c_pub_'}
        allowed_origins: {type: array, items: {type: string, format: uri}}
        timezone: {type: string, example: Europe/Paris}
        call_order: {type: string, enum: [agent_first, visitor_first, simultaneous]}
        routing_strategy: {type: string, enum: [round_robin, priority, simultaneous_agents]}
    AgentInput:
      type: object
      required: [name, phone]
      properties:
        name: {type: string, maxLength: 120}
        phone: {type: string, example: '+33612345678'}
        priority: {type: integer, minimum: 0}
    WidgetRequest:
      type: object
      required: [workspace_key, phone, consent]
      properties:
        workspace_key: {type: string, pattern: '^c2c_pub_'}
        phone: {type: string, example: '+33612345678'}
        name: {type: [string, 'null']}
        consent: {type: boolean, const: true}
        page_url: {type: [string, 'null'], format: uri}
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code: {type: string}
            message: {type: string}
  responses:
    Workspace:
      description: Configuration du workspace
      content:
        application/json:
          schema:
            type: object
            properties:
              data: {$ref: '#/components/schemas/Workspace'}
    Error:
      description: Erreur structurée
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
