openapi: 3.0.4
info:
  title: Evolution Foundation - CRM Service - Notificame Channels
  description: |
    Endpoint for verifying Notificame channel credentials before connecting.

    Available starting `v1.0.0-rc3` (EVO-986). The endpoint had been hardened
    in this release: mandatory authentication, strict input validation, and
    no error leakage on failure paths.

    **Note:** This OpenAPI spec was generated from the controller as part of the rc3 release. Schemas reflect the controller surface but request/response examples may need refinement based on real payloads.
  version: 1.0.0
servers:
- url: https://api.evoai.app
- url: http://localhost:3000
paths:
  /api/v1/channels/notificame/verify:
    post:
      operationId: verify-notificame-channel
      summary: Verify Notificame Channel
      description: |
        Validates that the provided `api_token`, `channel_id` and
        `phone_number` correspond to a valid Notificame channel and that
        the phone number matches the channel registration.

        All three fields are required. Missing or blank values return
        `400 Bad Request`. Authentication is mandatory.
      security:
      - userApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [api_token, channel_id, phone_number]
              properties:
                api_token:
                  type: string
                  description: Notificame API token (will be trimmed)
                channel_id:
                  type: string
                  description: ID of the Notificame channel
                phone_number:
                  type: string
                  description: Phone number expected to match the channel registration (E.164 format)
              example:
                api_token: "nt_live_abc123..."
                channel_id: "ch_xyz789"
                phone_number: "+5511999999999"
      responses:
        '200':
          description: Channel verified — credentials and phone match
          content:
            application/json:
              schema:
                type: object
                required: [success, data, meta, message]
                properties:
                  success: { type: boolean, example: true }
                  data:
                    type: object
                    properties:
                      channel_id: { type: string }
                      verified: { type: boolean, example: true }
                  meta:
                    type: object
                    properties:
                      timestamp: { type: string, format: date-time }
                  message: { type: string }
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: false }
                  message: { type: string, example: "Missing required parameters: phone_number" }
                  details:
                    type: array
                    items: { type: string }
                    description: List of missing fields
        '401':
          description: Missing or invalid authentication
        '422':
          description: |
            Verification failed. Distinct reasons map to distinct responses
            but all use status 422 to avoid leaking which step failed:

            - Listing channels failed (provider error)
            - Channel not found by the provided channel_id
            - Phone number does not match the channel registration
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: false }
                  message: { type: string }

components:
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token