Ir para o conteúdo

Quick Guides

How to authenticate with the CPF Query API

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 consume the CPF Api.

1. Step One - Get Consumer Key e Consumer Secret

To consume the APIs, you must use both codes (Consumer Key e Consumer Secret) available in the Client Area. These codes are used to identify the contract. Access credentials must be obtained from the área do cliente Serpro.

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 protected.

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 shown below.

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

For use in the * Authorization * parameter, 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 is returned ZGphUjIx[...]IzT3RlCg:

echo -n "djaR21PGoYp1iyK2n2ACOH9REdUb:ObRsAJWOL4fv2Tp27D1vd8fB3Ote" | base64

Result:

ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg

Below is an example of 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 experience errors"415 Unsupported Media Type" 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. Step four - Making a request

Querying the APIs

In possession of the Access Token, make the request to the CPF Trial API.

curl -X GET "https://gateway.apiserpro.serpro.gov.br/consulta-cpf-df-trial/v1/cpf/40442820135" \
-H "accept: application/json" \
-H "Authorization: Bearer 4e1a1858bdd584fdc077fb7d80f39283" \

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 the access token received

  • [GET] https://gateway.apiserpro.serpro.gov.br/consulta-cpf-df-trial/api/v1/cpf/40442820135
    We call the API url and the desired method. In this case, the base url is "https://gateway.apiserpro.serpro.gov.br/consulta-cpf-df-trial/v1/”, and the method is the "cpf/40442820135".

Example of expected response:

{
    "ni":"40442820135",
    "nome":"Nome do CPF 404.428.201-35",
    "situacao": {
        "codigo":"0",
        "descricao":"Regular"
    },
    "nascimento":"14111970"
}

IMPORTANT

The CPF Trial API query above is for demonstration purposes only. The available APIs and their respective URLs (endpoints) for consumption are made available (through the documentation of their respective swaggers) in the section API Reference. The gateway deals with the upper and lower case letters differently. Be sure to send the endpoints according to API Reference without changing to uppercase or lowercase any part of the endpoint.

How to use the CPF Demo API

API CPF Demo is the testing environment of the CPF API, with sample data (Mock), in order to demonstrate the API's operation. To use it:

  1. Access the CPF Demo API
  2. Choose the method (endpoint) to test
  3. click in Try it Out
  4. Insert the headings you want and/or change the content of the request body
  5. click in Execute

Test data

To test the Trial environment, use one of the fictional CPF listed below.

CPF Registration Situation
40442820135 Regular CPF
63017285995 Regular CPF
91708635203 Regular CPF
58136053391 Regular CPF
40532176871 Suspended
47123586964 Suspended
07691852312 Regularization Pending
10975384600 Regularization Pending
01648527949 Canceled by Multiplicity
47893062592 Canceled by Multiplicity
98302514705 Null
18025346790 Null
64913872591 Canceled Craft
52389071686 Canceled Craft
05137518743 Deceased Holder
08849979878 Deceased Holder