Ir para o conteúdo

Guias rápidos

Como autenticar no Datavalid

As APIs disponibilizadas pela plataforma API SERPRO utilizam o protocolo OAuth2 para realizar a autenticação e autorização de acesso das APIs contratadas. Siga os passos abaixo para se autenticar e consumir o Datavalid.

1. Primeiro passo - Obtenha Consumer Key e Consumer Secret

Para consumir as APIs, você deverá utilizar os dois códigos (Consumer Key e Consumer Secret) disponibilizados na Área do Cliente. Esses códigos servem para identificar o contrato. As credenciais de acesso devem ser obtidas a partir da área do cliente Serpro.

Exemplos de códigos: 

Consumer Key: djaR21PGoYp1iyK2n2ACOH9REdUb   
Consumer Secret: ObRsAJWOL4fv2Tp27D1vd8fB3Ote

Aviso importante

O Consumer Key e Consumer Secret identificam seu usuário e seu contrato com o SERPRO. Mantenha essas informações protegidas de forma segura.

2. Segundo passo - Solicite o Bearer Token

Para consultar as APIs, é necessário obter um token de acesso temporário (Bearer). Esse token possui uma (1) hora de validade e, sempre que expirado, repita este passo de requisição de um novo token de acesso

Como solicitar o Token de Acesso (Bearer)

Para solicitar o token temporário é necessário realizar uma requisição HTTP POST para o endpoint Token https://gateway.apiserpro.serpro.gov.br/token, informando as credenciais de acesso (consumerKey:consumerSecret) no HTTP Header Authorization, no formato base64, conforme exemplo abaixo. 

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

Para utilização no parâmetro Authorization, é necessário concatenar os códigos Consumer Key e Consumer Secret, separados pelo caracter ":", e converter o resultado em BASE64. No exemplo a seguir, é retornada a string ZGphUjIx[...]IzT3RlCg:

echo -n "djaR21PGoYp1iyK2n2ACOH9REdUb:ObRsAJWOL4fv2Tp27D1vd8fB3Ote" | base64

Resultado:

ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg

Abaixo segue um exemplo de chamada via cUrl:

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

Caso experiencie erros de "415 Unsupported Media Type" na chamada de solicitação do Token, utilize o campo do Header "Content-Type" com o valor "application/x-www-form-urlencoded"

[HEAD] Content-Type: "application/x-www-form-urlencoded"

3. Terceiro passo - Receba o Token

Como resultado do passo anterior, o endpoint informará o token de acesso a API, no campo access_token da mensagem json de retorno. Este token deve ser informado nos próximos passos. Fique atento ao tempo de renovação do Token de acesso.

Receba o Token

Como resultado, o endpoint informará o token de acesso a API, no campo access_token da mensagem json de retorno. Este token deve ser informado nos próximos passos.

{
  "scope": "default",
  "token_type": "Bearer",
  "expires_in": 3295,
  "access_token": "eyJ4NXQiO<<TOKEN_DE_1500_CARACTERES>>YzjB1wbrqHzqa4O1Qo-3DnQKkZhE5bvzM-lJHTbxnX6NRYsJ8ehrQ"
}

Observação

Os clientes que contrataram antes de 12/02/2023 continuarão recebendo token de 40 caracteres.

Renovação do Token de Acesso

O token de acesso possui 1h (uma hora) de validade. Recomenda-se gerar um token de acesso por hora. Utilize o token de acesso até o momento que o gateway retorne um HTTP CODE 401 após realizar uma requisição para uma API. Para renovação do token, repita o Segundo Passo Como solicitar o Token de Acesso (Bearer).

4. Quarto passo - Fazendo uma requisição

Como ativar o Datavalid V3

O Datavalid V3 está disponível e traz evoluções muito relevantes para seu negócio. Clique aqui e saiba o que fazer para ativar o acesso a esta nova versão.

Realizando consulta às APIs

De posse do Token de Acesso, faça a requisição a um dos serviços, por exemplo da API Datavalid Demonstração. 

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();
}

No exemplo acima foram utilizados os seguintes parâmetros:

  • [HEADER] Accept: application/json
    Informamos o tipo de dados que estamos requerendo, nesse caso JSON

  • [HEADER] Authorization: Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e
    Informamos o token de acesso recebido

  • [HEADER] Content-Type: application/json
    Informamos o tipo de dados que estamos enviando, nesse caso JSON

  • [BODY] JSON contendo os dados a serem verificados

Exemplo de Json enviado no 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"
        },
        "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"
    }
}
  • [POST] https://gateway.apiserpro.serpro.gov.br/datavalid-demonstracao/v2/validate/pf
    Chamamos a url da API e o método desejado. No caso, a url base é "https://gateway.apiserpro.serpro.gov.br/datavalid-demonstracao/v2/”, e o método é o "validate/pf".

Exemplo de resposta esperada:

{
"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
}

IMPORTANTE

A chamada à consulta da API acima é apenas para demonstração. As APIs disponíveis e suas respectivas URLs (endpoints) para consumo são disponibilizadas (através da documentação dos seus respectivos OAS) na seção Referência da API.

Como utilizar o Datavalid Demonstração

Datavalid Demonstração é o ambiente de testes do Datavalid com dados de exemplo (Mock), com objetivo de demonstrar o funcionamento da API. Para utilizá-lo:

  1. Acesse o Datavalid Demonstração
  2. Escolha o método (endpoint) a testar
  3. Clique em Try it Out
  4. Insira os cabeçalhos que desejar e/ou altere o conteúdo do corpo da requisição
  5. Clique em Execute

Acesse o Datavalid Demonstração

Como encontrar os campos disponíveis para validação

A Referência da API do Datavalid é disponibilizada em OAS/Swagger, um padrão bastante utilizado de documentação de APIs. Veja abaixo como buscar os detalhes sobre os campos possíveis de validação.

1. Navegue até a Referência da API

Campos para validação 1

2. Localize o método desejado

Campos para validação 2

3. Clique neste método e localize o trecho "Request Body"

Campos para validação 3

4. Localize a aba "Schema"

Campos para validação 4

5. Encontre o detalhamento dos campos de dados

No nível mais interno dos campos, é possível encontrar o tipo de dado e domínios de alguns campos quando aplicável.

Campos para validação 5

É possível ver também o mesmo detalhamento também para os campos de resposta, basta ver a seção "Response" em vez de Request Body.