Quick start

How to authenticate with Datavalid

The APIs provided by the API SERPRO platform use the OAuth2 protocol to perform the authentication and access authorization of the contracted APIs. Follow the steps below to authenticate yourself and use Datavalid.

1. First step - Get Consumer Key and Consumer Secret

To consume the APIs, you must use the two codes (Consumer Key and Consumer Secret) available in the Client Area. These codes are used to identify the contract. Access credentials must be obtained from the Serpro customer's area.

Code examples:

Consumer Key: djaR21PGoYp1iyK2n2ACOH9REdUb   
Consumer Secret: ObRsAJWOL4fv2Tp27D1vd8fB3Ote

Important Warning

Consumer Key and Consumer Secret identify their user and their contract with SERPRO. Keep this information safe and secure.

2. Second step - Request the Bearer Token

To consult the APIs, it is necessary to obtain a temporary access token (Bearer). This token has one (1) hour of expiraton time and whenever it expires, this step of requesting a new access token must be repeated.

How to request the Access Token (Bearer)

To request the temporary token, it is necessary to make an HTTP POST request to the Token endpoint https://gateway.apiserpro.serpro.gov.br/token, informing the access credentials (consumerKey: consumerSecret) in HTTP Header Authorization, in base64 format, as in the example below.

[HEAD] Authorization: Basic base64(Consumer Key:Consumer Secret) 
[HEAD] Content-Type: application/x-www-form-urlencoded 
[POST] grant_type=client_credentials

In order to request the Access Token, it is necessary to concatenate the Consumer Key and Consumer Secret codes, separated by the character ":", and convert the result to BASE64.
In the following example, the string ZGphUjIx[...]IzT3RlCg is returned:

echo -n "djaR21PGoYp1iyK2n2ACOH9REdUb:ObRsAJWOL4fv2Tp27D1vd8fB3Ote" | base64

Result:

ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg

The example below is a call via cUrl:

curl -k -d "grant_type=client_credentials" \
-H "Authorization: Basic ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg" \
https://gateway.apiserpro.serpro.gov.br/token

Content-Type

If you are facing "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

As a result of the previous step, the endpoint will inform the API access token, in the access_token field of the json return message. This token must be informed in the next steps. Pay attention to the Access Token renewal time.

Receive the Token

As a result, the endpoint will inform the API access token, in the access_token field of the return json message. This token must be informed in the next steps.

{
    "scope": "am_application_scope default", 
    "token_type": "Bearer", 
    "expires_in": 3295, 
    "access_token": "c66a7def1c96f7008a0c397dc588b6d7"
}

Access Token Renewal

The access token has one (1) hour of lifetime. It is recommended to generate an access token per hour. Use the access token until the gateway returns an HTTP CODE 401 after making a request to an API. For token renewal, the Second Step must be repeated How to request the Access Token (Bearer).

4. Fourth step - Making a request

Querying the APIs

With the Access Token, make the request to one of the services, for example 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 4e1a1858bdd584fdc077fb7d80f39283" \
-H "Content-Type: application/json" \
-d "{\"key\":{\"cpf\":\"33840981026\"},\"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\"}}"

In the example above, the following parameters were used:

[HEADER] Accept: application/json
We inform the type of data we are requesting, in this case JSON
[HEADER] Authorization: Bearer 4e1a1858bdd584fdc077fb7d80f39283
We inform you of the received access token
[HEADER] Content-Type: application/json
We inform the type of data we are sending, in this case JSON
[BODY] JSON containing the data to be verified

Example of Json sent in the body:

{
    "key": {
        "cpf": "33840981026"
    },
    "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 call the API url and 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 purposes only. The available APIs and their respective URLs (endpoints) for consumption are made available (through the documentation of their respective OAS) in the API Reference.

How to use the Datavalid Demo

Datavalid Demo is the test environment of Datavalid with sample data (Mock), with the objective of demonstrating the functioning of the API. To use it:

Access the Datavalid Demo
Choose the method (endpoint) to test
Click Try it Out
Insert the headers you want and/or change the content of the request body
Click Execute