Send NIP

Endpoint to send the NIP Buró. Step 1 in the process of a SIC query authentication

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":"[email protected]"
}

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.

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.

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 you shall fill the query param with:

  • success: it sends back a success answer for a request, it's only a simulation, this test case will not send any NIP to the provided method.

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

Language
Authorization
Header
Click Try It! to start a request and see the response here!