openapi: 3.0.1
info:
  license:
    name: Khipu Open Data API
    url: https://khipu.com
  title: Clave Única
  description: ''
  version: v1.0
servers:
  - url: https://api.khipu.com
    description: Production
security:
  - JWT: []
  - Api-Key: []
paths:
  /v1/cl/services/claveunica.cl/token:
    post:
      summary: Account Link
      description: >-
        Éste metodo conecta a la cuenta del usuario en **Clave Única**, el sitio
        de identidad digital ofrecido por el gobierno chileno, y retorna un
        token vinculado a esa cuenta que puede ser usado en operaciones futuras,
        incluyendo otros servicios que requieren autenticación Clave Única.
      operationId: fetchToken_1
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaveUnicaAuthCredential'
        required: true
      responses:
        '200':
          description: >-
            Operación exitosa. Retorna un objeto JSON con los datos solicitados
            en el campo `Data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponseOk'
        '400':
          description: Solicitud incorrecta
        '401':
          description: No autorizado - Credenciales inválidas o faltantes
        '404':
          description: No encontrado - Recurso no disponible
        '500':
          description: Error en el servicio remoto :(
components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
    Api-Key:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    ClaveUnicaAuthCredential:
      type: object
      description: >-
        Valores necesarios para autenticar al usuario en el sitio web de Clave
        Única,  el sitio de identidad digital ofrecido por el gobierno chileno.
      required:
        - Username
        - Password
      properties:
        Username:
          maxLength: 12
          minLength: 1
          type: string
          description: >-
            Identificación de usuario con acceso a la cuenta de Clave Única
            (RUN).
          example: 11.111.111-1
        Password:
          minLength: 7
          type: string
          description: Contraseña de la cuenta para el sitio web de Clave Única.
          example: wxyz1234!@#$
    error:
      type: object
      nullable: true
      description: >-
        Object with the error details, used when `Status=ERROR`. If `Status=OK`
        this field will be null. You can read a complete explanation of this
        object visiting [this link](https://docs.khipu.com/portal/en/errors/)
        Objeto con los detalles del error, utilizado cuando `Status=ERROR`. Si
        `Status=OK` este campo será nulo. Puede leer una explicación completa de
        este objeto visitando [este
        enlace](https://docs.khipu.com/portal/es/errors/)
      example: null
      properties:
        Code:
          type: string
          description: Código interno del sistema que identifica el error.
          example: E201
        Type:
          type: string
          enum:
            - RETRY_IMMEDIATELY
            - DO_NOT_RETRY
            - WAIT_4_HOURS_BEFORE_RETRY
            - RETRY_AFTER_NOTIFICATION
          description: >-
            Indica cómo tratar este código de error específico, en función del
            tipo de error.
          example: RETRY_IMMEDIATELY
        Description:
          type: string
          description: Descripción asociada al código de error.
          example: >-
            El servicio destino utilizado para la extracción de datos no se
            encuentra disponible.
    TokenResponseOk:
      type: object
      description: >-
        Object with the response from OpenData service for the token generation,
        that allows calling the services without the need to send the
        authentication credentials. If the token generation is successful, it
        will be placed in the `Data` element.
      required:
        - OperationId
        - Status
        - Data
        - AdditionalInformation
        - Error
        - LifeSpan
      properties:
        OperationId:
          maxLength: 36
          type: string
          description: Unique identifier of the operation.
          example: 6baf6c19-e485-463b-ae24-a821b025c8a4
        Status:
          type: string
          enum:
            - OK
          description: >-
            Operation status, "OK" meaning that the credentials were correct and
            the account link was generated.
          example: OK
        Data:
          type: object
          description: >-
            If the authentication challenge was successful, it includes the link
            for the account.
          required:
            - AccountLink
          properties:
            AccountLink:
              type: string
              description: Token generated to access the service account.
              example: >-
                dFyRCVYNM0aGb1LSR/0B8e+eSVr1Zf1xj9YHmMVoiZWk28XtWEyIxEbGXnr1EdvS+QBPzjweau7tbf5QlDv97IQ2jwfUB==
        AdditionalInformation:
          type: string
          description: >-
            This field can be used to display relevant information specific to
            the response, for instance indicating that the `Data` field is
            incomplete.
          example: null
          nullable: true
        Error:
          $ref: '#/components/schemas/error'
          nullable: true
        LifeSpan:
          type: string
          description: '`null` in sync requests.'
          example: null
          nullable: true
