swagger: '2.0'
info:
  title: 'GuardIAn Score de Circulo de Crédito'
  description: <p>Score desarrollado con el objetivo de estimar la probabilidad que una solicitud sea fraudulenta. Este score puede ser obtenido a partir del folio de la consulta o datos generales. Si es por esta última opción, se debe tener en cuenta que la llamada API se debe enviar en el momento en el que se realiza la solicitud de crédito.<br/><br/><img src='https://developer.circulodecredito.com.mx/sites/default/files/2024-01/Logo-Swaggers.png' width='240'/></p> 
  version: 1.0.0
  termsOfService: 'https://developer.circulodecredito.com.mx/legal'
  contact:
    email: 'api@circulodecredito.com.mx'
  license:
    name: 'Derechos reservados Circulo de Crédito 2021'
    url: 'https://developer.circulodecredito.com.mx/aviso-de-privacidad'
host: 'services.circulodecredito.com.mx'
basePath: '/'
externalDocs:
      description: 'Portal de desarrolladores'
      url: 'https://developer.circulodecredito.com.mx/apis'
    
schemes:
- 'https'
paths:
  '/v1/guardian-score':
    post:
      tags:
      - 'GuardIAn Score'
      operationId: 'creditreport'
      consumes:
        - 'application/json'
      produces:
        - 'application/json'
      parameters:
        - name: 'x-signature'
          in: 'header'
          description: 'Firma generada con la llave privada'
          required: true
          type: 'string'
        - name: 'x-api-key'
          in: 'header'
          description: 'ConsumerKey obtenido desde el portal de desarrolladores'
          required: true
          type: 'string'
        - name: 'username'
          in: 'header'
          description: 'Usuario de Círculo de Crédito'
          required: true
          type: 'string'
        - name: 'password'
          in: 'header'
          description: 'Contraseña de Círculo de Crédito'
          required: true
          type: 'string'
        - in: 'body'
          name: 'body'
          description: 'Solicitud para obtener Score de Fraude' 
          required: true
          schema:
            $ref: '#/definitions/RequestBody'
      responses:
        '200':
          description: 'OK'
          schema:
            $ref: '#/definitions/ResponseBody'
        '400':
          description: "BAD REQUEST"
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              errores:
                - codigo: "400.1"
                  mensaje: "El campo \"{Campo}\" no puede estar vacío."
        '401':
          description: "UNAUTHORIZED"
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              errores:
                - codigo: "401.1"
                  mensaje: 'Acceso no autorizado, x-api-key no válida.'
                - codigo: '401.2'
                  mensaje: 'Acceso no autorizado.'
                - codigo: '401.3'
                  mensaje: 'Acceso no autorizado, no tiene el producto asociado.'
                - codigo: '401.4'
                  mensaje: 'Acceso no autorizado, no tiene acceso al recurso.'
        '403':
          description: "FORBIDDEN"
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              errores:
                - codigo: "403.1"
                  mensaje: "No se pudo autenticar, x-signature no es válida"
        '404':
          description: "NOT FOUND"
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              errores:
                - codigo: "404.1"
                  mensaje: "No se encontraron resultados."
        '429':
          description: 'TOO MANY REQUESTS'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              errores:
                - codigo: '429.1'
                  mensaje: 'Se han enviado demasiadas solicitudes. Se debe esperar antes de realizar una nueva solicitud.'                  
        '500':
          description: "INTERNAL SERVER ERROR"
          examples:
            application/json:
              errores:
                - codigo: "500.1"
                  mensaje: "Ocurrió un problema, inténtelo nuevamente más tarde."
          schema:
            $ref: "#/definitions/Error"
        '503':
          description: 'SERVICE UNAVAILABLE'
          examples:
            application/json:
              errores:
                - codigo: "503.1"
                  mensaje: "Servicio no disponible."

  '/v1/guardian-express/datos-generales':
    post:
      summary: Datos Generales
      tags:
      - 'GuardIAn Score'
      description: ''
      operationId: 'datos-generales'
      parameters:
        - name: x-signature
          in: 'header'
          description: Firma generada con la llave privada
          required: true
          type: string
        - name: x-api-key
          in: 'header'
          description: ConsumerKey obtenido desde el portal de desarrolladores
          required: true
          type: string
        - name: username
          in: 'header'
          description: Usuario de Círculo de Crédito
          required: true
          type: string
        - name: password
          in: 'header'
          description: Contraseña de Círculo de Crédito
          required: true
          type: string
        - in: 'body'
          name: 'body'
          description: 'Solicitud para obtener Score de Fraude' 
          required: true
          schema:
            $ref: '#/definitions/RequestDatosGenerales'
      responses:
        200:
          description: 'OK'
          schema:
            $ref: '#/definitions/ResponseGuardianDG'
        204:
          description: NO CONTENT
        '400':
          description: "BAD REQUEST"
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              errores:
                - codigo: "400"
                  mensaje: El campo [nombre_campo] es requerido
                - codigo: "400"
                  mensaje: El código postal no corresponde al estado.
                - codigo: "400.4"
                  mensaje: Petición incorrecta el x-signature es requerido.
        '401':
          description: "UNAUTHORIZED"
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              errores:
                - codigo: "401.1"
                  mensaje: Acceso no autorizado, x-api-key no válida.
                - codigo: "401.2"
                  mensaje: Acceso no autorizado.
                - codigo: "401.3"
                  mensaje: Acceso no autorizado, no tiene el producto asociado.
                - codigo: "401.4"
                  mensaje: Acceso no autorizado, no tiene acceso al recurso.
        '403':
          description: "FORBIDDEN"
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              errores:
                  - codigo: "403"
                    mensaje: Acceso denegado
                  - codigo: "403.1"
                    mensaje: No se pudo autenticar, x-signature no es válida.
                  - codigo: "403.2"
                    mensaje: No se pudo autenticar.
        '404':
          description: "NOT FOUND"
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              errores:
                - codigo: "404.1"
                  mensaje: No se encontró a la persona.
        
        '405':
          description: "METHOD NOT ALLOWED"
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              errores:
                  - codigo: "405.1"
                    mensaje: Método no permitido.

        '415':
          description: "UNSUPPORTED MEDIA TYPE."
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              errores:
                - codigo: "415.1"
                  mensaje: Medios no admitidos

        '429':
          description: 'TOO MANY REQUESTS'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              errores:
                - codigo: '429.1'
                  mensaje: 'Se han enviado demasiadas solicitudes. Se debe esperar antes de realizar una nueva solicitud.'                  
        '500':
          description: "INTERNAL SERVER ERROR"
          examples:
            application/json:
              errores:
                - codigo: "500.1"
                  mensaje: "Ocurrió un problema, inténtelo nuevamente más tarde."
                - codigo: "500.1"
                  mensaje: Ocurrio un problema, inténtelo nuevamente más tarde.
          schema:
            $ref: "#/definitions/Error"
        '503':
          description: 'SERVICE UNAVAILABLE'
          examples:
            application/json:
              errores:
                - codigo: "503.1"
                  mensaje: "Servicio no disponible."
      x-codegen-request-body-name: 'datos-generales'

definitions:

  RequestDatosGenerales:
      type: object
      properties:
        folioOtorgante:
          type: number
          minLength: 1
          maxLength: 25
          pattern: (^[\s0-9a-zA-Z])$
          example: 1234
        persona:
          required:
            - primerNombre
            - apellidoPaterno
            - apellidoMaterno
            - fechaNacimiento
          type: object
          properties:
            primerNombre:
              type: string
              description: 'Primer nombre de la persona'
              minLength: 1
              maxLength: 25
              pattern: (^[\sA-Za-z\u00C0-\u017F]+)$
              example: "JUAN"
            segundoNombre:
              description: 'Segundo nombre de la persona, si tiene'
              pattern: (^[\sA-Za-z\u00C0-\u017F]+)$
              example: null
            apellidoPaterno:
              type: string
              description: 'Apellido paterno de la persona'
              minLength: 1
              maxLength: 25
              pattern: (^[\sA-Za-z\u00C0-\u017F]+)$
              example: "PRUEBA"
            apellidoMaterno:
              type: string
              description: 'Apellido materno de la persona'
              minLength: 1
              maxLength: 25
              pattern: (^[\sA-Za-z\u00C0-\u017F]+)$
              example: "CUATRO"
            apellidoAdicional:
              description: 'Apellido adicional de la persona, si tuviere'
              pattern: (^[\sA-Za-z\u00C0-\u017F]+)$
              example: null
            fechaNacimiento:
              type: string
              description: 'Fecha de nacimiento de la persona, en el formato especificado (por defecto dd-MM-yyyy)'
              minLength: 1
              maxLength: 25
              format: 'yyyy-MM-dd-'
              example: "1980-01-04"
            RFC:
              type: string
              description: 'RFC con homoclave de la persona'
              maxLength: 13
              pattern: (^[A-Za-z0-9]+)$
              example: "PUCJ800104"
            domicilio:
              required:
                - cp
              type: object
              properties:
                direccion:
                  type: string
                  pattern: (^[\sA-Za-z0-9]+)$
                  description: 'Reportar el nombre de la calle, número exterior, número interior. Deben considerarse avenida,cerrada, manzana, lote, edificio,departamento etc. Debe contener por lo menos dos cadenas de caracteres para que el registro sea válido, de lo contrario el registro será rechazado.'
                  minLength: 0
                  maxLength: 80
                  example: 'INSURGENTE SUR 1007'
                colonia:
                  type: string
                  pattern: (^[\sA-Za-z0-9]+)$
                  description: 'Reportar la colonia a la cual pertenece la dirección contenida en el elemento dirección.'
                  minLength: 0
                  maxLength: 65
                  example: 'INSURGENTES'
                delegacionMunicipio:
                  type: string
                  pattern: (^[\sA-Za-z0-9]+)$
                  description: 'Reportar la delegación o municipio a la cual pertenece la dirección contenida en el elemento Dirección.'
                  minLength: 0
                  maxLength: 65
                  example: 'BENITO JUAREZ'
                ciudad:
                  type: string
                  pattern: (^[\sA-Za-z0-9]+)$
                  description: 'Reportar la ciudad a la cual pertenece la dirección contenida en el elemento Dirección.'
                  minLength: 0
                  maxLength: 65
                  example: 'MEXICO'
                estado:
                  $ref: '#/definitions/CatalogoEstados'
                cp:
                  type: string
                  pattern: (^[\s0-9]+)$
                  description: 'El código postal reportado debeestar compuesto por 5 dígitos. Para que el código postal sea válido deberá corresponder al estado reportado.'
                  minLength: 5
                  maxLength: 5
                  example: '11230'


  CreditReport:
    type: object
    required:
    - 'idFolioConsultaReporte'
    - 'folioOtorgante'
    properties:
      idFolioConsultaReporte:
        description: 'Folio de consulta del RC o RCC para identificar al solicitante de crédito'
        type: string
        minLength: 2
        maxLength: 30
        example: 389844067
      folioOtorgante:
        description: 'Folio interno único o número consecutivo para identificar a la persona'
        type: string
        maxLength: 10
        example: 0202
  RequestBody:
    type: object
    required:
      - 'creditReport'
    properties:
      creditReport:
        $ref: '#/definitions/CreditReport'
        
  ResponseBody:
    type: 'object'
    properties:
      score:
        type: 'string'
        description: 'Valor del score  (0, 10)'
        example: '3.5'
      razones:
        type: 'array'
        description: 'Reglas activadas'
        items:
          type: 'string'
        example: ['CDC22','CDC23','CDC224','CDC27','CDC06']
      folioConsulta:
        description: 'Folio de conuslta de  score de fraude' 
        type: 'string'
        example: 390008494
      success:
        type: 'boolean'
        example: true
      mensaje:
        type: 'string'
        example: 'La peticion se proceso de manera exitosa'
  Error:
    type: 'object'
    properties:
      code:
        type: 'string'
        example: 'VA003'
        description: 'Código de error'
      message:
        type: 'string'
        example: 'El campo "campo" es requerido.'
        description: 'Mensaje de error'
      title:
        type: 'string'
        example: 'Alerta'
        description: 'Titulo de error'
      status:
        type: 'string'
        example: 'BAD_REQUEST'
        description: 'Status Http'
        minLength: 3
        maxLength: 3
        enum:
          - '100'
          - '101'
          - '102'
          - '103'
          - '200'
          - '201'
          - '202'
          - '203'
          - '204'
          - '205'
          - '206'
          - '207'
          - '208'
          - '226'
          - '300'
          - '301'
          - '302'
          - '303'
          - '304'
          - '305'
          - '307'
          - '308'
          - '400'
          - '401'
          - '402'
          - '403'
          - '404'
          - '405'
          - '406'
          - '407'
          - '408'
          - '409'
          - '410'
          - '411'
          - '412'
          - '413'
          - '414'
          - '415'
          - '416'
          - '417'
          - '418'
          - '419'
          - '420'
          - '421'
          - '422'
          - '423'
          - '424'
          - '426'
          - '428'
          - '429'
          - '431'
          - '451'
          - '500'
          - '501'
          - '502'
          - '503'
          - '504'
          - '505'
          - '506'
          - '507'
          - '508'
          - '509'
          - '510'
          - '511'
    title: 'Error'
    description: 'error'
  Errores:
    type: 'object'
    description: 'Si existen errores, se listarán.'
    properties:
      errores:
        type: 'array'
        items:
          $ref: '#/definitions/Error'

  ResponseGuardianDG:
      type: object
      properties:
        score:
          type: string
          example: "0.8"
        razones: 
          type: array
          items:
            type: string
          example: ["CDC22","CDC01","CDC23"]
        folioConsulta:
          type: string
          example: "389966042"

  CatalogoEstados:
      type: string
      description: "Estado en que se ubica el domicilio <table><thead><tr><th>Clave</th><th>Estado</th></tr></thead><tbody><tr><td>AGS</td><td>AGUASCALIENTES</td></tr><tr><td>BC</td><td>BAJA CALIFORNIA NORTE</td></tr><tr><td>BCS</td><td>BAJA CALIFORNIA SUR</td></tr><tr><td>CAMP</td><td>CAMPECHE</td></tr><tr><td>CDMX</td><td>CIUDAD DE MÉXICO</td></tr><tr><td>CHIS</td><td>CHIAPAS</td></tr><tr><td>CHIH</td><td>CHIHUAHUA</td></tr><tr><td>COAH</td><td>COHAHUILA</td></tr><tr><td>COL</td><td>COLIMA</td></tr><tr><td>DF</td><td>DISTRITO FEDERAL</td></tr><tr><td>DGO</td><td>DURANGO</td></tr><tr><td>GTO</td><td>GUANAJUATO</td></tr><tr><td>GRO</td><td>GUERRERO</td></tr><tr><td>HGO</td><td>HIDALGO</td></tr><tr><td>JAL</td><td>JALISCO</td></tr><tr><td>MEX</td><td>MÉXICO</td></tr><tr><td>MICH</td><td>MICHOCÁN</td></tr><tr><td>MOR</td><td>MORELOS</td></tr><tr><td>NAY</td><td>NAYARIT</td></tr><tr><td>NL</td><td>NUEVO LEÓN</td></tr><tr><td>OAX</td><td>OAXACA</td></tr><tr><td>PUE</td><td>PUEBLA</td></tr><tr><td>QRO</td><td>QUERÉTARO</td></tr><tr><td>QROO</td><td>QUINTANA ROO</td></tr><tr><td>SLP</td><td>SAN LUIS POTOSÍ</td></tr><tr><td>SIN</td><td>SINALOA</td></tr><tr><td>SON</td><td>SONORA</td></tr><tr><td>TAB</td><td>TABASCO</td></tr><tr><td>TAMP</td><td>TAMAULIPAS</td></tr><tr><td>TLAX</td><td>TLAXCALA</td></tr><tr><td>VER</td><td>VERACRUZ</td></tr><tr><td>YUC</td><td>YUCATÁN</td></tr><tr><td>ZAC</td><td>ZACATECAS</td></tr></tbody></table>"
      minLength: 2
      maxLength: 4
      pattern: (^[A-Za-z]+)$
      example: DF
      enum:
        - AGS
        - BC
        - BCS
        - CAMP
        - COAH
        - COL
        - CHIS
        - CHIH
        - DF
        - CDMX
        - DGO
        - GTO
        - GRO
        - HGO
        - JAL
        - MEX
        - MICH
        - MOR
        - NAY
        - NL
        - OAX
        - PUE
        - QRO
        - QROO
        - SLP
        - SIN
        - SON
        - TAB
        - TAMP
        - TLAX
        - VER
        - YUC
        - ZAC