swagger: '2.0'
info:
  description: <p
    style='margin:0cm;font-size:16px;font-family:"Calibri",sans-serif;vertical-align:top;'>API
    that validates the specified phone number and obtain the metadata associated
    with it.<br/><br/>
    <img src='https://developer.circulodecredito.com.mx/sites/default/files/2020-10/circulo_de_credito-apihub.png'  width='240' /><em><span
    style='font-family:"Literata",sans-serif;'><span
    style='text-decoration:none;
    font-size:28px'><big><Big><Big><big><big><big><sup></big></sup></big></big></big></big></span></em></p><br/>
  version: 1.0.1
  title: Telco TLV (Telephone Line Verification)
  termsOfService: https://developer.circulodecredito.com.mx/legal-mx
  contact:
    email: api@circulodecredito.com.mx
  license:
    name: Derechos Reservados Círculo de Crédito 2024
    url: https://services.circulodecredito.com.mx
host: services.circulodecredito.com.mx
basePath: /v1/telco
tags:
  - name: Telco
    description: API for telco data aggregation.
schemes:
  - https
paths:
  /aggregations:
    post:
      tags:
        - Telco
      summary: Start the aggregation process to validate the specified phone number
        and retrieve the data associated with it.
      description: Request a new Telco Aggregation. Note that this operation only
        start a new aggregation and do NOT return the final result, the final
        result is delivery through the webhook HTTP notification and
        additionally can be fetched using the endpoint
        '/aggregations/{inquiryId}' of this API.
      operationId: aggregatePhoneNumber
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: header
          name: x-api-key
          type: string
          required: true
          description: Your authentication API key. The Key is assigned through the
            Círculo de Crédito API-Hub Web site.<br>If you have any questions
            please contact your Círculo de Crédito sales agent.
        - in: header
          name: username
          type: string
          required: true
          description: Your username from the Círculo de Crédito Grantor Web Portal.
            <br>If you have any questions please contact your Círculo de Crédito
            sales agent.
        - in: header
          name: password
          type: string
          required: true
          description: Your password from the Círculo de Crédito Grantor Web Portal.
            <br>If you have any questions please contact your Círculo de Crédito
            sales agent.
        - in: header
          name: x-signature
          type: string
          required: true
          description: The digital signature of the full HTTP Request Body (payload) that
            you send to call this API. The siganture is created with your
            private key (SHA256withECDSA - secp384r) and the request
            body.<br><br><b>NOTE:</b> It is not necessary to canonicalize the
            request body, however, the request body that is sent to invoke the
            API must be exactly the same as the one used to generate the digital
            signature (x-signature).<br><br> <b>IMPORTANT:</b> Please refer to
            the <a
            href="https://developer.circulodecredito.com.mx/guia_de_inicio">Círculo
            de Crédito API-Hub</a> site to learn the details and specifications
            for the process of generating the certificates and cryptographic
            keys necessary to consume this API.
        - in: body
          name: body
          description: Telco Aggregation request object.
          required: true
          schema:
            $ref: '#/definitions/PhoneNumberPostRequest'
      responses:
        '200':
          headers:
            x-signature:
              type: string
              description: Signature of the response body (payload), the signature is created
                by the Telco API with the Círculo de Crédito private key. You
                must verify the signature against the received response body
                (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/PhoneNumberPostResponse'
          description: Telco Aggregation response object.
        '400':
          headers:
            x-signature:
              type: string
              description: Signature of the response body (payload), the signature is created
                by the Telco API with the Círculo de Crédito private key. You
                must verify the signature against the received response body
                (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Bad Request Error Response.
          examples:
            application/json:
              errors:
                - code: '400.1'
                  message: A request body is required but none found.
                - code: '400.1'
                  message: Header parameter 'XXXXXXX' is required on path '/aggregations' but not
                    found in request.
                - code: '400.1'
                  message: 'Missing required property: XXXXXX'
                - code: '400.103'
                  message: 'The provided subscription has an invalid event type. Event type
                    expected: ''mx.com.circulodecredito.telcos'' but the
                    subscription xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx has an
                    event type of: ''mx.com.circulodecredito.xxxx'''
        '401':
          headers:
            x-signature:
              type: string
              description: Signature of the response body (payload), the signature is created
                by the Telco API with the Círculo de Crédito private key. You
                must verify the signature against the received response body
                (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Unauthorized Error Response.
          examples:
            application/json:
              errors:
                - code: '401.2'
                  message: Unauthorized, invalid x-api-key.
                - code: '401.3'
                  message: Unauthorized, invalid x-signature value.
                - code: '401.4'
                  message: Unauthorized, invalid username or password.
        '404':
          headers:
            x-signature:
              type: string
              description: Signature of the response body (payload), the signature is created
                by the Telco API with the Círculo de Crédito private key. You
                must verify the signature against the received response body
                (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Not Found Error Response.
          examples:
            application/json:
              errors:
                - code: '404.100'
                  message: The provided subscription xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx was not
                    found.
        '500':
          headers:
            x-signature:
              type: string
              description: Signature of the response body (payload), the signature is created
                by the Telco API with the Círculo de Crédito private key. You
                must verify the signature against the received response body
                (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Internal Server Error Response.
          examples:
            application/json:
              errors:
                - code: '500.100'
                  message: Unexpected system error. Try again later or contact technical support.
  /aggregations/{inquiryId}:
    get:
      tags:
        - Telco
      summary: Get the Telco Aggregation associated with the specified inquiryId.
      description: Fetch the specified Telco Aggregation by inquiryId and return the
        result. This operation could return a partial result if the aggregation
        is not been completed yet or the final result if the aggregation process
        has been finished.
      operationId: getPhoneNumberAggregation
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: inquiryId
          type: string
          description: The unique identifier of an aggregation. The inquiryId is provided
            in response to a successful start aggregation request by this API.
          required: true
        - in: header
          name: x-api-key
          type: string
          required: true
          description: Your authentication API key. The Key is assigned through the
            Círculo de Crédito API-Hub Web site.<br>If you have any questions
            please contact your Círculo de Crédito sales agent.
        - in: header
          name: username
          type: string
          required: true
          description: Your username from the Círculo de Crédito Grantor Web Portal.
            <br>If you have any questions please contact your Círculo de Crédito
            sales agent.
        - in: header
          name: password
          type: string
          required: true
          description: Your password from the Círculo de Crédito Grantor Web Portal.
            <br>If you have any questions please contact your Círculo de Crédito
            sales agent.
        - in: header
          name: x-signature
          type: string
          required: true
          description: The digital signature of the <b>inquiryId</b> that you will send in
            the URL path to call this API. The siganture is created with your
            private key (SHA256withECDSA - secp384r) and the inquiryId from the
            URL.<br><br><b>NOTE:</b> The requested inquiryId that is sent to
            invoke the API must be exactly the same as the one used to generate
            the digital signature (x-signature).<br><br> <b>IMPORTANT:</b>
            Please refer to the <a
            href="https://developer.circulodecredito.com.mx/guia_de_inicio">Círculo
            de Crédito API-Hub</a> site to learn the details and specifications
            for the process of generating the certificates and cryptographic
            keys necessary to consume this API.
      responses:
        '200':
          headers:
            x-signature:
              type: string
              description: Signature of the response body (payload), the signature is created
                by the Telco API with the Círculo de Crédito private key. You
                must verify the signature against the received response body
                (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/AggregationPhoneNumberGetResponse'
          description: Telco Aggregation Response Data.
        '400':
          headers:
            x-signature:
              type: string
              description: Signature of the response body (payload), the signature is created
                by the Telco API with the Círculo de Crédito private key. You
                must verify the signature against the received response body
                (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Bad Request Error Response.
          examples:
            application/json:
              errors:
                - code: '400.1'
                  message: Header parameter 'XXXXXXX' is required on path
                    '/aggregations/{inquiryId}' but not found in request.
                - code: '400.1'
                  message: GET operation not allowed on path '/aggregations/'.
        '401':
          headers:
            x-signature:
              type: string
              description: Signature of the response body (payload), the signature is created
                by the Telco API with the Círculo de Crédito private key. You
                must verify the signature against the received response body
                (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Unauthorized Error Response.
          examples:
            application/json:
              errors:
                - code: '401.2'
                  message: Unauthorized, invalid x-api-key.
                - code: '401.3'
                  message: Unauthorized, invalid x-signature value.
                - code: '401.4'
                  message: Unauthorized, invalid username or password.
        '404':
          headers:
            x-signature:
              type: string
              description: Signature of the response body (payload), the signature is created
                by the Telco API with the Círculo de Crédito private key. You
                must verify the signature against the received response body
                (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Not Found Error Response.
          examples:
            application/json:
              errors:
                - code: '404.101'
                  message: No request associated with the provided inquiryId was found.
                - code: '404.102'
                  message: No aggregation was found with the provided inquiryId.
        '500':
          headers:
            x-signature:
              type: string
              description: Signature of the response body (payload), the signature is created
                by the Telco API with the Círculo de Crédito private key. You
                must verify the signature against the received response body
                (paylod) using the Círculo de Crédito public certificate
                downloaded from the Círculo de Crédito developers web portal.
          schema:
            $ref: '#/definitions/ResponseErrorObject'
          description: Telco Aggregation Internal Server Error Response.
          examples:
            application/json:
              errors:
                - code: '500.100'
                  message: Unexpected system error. Try again later or contact technical support.
definitions:
  PhoneNumberPostRequest:
    type: object
    properties:
      requestId:
        type: string
        format: uuid
        description: 'The unique identifier of the request, this value is provided by
          the client consuming the API. <p>IMPORTANT: This value MUST be an UUID
          v1. This ensures efficient system performance.</p>'
      subscriptionId:
        type: string
        format: uuid
        description: The unique identifier of a valid 'Círculo de Crédito' subscription.
          <p>This value allows the asynchronous reception of the results of this
          API, through an HTTP call to the webhook associated with the
          subscription.</p>
      companyName:
        type: string
        pattern: ^[a-zA-ZñÑáéíóúÁÉÍÓÚ]+(([ ][a-zA-ZñÑáéíóúÁÉÍÓÚ
          ])?[a-zA-ZñÑáéíóúÁÉÍÓÚ]*)*$
        example: Pruebas Corportation
        description: 'The name of the ''business/company'' that is trying to validate
          the phone number via ''whatsapp'' message. <p>IMPORTANT: This name
          will appear in the whatsapp message sent to the final user.</p>
          <p>NOTE: This field only works if the ''setting'' ''ownership'' is
          activated (true).</p>'
      termsConditionsUrl:
        type: string
        description: 'The company terms and conditions URL. This URL is shown in the
          whatsapp validation message that is send to the end-user.<br><br>Note:
          This URL correspond with the terms and conditions of the grantor, NOT
          the terms and conditions of ''Círculo de Credito''.'
        maxLength: 512
        pattern: ^(https?:\/\/(?:www\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\.[^\s]{2,}|www\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\.[^\s]{2,}|https?:\/\/(?:www\.|(?!www))[a-zA-Z0-9]+\.[^\s]{2,}|www\.[a-zA-Z0-9]+\.[^\s]{2,})$
        example: https://www.acme.com/terms-conditions
      customer:
        $ref: '#/definitions/Customer'
      settings:
        $ref: '#/definitions/AggregationSettings'
  PhoneNumberPostResponse:
    type: object
    properties:
      requestId:
        type: string
        format: uuid
        description: 'The unique identifier of the request, this value is provided by
          the client consuming the API. <p>IMPORTANT: This value MUST be an UUID
          v1. This ensures efficient system performance.</p>'
      inquiryId:
        type: string
        format: uuid
        description: 'The unique identifer of the Telco Aggregation, allows to track the
          progress and final result of the aggregation. <p>IMPORTANT: This is
          NOT an UUID string, is an alphanumeric string with hyphen characters,
          with variable length from 37 characters up to 64 characters.</p>
          <p>NOTE: This value is automatically generated by the API Telco ONLY
          when there is a successful aggregation request.</p>'
      dateTime:
        type: string
        format: date-time
        description: The date-time when the Telco Aggregation was STARTED,
          NOT_AUTHORIZED or FAILED.
      status:
        type: string
        enum:
          - STARTED
          - NOT_AUTHORIZED
          - FAILED
        description: The possible 'status' values that the Telco Aggregation can have
          when it is requested.
  AggregationPhoneNumberGetResponse:
    type: object
    properties:
      requestId:
        type: string
        format: uuid
        description: 'The unique identifier of the request, this value is provided by
          the client consuming the API. <p>IMPORTANT: This value MUST be an UUID
          v1. This ensures efficient system performance.</p>'
      inquiryId:
        type: string
        format: uuid
        description: 'The unique identifer of the Telco Aggregation, allows to track the
          progress and final result of the aggregation. <p>IMPORTANT: This is
          NOT an UUID string, is an alphanumeric string with hyphen characters,
          with variable length from 37 characters up to 64 characters.</p>
          <p>NOTE: This value is automatically generated by the API Telco ONLY
          when there is a successful aggregation request.</p>'
      status:
        type: string
        enum:
          - FINISHED
          - IN_PROGRESS
          - FAILED
          - NOT_AUTHORIZED
        description: The possible 'status' values that the Telco Aggregation can have
          when it is queried.
      dateTime:
        type: string
        format: date-time
        description: The date-time when the Telco Aggregation was FINISHED, IN_PROGRESS,
          NOT_AUTHORIZED or FAILED.
      aggregation:
        $ref: '#/definitions/Aggregation'
  Customer:
    type: object
    properties:
      phoneNumber:
        type: string
        pattern: ^[0-9]{10}$
        description: The phone number that will be used for the Telco Aggregation process.
      name:
        type: string
        pattern: ^[a-zA-ZñÑáéíóúÁÉÍÓÚ]+(([ ][a-zA-ZñÑáéíóúÁÉÍÓÚ
          ])?[a-zA-ZñÑáéíóúÁÉÍÓÚ]*)*$
        example: Juan Pruebas
        description: 'The name of the final user/customer which phone number will be
          validated via ''whatsapp'' message. <p>IMPORTANT: This name will
          appear in the whatsapp message sent to the final user.</p> <p>NOTE:
          This field only works if the ''setting'' ''ownership'' is activated
          (true).</p>'
      authorization:
        type: boolean
        description: 'A boolean flag to indicate the authorization of the final
          user/customer to do the Telco Aggregation process with their phone
          number. True if the final user/customer authorize the Telco
          Aggregation process, false otherwise.<p>IMPORTANT: If the final
          user/customer do not authorize the Telco Aggregation process the
          process will not be carried out and will be cancelled.</p>'
      authorizationDateTime:
        type: string
        format: date-time
        description: The date-time when the final user/customer authorized the Telco
          Aggregation process on their own phone number.
  AggregationSettings:
    type: object
    description: Settings available in the API Telco, allows you to choose the
      behavior that the API will have.
    properties:
      ownership:
        type: boolean
        description: Activates the phone message validation via 'whatsapp' message.
      socialNetworks:
        type: boolean
        description: Activates the validation of social networks associated with the
          phone number.
      statistics:
        type: boolean
        description: Reserved for future use. Not working right now.
  Aggregation:
    type: object
    properties:
      phone:
        $ref: '#/definitions/Phone'
      socialNetworks:
        $ref: '#/definitions/SocialNetworks'
  Phone:
    type: object
    properties:
      number:
        type: string
        pattern: ^[0-9]{10}$
        description: The phone number used for the Telco Aggregation process.
      carrier:
        type: string
        example: TELCEL
        description: The phone carrier of the phone number.
      city:
        type: string
        example: CUAUHTEMOC
        description: The city associated with phone number.
      type:
        type: string
        enum:
          - MOBILE
          - LANDLINE
        description: The type of phone number.
      authenticity:
        type: string
        enum:
          - VALID
          - INVALID
          - UNKNOWN
        description: Indicates the validity of the telephone number.
      ownership:
        type: string
        enum:
          - WAITING_CONFIRMATION
          - NOT_REQUESTED
          - OWNERSHIP_CONFIRMED
          - OWNERSHIP_DENIED
          - NOT_CONFIRMED
          - FAILED
        description: Indicates the current 'status' of the 'ownership' process (i.e. the
          whatsapp message validation) in the Telco Aggregation.
  SocialNetworks:
    type: object
    description: Indicates the social networks associated with the provided phone
      number. True if the social network is associated with phone number, false
      otherwise
    properties:
      whatsapp:
        type: boolean
      facebook:
        type: boolean
      instagram:
        type: boolean
      google:
        type: boolean
      twitter:
        type: boolean
      microsoft:
        type: boolean
      yahoo:
        type: boolean
      skype:
        type: boolean
      snapchat:
        type: boolean
      telegram:
        type: boolean
  ResponseErrorObject:
    type: object
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/ArrayErrorObject'
  ArrayErrorObject:
    type: object
    properties:
      code:
        type: string
      message:
        type: string