swagger: '2.0'
info:
  description: 'This API lets you manage the subscriptions to API Hub asynchronous events. It enables you to receive notifications (asynchronous events) from Círculo de Crédito next-generation products (Open Banking & Data Aggregation).'
  version: '1.0.0'
  title: 'API Subscriptions Sandbox'
  termsOfService: 'https://developer.circulodecredito.com.mx/legal'
  contact:
    email: 'api@circulodecredito.com.mx'
host: 'services.circulodecredito.com.mx'
basePath: '/sandbox'
tags:
  - name: 'WebHook subscriptions'
    description: 'API WebHook Subscriptions'
    externalDocs:
      description: 'API Hub'
      url: 'https://developer.circulodecredito.com.mx/en/products/subscriptions'
schemes:
  - 'https'
parameters:
  x-api-key:
    in: 'header'
    name: 'x-api-key'
    description: 'The Consumer Key assigned to the client application you have registered in API Hub.'
    required: true
    type: 'string'
  x-webhook-jwt-auth:
    in: 'header'
    name: 'x-webhook-jwt-auth'
    description: 'Json Web Token that contains the username and password required to invoke your WebHook API published with Basic Authentication.'
    required: false
    type: 'string'
  subscriptionId:
    in: 'path'
    name: 'subscriptionId'
    description: 'Subscription identifier.'
    required: true
    type: 'string'
  page:
    in: 'query'
    name: 'page'
    description: 'Page to query.'
    required: false
    type: 'integer'
  perPage:
    in: 'query'
    name: 'perPage'
    description: 'Rows per page.'
    required: false
    type: 'integer'
paths:
  '/v1/subscriptions':
    parameters:
      - $ref: '#/parameters/x-api-key'
    post:
      summary: 'Enrolls you in a product subscription.'
      description: 'Creates a new subscription. You must provide the type of event you are interested in, the URL endpoint of your WebHook API and your enrollment identifier. Note: In the Sandbox Environment the subscriptions will be stored for a maximum period of 24 hours.'
      tags:
        - 'WebHook subscriptions'
      operationId: 'postSubscription'
      consumes:
        - 'application/json'
      produces:
        - 'application/json'
      parameters:
        - in: 'body'
          name: 'enrollment'
          description: 'Enrollment information'
          required: true
          schema:
            $ref: '#/definitions/Subscription'
        - $ref: '#/parameters/x-webhook-jwt-auth'
      responses:
        '200':
          description: 'OK - A new subscription was created.'
          schema:
            $ref: '#/definitions/SubscriptionAcknowledge'
        '400':
          description: 'Bad request.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "400"
                  message: "Missign parameters {x-api-key}."
        '401':
          description: 'Unauthorized.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: '401.1'
                  message: 'Unauthorized, invalid x-api-key.'
                - code: '401.2'
                  message: 'Unauthorized, invalid credentials.'
                - code: '401.3'
                  message: 'Unauthorized, you do not have access to the product'
                - code: '401.4'
                  message: 'Unauthorized, you do not have access to the resource.'
        '403':
          description: 'Forbidden.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: '403.1'
                  message: 'We could not verify the signature, x-signature is invalid.'
        '429':
          description: 'Too many requests.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "429"
                  message: "Too many requests."
        '500':
          description: "Internal server error."
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "500"
                  message: "There was an unexpected error, try again later."
        '503':
          description: "Service unavailable."
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "503"
                  message: "Service unavailable."
    get:
      summary: 'Returns a list of subscriptions you are enrolled in.'
      description: 'Returns a subscription list. The maximum number of returned rows is 20. You could use the {page} and {perPage} parameters in order to navigate through the list.'
      tags:
        - WebHook subscriptions
      operationId: getSubscriptions
      consumes:
        - 'application/json'
      produces:
        - 'application/json'
      parameters:
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/perPage'
      responses:
        '200':
          description: 'OK - Returns a subscription list.'
          schema:
            $ref: '#/definitions/SubscriptionsMetadata'
        '400':
          description: 'Bad request.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "400"
                  message: "Missign parameters {x-api-key}."
        '401':
          description: 'Unauthorized.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: '401.1'
                  message: 'Unauthorized, invalid x-api-key.'
                - code: '401.2'
                  message: 'Unauthorized, invalid credentials.'
                - code: '401.3'
                  message: 'Unauthorized, you do not have the product.'
                - code: '401.4'
                  message: 'Unauthorized, you do not have access to the resource.'
        '429':
          description: 'Too many requests.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "429"
                  message: "Too many requests."
        '500':
          description: "Internal server error."
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "500"
                  message: "There was an unexpected error, try again later."
        '503':
          description: "Service unavailable."
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "503"
                  message: "Service unavailable."
  '/v1/subscriptions/{subscriptionId}':
    parameters:
      - $ref: '#/parameters/x-api-key'
      - $ref: '#/parameters/subscriptionId'
    get:
      summary: 'Returns the subscription information.'
      description: 'Returns the subscription information identified by the {subscriptionId} path parameter.'
      tags:
        - 'WebHook subscriptions'
      operationId: 'getSubscription'
      consumes:
        - 'application/json'
      produces:
        - 'application/json'
      responses:
        '200':
          description: "OK - Returns the subscription information."
          schema:
            $ref: '#/definitions/Subscription'
        '400':
          description: 'Bad request.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "400"
                  message: "Missign parameters {x-api-key}."
        '401':
          description: 'Unauthorized.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: '401.1'
                  message: 'Unauthorized, invalid x-api-key.'
                - code: '401.2'
                  message: 'Unauthorized, invalid credentials.'
                - code: '401.3'
                  message: 'Unauthorized, you do not have the product.'
                - code: '401.4'
                  message: 'Unauthorized, you do not have access to the resource.'
        '404':
          description: 'Subscription not found.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "404.1"
                  message: "Subscription does not exist."
        '429':
          description: 'Too many requests.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "429"
                  message: "Too many requests."
        '500':
          description: "Internal server error."
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "500"
                  message: "There was an unexpected error, try again later."
        '503':
          description: "Service unavailable."
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "503"
                  message: "Service unavailable."
    delete:
      summary: 'Withdraws a subscription.'
      description: 'Withdraws the subscription identified by the {subscriptionId} path parameter.'
      tags:
        - 'WebHook subscriptions'
      operationId: 'deleteSubscription'
      consumes:
        - 'application/json'
      produces:
        - 'application/json'
      responses:
        '200':
          description: 'OK - You are not longer enrolled in.'
          schema:
            $ref: '#/definitions/SubscriptionAcknowledge'
          examples:
            application/json:
              acknowledgeId: 627aa72a-c799-4abf-b98e-0c4838af9bd5
              dateTime: '2020-04-12T22:20:50.52Z'
              operation: cancellation
              message: The subscription was canceled.
              subscription:
                eventType: mx.com.circulodecredito.eva
                webHookUrl: https://yourdomain.com/v1/notifications
                enrollmentId: 470987ab-b4cb-4a1e-9eaf-8856a813da59
                subscriptionId: 4fc07667-b928-4a5c-a9d4-e18d3d515d24
                dateTime: '2020-04-12T22:20:50.52Z'
        '400':
          description: 'Bad request.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "400"
                  message: "Missign parameters {x-api-key}."
        '401':
          description: 'Unauthorized.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: '401.1'
                  message: 'Unauthorized, invalid x-api-key.'
                - code: '401.2'
                  message: 'Unauthorized, invalid credentials.'
                - code: '401.3'
                  message: 'Unauthorized, you do not have the product.'
                - code: '401.4'
                  message: 'Unauthorized, you do not have access to the resource.'
        '404':
          description: 'Subscription not found.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "404.1"
                  message: "Subscription does not exist."
        '429':
          description: 'Too many requests.'
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "429"
                  message: "Too many requests."
        '500':
          description: "Internal server error."
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "500"
                  message: "There was an unexpected error, try again later."
        '503':
          description: "Service unavailable."
          schema:
            $ref: '#/definitions/Errors'
          examples:
            application/json:
              errors:
                - code: "503"
                  message: "Service unavailable."
definitions:
  Error:
    type: 'object'
    description: 'Error'
    readOnly: true
    properties:
      code:
        type: 'string'
        description: 'Error code.'
        example: '400'
      message:
        type: 'string'
        maxLength: 120
        description: 'Descriptive and human-readable error message.'
        example: 'External data source not available.'
  Errors:
    description: 'A list of errors.'
    type: 'object'
    properties:
      errors:
        description: 'List of errors.'
        type: 'array'
        items:
          $ref: '#/definitions/Error'
  Subscription:
    description: 'A product subscription.'
    type: 'object'
    required:
      - 'eventType'
      - 'webHookUrl'
      - 'enrollmentId'
    properties:
      eventType:
        description: 'Event type you are interested in.'
        type: 'string'
        maxLength: 50
        enum:
          - "mx.com.circulodecredito.ada"
          - "mx.com.circulodecredito.ada.pm"
          - "mx.com.circulodecredito.eva"
          - "mx.com.circulodecredito.eva.models"
          - "mx.com.circulodecredito.telcos"
          - "mx.com.circulodecredito.bavs"
          - "mx.com.circulodecredito.odc"
          - "mx.com.circulodecredito.sat"
          - "mx.com.circulodecredito.eva.iss"
          - "mx.com.circulodecredito.pav"
          - "mx.com.circulodecredito.idendata"
          - "mx.com.circulodecredito.unnax.eva"
          - "NA"
        example: 'mx.com.circulodecredito.eva'
      webHookUrl:
        description: 'The URL which will receive API Hub event notifications.'
        type: 'string'
        example: 'https://yourdomain.com/v1/notifications'
        maxLength: 100
      enrollmentId:
        type: 'string'
        format: 'uuid'
        minLength: 36
        maxLength: 36
        description: 'Your enrollment identifier to associate with the subscription identifier (UUID v4).'
        example: '470987ab-b4cb-4a1e-9eaf-8856a813da59'
      subscriptionId:
        type: 'string'
        format: 'uuid'
        minLength: 36
        maxLength: 36
        description: 'Subscription identifier (UUID v4).'
        readOnly: true
        example: '4fc07667-b928-4a5c-a9d4-e18d3d515d24'
      dateTime:
        description: 'Date and time when the subscription was created. As defined by date-time - RFC3339.'
        type: 'string'
        format: 'date-time'
        readOnly: true
        example: '2020-04-12T22:20:50.52Z'
  Subscriptions:
    description: 'A list of subscriptions.'
    type: 'array'
    items:
      $ref: '#/definitions/Subscription'
  Metadata:
    description: 'Pagination information.'
    type: 'object'
    properties:
      page:
        description: 'Current page.'
        type: 'integer'
        readOnly: true
        example: 7
      perPage:
        description: 'Rows per page.'
        type: 'integer'
        readOnly: true
        example: 15
      pageCount:
        description: 'Total number of pages.'
        type: 'integer'
        readOnly: true
        example: 12
      totalCount:
        description: 'Total number of rows.'
        type: 'integer'
        readOnly: true
        example: 175
      links:
        $ref: '#/definitions/Links'
  Links:
    description: 'Pagination information.'
    type: 'object'
    properties:
      self:
        description: 'URL of this page.'
        type: 'string'
        readOnly: true
        example: 'https://services.circulodecredito.com.mx/v1/subscriptions?page=7&perPage=15'
      first:
        description: 'URL of the first page.'
        type: 'string'
        readOnly: true
        example: 'https://services.circulodecredito.com.mx/v1/subscriptions?page=1&perPage=15'
      previous:
        description: 'URL of the previous page.'
        type: 'string'
        readOnly: true
        example: 'https://services.circulodecredito.com.mx/v1/subscriptions?page=6&perPage=15'
      next:
        description: 'URL of the next page.'
        type: 'string'
        readOnly: true
        example: 'https://services.circulodecredito.com.mx/v1/subscriptions?page=8&perPage=15'
      last:
        description: 'URL of the last page.'
        type: 'string'
        readOnly: true
        example: 'https://services.circulodecredito.com.mx/v1/subscriptions?page=12&perPage=15'
  SubscriptionsMetadata:
    description: 'A list of subscriptions showed in pages.'
    type: 'object'
    properties:
      _metadata:
        $ref: '#/definitions/Metadata'
      subscriptions:
        $ref: '#/definitions/Subscriptions'
  SubscriptionAcknowledge:
    description: 'Subscription acknowledge information.'
    type: 'object'
    properties:
      acknowledgeId:
        type: 'string'
        format: 'uuid'
        minLength: 36
        maxLength: 36
        description: 'The acknowledge identifier (UUID v4).'
        readOnly: true
        example: '627aa72a-c799-4abf-b98e-0c4838af9bd5'
      dateTime:
        description: 'Date and time when the acknowledge was sent. As defined by date-time - RFC3339.'
        type: 'string'
        format: 'date-time'
        readOnly: true
        example: '2020-04-12T22:20:50.52Z'
      operation:
        description: 'Subscription activity.'
        type: 'string'
        enum:
          - 'enrollment'
          - 'cancellation'
        readOnly: true
        example: 'enrollment'
      message:
        description: 'Descriptive and human-readable message.'
        type: 'string'
        readOnly: true
        example: 'The subscription was created.'
      subscription:
        $ref: '#/definitions/Subscription'
