paths:
  /api/v1/external/getDataToken:
    get:
      tags: [Canales Externos]
      summary: Obtener datos del token API
      description: Valida el apikey enviado y retorna la configuración de canal asociada en maclient_api.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: header
          name: apikey
          required: true
          schema:
            type: string
          description: Token API del canal externo.
      responses:
        '200':
          description: Datos del token obtenidos exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: true
                  result:
                    type: object
                    properties:
                      corigen_rel:
                        type: string
                        maxLength: 2
                        example: "99"
                      cci_rif:
                        type: number
                        example: 25221952
                      xcanal_venta:
                        type: string
                        maxLength: 50
                        example: "Canal Externo RCV"
                      cproductor:
                        type: number
                        example: 80080
                      ctipocanal:
                        type: string
                        maxLength: 1
                        example: "A"
                      ccanalalt:
                        type: integer
                        nullable: true
                        example: 99
                      cscanalalt:
                        type: integer
                        nullable: true
                        example: null
                      iestado:
                        type: string
                        maxLength: 1
                        example: "V"
                      csucur:
                        type: integer
                        example: 1
                      xuser:
                        type: string
                        maxLength: 20
                        example: "external_user"
                      xpass:
                        type: string
                        maxLength: 250
                        example: "********"
              example:
                status: true
                result:
                  corigen_rel: "99"
                  cci_rif: 25221952
                  xcanal_venta: "Canal Externo RCV"
                  cproductor: 80080
                  ctipocanal: "A"
                  ccanalalt: 99
                  cscanalalt: null
                  iestado: "V"
                  csucur: 1
                  xuser: "external_user"
                  xpass: "********"
        '401':
          description: API Key faltante o inválida
        '500':
          description: Error interno del servidor

  /api/v1/external/getCategoriasUso:
    post:
      tags: [Canales Externos]
      summary: Categorías de uso disponibles para un vehículo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoriasUsoRequest'
      responses:
        '200':
          description: Categorías disponibles
        '400':
          description: Parámetros inválidos
        '500':
          description: Error interno del servidor

  /api/v1/external/getCotizacionAuto:
    post:
      tags: [Canales Externos]
      summary: Cotización de una póliza de automóvil
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CotizacionAutoRequest'
      responses:
        '200':
          description: Cotización calculada
        '400':
          description: Parámetros inválidos
        '500':
          description: Error interno del servidor

  /api/v1/external/getCotizacionPerson:
    post:
      tags: [Canales Externos]
      summary: Cotización de póliza para personas
      description: Consulta de cotización de personas usando servicio de App y validación por apikey.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CotizacionPersonRequest'
      responses:
        '200':
          description: Cotización calculada
        '400':
          description: Parámetros inválidos
        '401':
          description: API Key faltante o inválida
        '500':
          description: Error interno del servidor

  /api/v1/external/payments/bancoActivo/find-mobile-pay:
    post:
      tags: [Canales Externos - Payments]
      summary: Buscar pago movil (Banco Activo/Meritop)
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalPaymentsFindMobilePayRequest'
      responses:
        '200':
          description: Consulta ejecutada exitosamente
          content:
            application/json:
              example:
                status: true
                data:
                  Refpk: "26052753"
                  NroReferencia: "130223"
                  BancoOrig: "0102"
                  BancoDest: "0104"
                  PhoneOrig: "04121234567"
                  PhoneDest: "04141234567"
                  Amount: 1500.25
                  FechaMovimiento: "2026-05-25"
                  HoraMovimiento: "18:58:33"
                  Descripcion: "Pago Meritop"
        '400':
          description: Parámetros inválidos
        '401':
          description: API Key faltante o inválida
        '500':
          description: Error interno del servidor

  /api/v1/external/payments/getBanks:
    get:
      tags: [Canales Externos - Payments]
      summary: Obtener bancos habilitados para pagos OTP
      security:
        - ApiKeyAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalPaymentsGetBanksRequest'
      responses:
        '200':
          description: Bancos obtenidos
          content:
            application/json:
              example:
                result:
                  - cbanco: "0001"
                    xbanco: "Banco Central de Venezuela"
                  - cbanco: "0104"
                    xbanco: "Venezolano de Crédito (BVC)"
                  - cbanco: "0105"
                    xbanco: "Banco Mercantil"
                status: true
        '401':
          description: API Key faltante o inválida
        '500':
          description: Error interno del servidor

  /api/v1/external/payments/requestOtp:
    post:
      tags: [Canales Externos - Payments]
      summary: Solicitar OTP para pago movil
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalPaymentsRequestOtpRequest'
      responses:
        '200':
          description: OTP solicitado exitosamente
          content:
            application/json:
              example:
                result: "Request Exitoso"
                status: true
        '400':
          description: Parámetros inválidos o error de negocio
        '401':
          description: API Key faltante o inválida
        '500':
          description: Error interno del servidor

  /api/v1/external/payments/transactionOtp:
    post:
      tags: [Canales Externos - Payments]
      summary: Ejecutar transacción OTP
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalPaymentsTransactionOtpRequest'
      responses:
        '200':
          description: Transacción procesada
          content:
            application/json:
              example:
                result:
                  operation_date: "2026-05-25T18:58:33.551000"
                  transaction_id: "6F6CF59D6ACD"
                  ref_ibp: "26052753"
                  status: "ACCP"
                  message: "Operación aceptada"
                  rejected_code: ""
                  rejected_message: ""
                status: true
        '400':
          description: Parámetros inválidos o error de negocio
        '401':
          description: API Key faltante o inválida
        '500':
          description: Error interno del servidor

  /api/v1/external/payments/getTransactionOtp:
    post:
      tags: [Canales Externos - Payments]
      summary: Consultar estado de transacción OTP
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalPaymentsGetTransactionOtpRequest'
      responses:
        '200':
          description: Estado de transacción obtenido
          content:
            application/json:
              example:
                result:
                  operation_date: "2026-05-25T18:58:33.551000"
                  transaction_id: "6F6CF59D6ACD"
                  ref_ibp: "26052753"
                  status: "ACCP"
                  message: "Operación aceptada"
                  rejected_code: ""
                  rejected_message: ""
                status: true
        '400':
          description: Parámetros inválidos o error de negocio
        '401':
          description: API Key faltante o inválida
        '500':
          description: Error interno del servidor

  /api/v1/external/validateEmissionPerson:
    post:
      tags: [Canales Externos]
      summary: Validar persona antes de emitir póliza
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateEmissionPersonRequest'
      responses:
        '200':
          description: Validación exitosa
        '400':
          description: Parámetros inválidos o validación fallida
        '500':
          description: Error interno del servidor

  /api/v1/external/validateEmissionAuto:
    post:
      tags: [Canales Externos]
      summary: Validar vehículo antes de emitir póliza
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateEmissionAutoRequest'
      responses:
        '200':
          description: Validación exitosa
        '400':
          description: Parámetros inválidos o validación fallida
        '500':
          description: Error interno del servidor

  /api/v1/external/createEmissionAuto:
    post:
      tags: [Canales Externos]
      summary: Emitir póliza de automóvil (RCV)
      description: Emite póliza mediante SP de pre-emisión de automóvil.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmissionAutoRequest'
      responses:
        '200':
          description: Póliza emitida exitosamente
        '400':
          description: Parámetros inválidos
        '401':
          description: API Key faltante o inválida
        '500':
          description: Error interno del servidor

  /api/v1/external/createEmissionPerson:
    post:
      tags: [Canales Externos]
      summary: Emitir póliza de personas
      description: Emite póliza de personas mediante SP de pre-emisión.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmissionPersonRequest'
      responses:
        '200':
          description: Póliza emitida exitosamente
        '400':
          description: Parámetros inválidos
        '401':
          description: API Key faltante o inválida
        '500':
          description: Error interno del servidor

  /api/v1/external/changes/changeClientData:
    post:
      tags: [Canales Externos]
      summary: Modificar datos del cliente
      description: Valida token API y actualiza datos del cliente.
      parameters:
        - in: header
          name: api-key
          schema:
            type: string
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/ChangeClientDataRequestNatural'
                - $ref: '#/components/schemas/ChangeClientDataRequestJuridica'
      responses:
        '200':
          description: Datos del cliente actualizados exitosamente
        '400':
          description: Error en la solicitud o validación
        '401':
          description: No autorizado - Clave API faltante o inválida
        '500':
          description: Error interno del servidor

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apikey
