API to send the NIP
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
Body
It is not necessary to send a query body, because the required fields are obtained from the form, so you only need to have your workfloo configured with the required fields.
Kiban will send the following fixed messages.
- For email:
Email message
Hola {{firstName}}
Tu NIP para validar la creación de tu cuenta y autorizar la consulta del Reporte de Crédito {{company_name}} es:
{{NIP}}Atentamente,
El equipo kiban
- For SMS
The message defined in the NIP connector configuration in workfloo will be sent.
- For WhatsApp:
WhatsApp message
Tu NIP para crear tu cuenta y autorizar la consulta del Reporte de Crédito es {{NIP}}
Where {{firstName}}, {{company_name}} and {{NIP}} will be replaced by the fields in the form and the generated NIP value. In case of using emil or WhatsApp, 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
A successful response will only have an http code 200.
Test the service
You can make sanbox requests to this API, it is not necessary to provide any other parameter to the query, being in a sandbox environment it is assumed that a NIP is sent, but this is not actually sent, sendings are only made in the production environment.
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
id workfloo not found
You will get a 404 Not Found error when the workflooId field is not correct in the path parameter request.
NIP previously sent
You will get a 400 Bad Request error when the NIP was previously sent.
Not authorized
If you receive an error code 401, it is because you do not have execution permissions, this happens because the service was consumed with an incorrect API KEY.