Guias rápidos

Gateway Descontinuado

Este guia contém URLs do Gateway (apigateway.serpro.gov.br) que será descontinuado (Deprecated) em breve. Recomendamos a utilização do guia com o Gateway atualizado.

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 um tempo de validade e sempre que expirado, este passo de requisição de um novo token de acesso deve ser repetido.

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://apigateway.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" \
-H "Authorization: Basic ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg" \
https://apigateway.serpro.gov.br/token

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.

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": "am_application_scope default", 
    "token_type": "Bearer", 
    "expires_in": 3295, 
    "access_token": "c66a7def1c96f7008a0c397dc588b6d7"
}

Renovação do Token de Acesso

Atentar que sempre que o token de acesso temporário expirar, o gateway vai retornar um HTTP CODE 401 após realizar uma requisição para uma API. Neste caso, deve ser repetido o passo anteriormente descrito no Segundo Passo Como solicitar o Token de Acesso (Bearer) para geração de um novo token de acesso temporário.

4. Quarto passo - Fazendo uma requisiçã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://apigateway.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\"}}"

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 4e1a1858bdd584fdc077fb7d80f39283
Informamos o token de acesso recebido
[BODY] JSON contendo os dados a serem verificados

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

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