Intro

With this API you will carry out step 1 for the authentication process to the SICs (Buró de crédito and Círculo de Crédito).
With this API, a 6-digit NIP code will be sent to the client so that you can authenticate their query.

Important points

Required parameters

The principal required field in this endpoint is method, this field can have the following values.

email
sms
whatsapp

According to the method provided, is necessary to send the necessary fields for each one.

email

It is mandatory to send the email of the person who will receive the NIP via email with a valid format.

{
    "method":"email",
    "email":"help@kiban.com"
}

sms

With this method is mandatory to send the next fields:

countryCode, country code according to the International Telecommunication Union Catalog adding a plus (+) at the beginning.
to, indicate the phone number to which the SMS will be sent.
message, message to send the NIP. You can put any message, but it is mandatory to send the key word {{nip}} to be replaced by the NIP value in the message to send.

{
    "method":"sms",
    "countryCode":"+52",
    "to": "9999690335",
    "message":"Your NIP is: {{nip}}"
}

WhatsApp

With this method is mandatory to send the next fields:

countryCode, country code according to the International Telecommunication Union adding a plus (+) at the beginning. For example, to send an SMS to Mexico, you must send +52 in this field
to, indicate the phone number to which the SMS will be sent.

{
    "method":"whatsapp",
    "countryCode":"+52",
    "to": "9999690335"
}

Kiban will send the following fixed message:

📘
Tu NIP para crear tu cuenta y autorizar la consulta del Reporte de Crédito es {{NIP}}

Where NIP will be replaced by the generated NIP value. This message cannot be modified, so in case of using this method, you must consider that this will be the message sent to your client with the data of the kiban WhatsApp business account.

Callback

If you want to receive the different statuses of the NIP sent, you can receive callbacks in your API. To do this, you must add the following headers to the request (only active for SMS and WhatsApp).

header name	Description
urlCallback	Header to indicate the URL to which we will send the notifications with the response
xApiKeyCallback	Header to assign an API key if you need to add security to your service

Successful response

To know the fields of a successful response, please refer to the examples in the Response section.

Put special emphasis on retrieving the execution id, since this id will be used in steps 2 and 3 of validation.

Callback responses

If you activated a callback to receive the status of the PIN sending, you will be able to receive the following statuses:

Pending, when we receive the request and we are generating the sending of the NIP

{
  "event": "PENDING",
  "date": "2024-12-24T20:24:44.689415709Z",
  "linkId": "676b188a6ef8abaf775fef10"
}

Sent, when we send the NIP

{
  "event": "SENT",
  "date": "2024-12-24T20:24:44.71487296Z",
  "linkId": "676b188a6ef8abaf775fef10"
}

Success, when we detect that the client correctly received the NIP.

{
  "event": "SUCCESS",
  "date": "2024-12-24T20:24:46.284059543Z",
  "linkId": "676b188a6ef8abaf775fef10"
}

Error, indicates a generic error when an error occurred when sending the NIP, generally because it is not a correct number, it does not exist or it is not enabled to receive the NIP through the selected method.

{
  "event": "ERROR",
  "date": "2024-12-24T20:33:48.35163521Z",
  "errorMessage": "The destination number you are trying to reach is unknown and may no longer exist.",
  "linkId": "676b1aa96ef8abaf775fef27"
}

Possible Errors

Required Method

You will get a 400 bad request error when the method field is not provided in the body request.

{
  "method": "REQUIRED_FIELD_ERROR; EMPTY_ERROR; can't be empty (must be sms, whatsapp or email) "
}

Required fields for an specific method

When you choose an specific method, certain fields become mandatory, in case of not sending a required field, one of the following errors can be received.

{
  "countryCode": "REQUIRED_FIELD_ERROR; EMPTY_ERROR; can't be empty",
  "message": "REQUIRED_FIELD_ERROR; EMPTY_ERROR; can't be empty",
  "to": "REQUIRED_FIELD_ERROR; EMPTY_ERROR; can't be empty",
  "email": "REQUIRED_FIELD_ERROR; EMPTY_ERROR; can't be empty"
}

Invalid format

You will get a 400 bad request error when any of the parameters do not conform the specific length

{
  "email": "FORMAT_ERROR; should be correct format ^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$",
  "countryCode": "LENGTH_ERROR; should be <= 4",
  "message": "FORMAT_ERROR; must contain key nip in braces; {{nip}}",
  "to": "LENGTH_ERROR; should be >= 1 and <=15"
}

Test case not found

if a test case parameter is not sent in sandbox environment, the service will return the following error 400 bad request

{
    "testCase": "EMPTY_ERROR; test case not found"
}

API not activated

If you receive an error code 401, it is because you do not have execution permissions, this happens because the service was not activated in the marketplace or because there was an error entering the correct API KEY