Validate NIP

Intro

With this API you will carry out the steps 2 and 3 for the authentication process to the SICs (Buró de crédito and Círculo de Crédito).
With this API, the 6-digit PIN code sent in step 1 for the authentication process of the query to a SIC will be validated.

Important points

📘

This endpoint is the same one that must be executed for steps 2 and 3 of the authentication process via NIP. That is, you must run this service twice to successfully validate the NIP and, later, be able to query a SIC.

Required parameters

The required parameters on this endpoint are the next:

• id the id retrieved in step 1 (Send PIN)
• nip the 6-digit NIP sent to the customer by the provided method

Example of the request:

{
   "id": "645590bf0f24ca7ebfc6580d",
   "nip": "318958"
}

Attempts

You have a total of 3 attempts to successfully validate the PIN on each run. If you exceed this number of attempts, the flow will fail immediately and you will not be able to continue validation. If you make a mistake at least once but then enter the PIN correctly, the attempt counter will be reset for the next validation.

Successful response

To learn about the fields of a successful response, please refer to the success example in the Response section.

You must run this endpoint twice. The response from both runs will be the same, but on the second run you will receive a parameter called "validated". This parameter will be a boolean true indicating that the PIN has been successfully validated.

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 an email request.
• notFound: it sends back a 400 code and no body in the not found response.
• blockedNip: it sends back an error indicating that an attempt limit was reached and that the PIN is locked
• incorrectNip: it sends back an error indicating that the 6-digit NIP is incorrect.

Possible Errors

Required Method

You will get a 400 bad request error when any of the request fields was not provided in the body.

{
  "id": "REQUIRED_FIELD_ERROR; EMPTY_ERROR; can't be empty",
  "nip": "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

{
  "id": "FORMAT_ERROR; invalid id string",
  "nip": "FORMAT_ERROR; should be only numbers"
}

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

Incorrect NIP

If a NIP is incorrect, an error code 400 will be presented with the following response

{
  "id": "645591130f24ca7ebfc65811",
  "createdAt": "2023-05-05T17:28:19.482254-06:00",
  "finishedAt": "2023-05-05T17:28:19.660262-06:00",
  "duration": 178,
  "status": "INPUT_ERROR",
  "errorMessage": "NIP Incorrecto.",
  "request": {
    "id": "645590bf0f24ca7ebfc6580d",
    "nip": "318957"
  },
  "response": {
    "attempts": [
      {
        "createdAt": "2023-05-05T17:28:19.655141-06:00",
        "nip": "318957"
      }
    ]
  }
}

NIP Blocked

If a PIN was provided incorrectly more than 3 times, the PIN is blocked and a 400 code is returned with the following error message

{
  "id": "645591130f24ca7ebfc65811",
  "createdAt": "2023-05-05T17:29:38.213487-06:00",
  "finishedAt": "2023-05-05T17:29:38.605499-06:00",
  "duration": 392,
  "status": "INPUT_ERROR",
  "errorMessage": "Limite de intentos, NIP bloqueado.",
  "request": {
    "id": "645590bf0f24ca7ebfc6580d",
    "nip": "318956"
  },
  "response": {
    "attempts": [
      {
        "createdAt": "2023-05-05T17:28:19.655141-06:00",
        "nip": "318957"
      },
      {
        "createdAt": "2023-05-05T17:28:43.108768-06:00",
        "nip": "318959"
      },
      {
        "createdAt": "2023-05-05T17:28:56.431113-06:00",
        "nip": "318953"
      }
    ]
  }
}

Previously validated NIP

You will get this error if you try to revalidate a PIN that has already been validated as successful

{
    "id": "6494f34ba63a8326b82930c6",
    "createdAt": "2023-06-23T01:40:55.953024078Z",
    "finishedAt": "2023-06-23T01:40:56.319994172Z",
    "duration": 366,
    "status": "INPUT_ERROR",
    "errorMessage": "NIP previamente validado",
    "request": {
        "id": "6494f349a63a8326b82930c2",
        "nip": "476206"
    },
    "response": {
        "attempts": [
            {
                "createdAt": "2023-06-23T01:30:14.471314278Z",
                "nip": "241183",
                "status": "fail"
            },
            {
                "createdAt": "2023-06-23T01:31:36.899681719Z",
                "nip": "476206",
                "status": "success"
            },
            {
                "createdAt": "2023-06-23T01:33:27.538067111Z",
                "nip": "476206",
                "status": "success"
            }
        ],
        "validated": true
    }
}

Next step of authentication

Executing this API step 2 and 3, the process to validate the the NIP is completed. Now you must authenticate your query to the SIC, to see how this is done in each query API, visit the documentation for the specific SIC.