Query

Intro

This API is meant to query Círculo de Crédito - Personas Morales (Legal entities database).

Important points

Request Data

To make the request it is necessary to provide the next request fields.

If you want to validate the RFC (Registro Federal de Contribuyentes) of the P (Persona Física) or PM (Persona Moral), you can use this service to ensure that the RFC provided is correct.

Validations

Validations applied to the rfc parameter

• Must be 12 characters long.
• Must comply with the format of a valid RFC for a legal entity.

Validations applied to the cp parameter

• Must be 5 digits long.
• The postal code must be a valid postal code according to the SEPOMEX catalog.
• To send data to the CC PM API, kiban obtains the delegation or municipality, city, state, and country fields through the postal code.

Response

You can find an examples of the different kinds of responses in the examples of the call.

Test the service (test cases)

We included a query param in Sandbox environment, so you can query test cases that we created to run tests. In order to obtain the response, please fill the query param with:

• success: it sends back a successful response
• notFound: it sends back a not found query
• serviceUnavailable: it sends back an error indicating that the service is not available.
• unauthorized, it sends back an error indicating that the request is unauthorized, due to a bad configuration about User, Password, API KEY or Certificate in the secret created in Vault.

📘

Test your own test case

In case you want to test your own test case created in link, you can change the testCase parameter to testCaseId and send the identifier of the test case you want to use

Possible Errors

Required fields

You will receive a 400 bad request error if any of the required parameters are not provided in the request body.

[
  {
    "field": "direccion",
    "errors": [
      {
        "code": "EMPTY_ERROR",
        "message": "can`t be empty",
        "field": "cp"
      }
    ]
  },
  {
    "field": "encabezado",
    "errors": [
      {
        "code": "EMPTY_ERROR",
        "message": "can't be empty",
        "field": "folioOtorgante"
      },
      {
        "code": "EMPTY_ERROR",
        "message": "can't be empty",
        "field": "vault"
      }
    ]
  },
  {
    "field": "authorization",
    "errors": [
      {
        "code": "EMPTY_ERROR",
        "message": "can't be empty",
        "field": "authorization"
      }
    ]
  },
  {
    "field": "datosGeneralesOCompania",
    "errors": [
      {
        "code": "EMPTY_ERROR",
        "message": "can't be empty",
        "field": "razonSocial"
      },
      {
        "field": "informacionGeneral",
        "errors": [
          {
            "code": "EMPTY_ERROR",
            "message": "can't be empty",
            "field": "rfc"
          }
        ]
      },
      {
        "field": "direccion",
        "errors": [
          {
            "code": "EMPTY_ERROR",
            "message": "can't be empty",
            "field": "direccion"
          },
          {
            "code": "EMPTY_ERROR",
            "message": "can't be empty",
            "field": "colonia"
          },
          {
            "code": "EMPTY_ERROR",
            "message": "can't be empty",
            "field": "cp"
          }
        ]
      }
    ]
  }
]

Invalid format

You will get a 400 bad request error any of the parameters do not comply with the correct format

[
  {
    "field": "direccion",
    "errors": [
      {
        "code": "ELEMENT_NOT_EXIST_ERROR",
        "message": "pais not found",
        "field": "pais"
      },
      {
        "code": "CATALOG_ERROR",
        "message": "postal code not found",
        "field": "cp"
      }
    ]
  },
  {
    "field": "direccion",
    "errors": [
      {
        "code": "ELEMENT_NOT_EXIST_ERROR",
        "message": "pais not found",
        "field": "pais"
      },
      {
        "code": "CATALOG_ERROR",
        "message": "postal code not found",
        "field": "cp"
      }
    ]
  },
  {
    "field": "datosGeneralesOCompania",
    "errors": [
      {
        "field": "informacionGeneral",
        "errors": [
          {
            "code": "LENGTH_ERROR",
            "message": "should be = 12",
            "field": "rfc"
          },
          {
            "code": "FORMAT_ERROR",
            "message": "invalid rfc",
            "field": "rfc"
          }
        ]
      }
    ]
  }
]

Test case not found

if a test case parameter is not sent or a value other than those mentioned above is sent, the service will return the following error 400 bad request

[
    {
        "code": "EMPTY_ERROR",
        "message": "test case not found",
        "field": "testCase"
    },
    {
        "code": "EMPTY_ERROR",
        "message": "test case not found with given id",
        "field": "testCaseId"
    }
]

Service Unavailable

If the Círculo de Crédito system is not available, this endpoint will retrieve the next response:

{
  "id": "65f370b719d32e8a893c53e2",
  "createdAt": "2024-03-14T15:48:39.011166-06:00",
  "finishedAt": "0001-01-01T00:00:00Z",
  "duration": 0,
  "status": "SERVICE_ERROR",
  "errorMessage": "Servicio no disponible"
}

NIP not found

You will receive this 400 bad request error if the provided NIP in the request body does not exist.

[
  {
    "field": "authorization",
    "errors": [
      {
        "code": "CONFLICT_ERROR",
        "message": "nip record not found",
        "field": "id"
      }
    ]
  }
]

NIP not found

You will receive this 400 bad request error if the provided NIP in the request body has not been validated.

[
  {
    "field": "authorization",
    "errors": [
      {
        "code": "CONFLICT_ERROR",
        "message": "nip record is not validated",
        "field": "id"
      }
    ]
  }
]

NIP already consumed

You will receive this 400 bad request error if the provided NIP in the request body has been consumed in another request.

[
  {
    "field": "authorization",
    "errors": [
      {
        "code": "CONFLICT_ERROR",
        "message": "nip already consumed",
        "field": "id"
      }
    ]
  }
]

Vault not found

You will receive this 404 not found error if the provided vault in the request body does not exist.

{
  "typeError": "ELEMENT_NOT_EXIST_ERROR",
  "errors": {},
  "errorMessage": "vault was not found"
}

Request unauthorized

You will receive this 401 unauthorized error if the there is a problem with the provided vault value in the request body. This is due to a misconfiguration of the secret in the vault section, usually because the user, password, API key or certificate are not correct and we were unable to authenticate the request to CC.

{
  "id": "66107b072e5feb3e7c9b5d48",
  "createdAt": "2024-04-05T16:28:23.750079-06:00",
  "finishedAt": "2024-04-05T16:28:23.884653-06:00",
  "duration": 134,
  "status": "SERVICE_ERROR",
  "errorMessage": "Access denied due to configuration error"
}