Quick start
How to authenticate with Datavalid
The APIs provided by SERPRO utilize the OAuth2 protocol for authentication and access authorization of the contracted APIs. Follow the steps below to authenticate and use Datavalid.
1. First step - Get Consumer Key and Consumer Secret
To use the APIs, you need to obtain the two codes (Consumer Key and Consumer Secret) provided in the Customer Area. These codes serve to identify the contract. Access credentials can be obtained from the Serpro customer's area.
Examples:
Consumer Key: djaR21PGoYp1iyK2n2ACOH9REdUb
Consumer Secret: ObRsAJWOL4fv2Tp27D1vd8fB3Ote
Important notice
Your Consumer Key and Consumer Secret serve as identification for both you, the user, and your contract with SERPRO. Keep this information secure.
2. Second step - Request the Bearer Token
To query the APIs, you need to acquire a temporary access token (Bearer). This token has 1 hour of expiration time and, once expired, you must repeat the step of requesting a new access token.
How to request the Access Token (Bearer)
To request the temporary token, you need to make an HTTP POST request to the Token endpoint at https://gateway.apiserpro.serpro.gov.br/token. In the HTTP Header Authorization, you should provide the access credentials (consumerKey:consumerSecret) in Base64 format.
Here is an example:
[HEAD] Authorization: Basic base64(Consumer Key:Consumer Secret)
[HEAD] Content-Type: application/x-www-form-urlencoded
[POST] grant_type=client_credentials
To use in the Authorization parameter, you need to combine the Consumer Key and Consumer Secret codes using a ":" as the separator. Then, convert the resulting string to BASE64. In the following example, the string ZGphUjIx[...]IzT3RlCg is returned:
echo -n "djaR21PGoYp1iyK2n2ACOH9REdUb:ObRsAJWOL4fv2Tp27D1vd8fB3Ote" | base64
Result:
ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg
Examples:
curl -k -d "grant_type=client_credentials" \
--header "Authorization: Basic ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg" \
--header "Content-Type: application/x-www-form-urlencoded" \
https://gateway.apiserpro.serpro.gov.br/token
// NodeJs - Request
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://gateway.apiserpro.serpro.gov.br/token',
'headers': {
'Authorization': 'Basic ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg',
'Content-Type': 'application/x-www-form-urlencoded'
},
form: {
'grant_type': 'client_credentials'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
// Java - Unirest
Unirest.setTimeouts(30000, 10000);
HttpResponse<String> response = Unirest.post("https://gateway.apiserpro.serpro.gov.br/token")
.header("Authorization", "Basic ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg")
.header("Content-Type", "application/x-www-form-urlencoded")
.field("grant_type", "client_credentials")
.asString();
<?php
# PHP cURL
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://gateway.apiserpro.serpro.gov.br/token',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => 'grant_type=client_credentials',
CURLOPT_HTTPHEADER => array(
'Authorization: Basic ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg',
'Content-Type: application/x-www-form-urlencoded'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Content-Type
If you experience "415 Unsupported Media Type" errors in the Token request call, use the "Content-Type" header field with the value "application/x-www-form-urlencoded"
[HEAD] Content-Type: "application/x-www-form-urlencoded"
3. Third step - Receive the Token
Following the preceding step, the API access token will be included in the access_token portion of the JSON response from the endpoint. This token should be informed in the next steps. Be mindful of the expiration time of the access token.
Receive the Token
As a result, the endpoint will report the API access token in the "access_token" field of the returned JSON message. This token should be informed in the next steps.
{
"scope": "am_application_scope default",
"token_type": "Bearer",
"expires_in": 3295,
"access_token": "c66a7def1c96f7008a0c397dc588b6d7"
}
Important Notice
If you got started before February 12th, 2023, you'll continue to receive 40 character tokens.
Renewal of the Access Token
The access token has a validity of one (1) hour. It is recommended to generate an access token once per hour. Continue using the access token until the gateway returns an HTTP CODE 401 after making a request to an API. To renew the token, simply follow the second step on How to request the Access Token (Bearer).
4. Fourth step - Making a request
How to activate Datavalid V3
Datavalid V3 has been launched and includes essential improvements. Follow this link to find out how to have access to this new version.
Using the APIs
With the Access Token in hand, you can now proceed to make a request to one of the services, such as the Datavalid Demo API.
curl -X POST "https://gateway.apiserpro.serpro.gov.br/datavalid-demonstracao/v2/validate/pf" \
-H "Accept: application/json" \
-H "Authorization: Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e" \
-H "Content-Type: application/json" \
-d "{\"key\":{\"cpf\":\"25774435016\"},\"answer\":{\"nome\":\"João\",\"sexo\":\"M\",\"nacionalidade\":1,\"filiacao\":{\"nome_mae\":\"Mãe do João\",\"nome_pai\":\"Pai do João\"},\"documento\":{\"tipo\":1,\"numero\":\"000001\",\"orgao_expedidor\":\"SSP\",\"uf_expedidor\":\"DF\"},\"endereco\":{\"logradouro\":\"Nome do Logradouro\",\"numero\":\"0007\",\"complemento\":\"APTO 2015\",\"bairro\":\"Nome do Bairro\",\"cep\":\"0000001\",\"municipio\":\"Nome do municipio\",\"uf\":\"DF\"},\"cnh\":{\"categoria\":\"AB\",\"numero_registro\":\"0000001\",\"data_primeira_habilitacao\":\"2000-10-31\",\"data_validade\":\"2005-12-10\",\"registro_nacional_estrangeiro\":\"123456\",\"data_ultima_emissao\":\"2000-10-01\",\"codigo_situacao\":\"3\"},\"data_nascimento\":\"2001-01-01\",\"situacao_cpf\":\"regular\"}}"
//NodeJs - Request
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://gateway.apiserpro.serpro.gov.br/datavalid-demonstracao/v2/validate/pf',
'headers': {
'Content-Type': 'application/json',
'Authorization': 'Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e',
'Accept': 'application/json'
},
body: JSON.stringify({
"key": {
"cpf": "25774435016"
},
"answer": {
"nome": "João",
"sexo": "M",
"nacionalidade": 1,
"filiacao": {
"nome_mae": "Mãe do João",
"nome_pai": "Pai do João"
},
"documento": {
"tipo": 1,
"numero": "000001",
"orgao_expedidor": "SSP",
"uf_expedidor": "DF"
},
"endereco": {
"logradouro": "Nome do Logradouro",
"numero": "0007",
"complemento": "APTO 2015",
"bairro": "Nome do Bairro",
"cep": "0000001",
"municipio": "Nome do municipio",
"uf": "DF"
},
"cnh": {
"categoria": "AB",
"numero_registro": "0000001",
"data_primeira_habilitacao": "2000-10-31",
"data_validade": "2005-12-10",
"registro_nacional_estrangeiro": "123456",
"data_ultima_emissao": "2000-10-01",
"codigo_situacao": "3"
},
"data_nascimento": "2001-01-01",
"situacao_cpf": "regular"
}
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
//Java - Unirest
Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://gateway.apiserpro.serpro.gov.br/datavalid-demonstracao/v2/validate/pf")
.header("Content-Type", "application/json")
.header("Authorization", "Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e")
.header("Accept", "application/json")
.body("{\n \"key\": {\n \"cpf\": \"25774435016\"\n },\n \"answer\": {\n \"nome\": \"João\",\n \"sexo\": \"M\",\n \"nacionalidade\": 1,\n \"filiacao\": {\n \"nome_mae\": \"Mãe do João\",\n \"nome_pai\": \"Pai do João\"\n },\n \"documento\": {\n \"tipo\": 1,\n \"numero\": \"000001\",\n \"orgao_expedidor\": \"SSP\",\n \"uf_expedidor\": \"DF\"\n },\n \"endereco\": {\n \"logradouro\": \"Nome do Logradouro\",\n \"numero\": \"0007\",\n \"complemento\": \"APTO 2015\",\n \"bairro\": \"Nome do Bairro\",\n \"cep\": \"0000001\",\n \"municipio\": \"Nome do municipio\",\n \"uf\": \"DF\"\n },\n \"cnh\": {\n \"categoria\": \"AB\",\n \"numero_registro\": \"0000001\",\n \"data_primeira_habilitacao\": \"2000-10-31\",\n \"data_validade\": \"2005-12-10\",\n \"registro_nacional_estrangeiro\": \"123456\",\n \"data_ultima_emissao\": \"2000-10-01\",\n \"codigo_situacao\": \"3\"\n },\n \"data_nascimento\": \"2001-01-01\",\n \"situacao_cpf\": \"regular\"\n }\n}")
.asString();
//PHP - HTTP_Request2
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://gateway.apiserpro.serpro.gov.br/datavalid-demonstracao/v2/validate/pf');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Type' => 'application/json',
'Authorization' => 'Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e',
'Accept' => 'application/json'
));
$request->setBody('{\n "key": {\n "cpf": "25774435016"\n },\n "answer": {\n "nome": "João",\n "sexo": "M",\n "nacionalidade": 1,\n "filiacao": {\n "nome_mae": "Mãe do João",\n "nome_pai": "Pai do João"\n },\n "documento": {\n "tipo": 1,\n "numero": "000001",\n "orgao_expedidor": "SSP",\n "uf_expedidor": "DF"\n },\n "endereco": {\n "logradouro": "Nome do Logradouro",\n "numero": "0007",\n "complemento": "APTO 2015",\n "bairro": "Nome do Bairro",\n "cep": "0000001",\n "municipio": "Nome do municipio",\n "uf": "DF"\n },\n "cnh": {\n "categoria": "AB",\n "numero_registro": "0000001",\n "data_primeira_habilitacao": "2000-10-31",\n "data_validade": "2005-12-10",\n "registro_nacional_estrangeiro": "123456",\n "data_ultima_emissao": "2000-10-01",\n "codigo_situacao": "3"\n },\n "data_nascimento": "2001-01-01",\n "situacao_cpf": "regular"\n }\n}');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}
In the example above the following parameters were used:
- [HEADER] Accept: application/json
We indicate the type of data we are requesting, in this case, JSON.
- [HEADER] Authorization: Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e
We will inform you about the received access token.
- [HEADER] Content-Type: application/json
We specify the type of data we are sending, which in this case is JSON.
- [BODY] JSON containing the data to be checked
Example of Json sent in body:
{
"key": {
"cpf": "25774435016"
},
"answer": {
"nome": "João",
"sexo": "M",
"nacionalidade": 1,
"filiacao": {
"nome_mae": "Mãe do João",
"nome_pai": "Pai do João"
},
"endereco": {
"logradouro": "Nome do Logradouro",
"numero": "0007",
"complemento": "APTO 2015",
"bairro": "Nome do Bairro",
"cep": "0000001",
"municipio": "Nome do municipio",
"uf": "DF"
},
"cnh": {
"categoria": "AB",
"numero_registro": "0000001",
"data_primeira_habilitacao": "2000-10-31",
"data_validade": "2005-12-10",
"registro_nacional_estrangeiro": "123456",
"data_ultima_emissao": "2000-10-01",
"codigo_situacao": "3"
},
"data_nascimento": "2001-01-01",
"situacao_cpf": "regular"
}
}
- [POST] https://gateway.apiserpro.serpro.gov.br/datavalid-demonstracao/v2/validate/pf
We make a call to the API URL and specify the desired method. In this case, the base URL is "https://gateway.apiserpro.serpro.gov.br/datavalid-demonstracao/v2/", and the method is "validate/pf".
Example of expected response:
{
"nome": false,
"sexo": false,
"nacionalidade": true,
"filiacao": {
"nome_mae": false,
"nome_mae_similaridade": 0.4545454545454546,
"nome_pai": false,
"nome_pai_similaridade": 0.09090909090909094
},
"cnh": {
"nome": false,
"categoria": true,
"nome_similaridade": 0.15384615384615385,
"numero_registro": false,
"data_primeira_habilitacao": false,
"data_validade": false,
"registro_nacional_estrangeiro": true,
"data_ultima_emissao": false
},
"documento": {
"tipo": true,
"numero": true,
"numero_similaridade": 1,
"orgao_expedidor": true,
"uf_expedidor": true
},
"endereco": {
"logradouro": false,
"numero": false,
"bairro": false,
"cep": false,
"uf": false,
"logradouro_similaridade": 0.05555555555555558,
"numero_similaridade": 0,
"bairro_similaridade": 0.2142857142857143
},
"cpf_disponivel": true,
"nome_similaridade": 0.15384615384615385,
"situacao_cpf": true
}
IMPORTANT
The above API query call is for demonstration only. The available APIs and their respective URLs (endpoints) for use are found in the API Reference. These URLs can be accessed by referring to the documentation of their respective OpenAPI Specifications (OAS).
How to use the Datavalid Demo
Datavalid Demo serves as a test environment for Datavalid. It allows users to experiment with the API's features using sample data (Mock). Its purpose is to provide a practical demonstration of the API's functionality. To use it:
- Access the Datavalid Demo
- Choose the method (endpoint) to test
- Click on Try it Out
- Enter the headers you want and/or change the content of the request body
- Click Run
How to find what can be validated
The Datavalid API Reference is available in OAS/Swagger, which is a commonly used standard for API documentation. See below for details on possible validation fields.
1. Navigate to the API Reference
2. Locate the desired method
3. Click on this method and locate the "Request Body" section
4. Locate the "Schema" tab
5. Find the details of the data fields
At the deepest level of the fields, you can find the data type and domains of certain fields, if applicable.
You can find the same information regarding the response fields in the "Response" section, rather than the Request Body.