troyam / api-siafi

API SIAFI

API para acesso ao Cadastro de Pessoas Físicas diretamente das bases da Receita Federal do Brasil.

A plataforma APIGOV (Plataforma que contempla todas as API's disponibilizadas e comercializadas pelo SERPRO) utiliza o protocolo Oauth2 - Client Credential Grant (https://tools.ietf.org/html/rfc6749#section-4.4) para realizar a autenticação e autorização de acesso para consumo das API's contratadas, conforme figura abaixo:

Como fazer consultas a API SIAFI

Para consumir a API SIAFI, 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 e deverão ser informados sempre que uma consulta for realizada. Exemplos de códigos:

Consumer Key: uldY78ZMvYm4btC0x3XZLG7ZTsYa

Consumer Secret: WyUeBFCUK7wu1Ko61V7bb7yB2Uoa

1 – Como solicitar o Token de Acesso (Bearer)

Para consultar a API, é 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.

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. As credenciais de acesso devem ser obtidas a partir do portal do cliente Serpro - https://minhaconta.serpro.gov.br

[HEAD] Authorization: Basic base64(Consumer Key:Consumer Secret)

Abaixo segue um exemplo de chamada via cUrl:

curl -k -d "grant_type=client_credentials" -H "Authorization: Basic dWxkWTc4Wk12WW00YnRDMHgzWFpMRzdaVHNZYTpXeVVlQkZDVUs3d3UxS282MVY3YmI3eUIyVW9h" https://apigateway.serpro.gov.br/token

A chave informada no exemplo acima "dWxkWTc4Wk12WW00YnRDMHgzWFpMRz daVHNZYTpXeVVlQkZDVUs3d3UxS282MVY3YmI3eUIyVW9h" é resultado do BASE64 dos códigos Consumer Key e Consumer Secret separados pelo caracter “:”, conforme exemplo a seguir:

base64(uldY78ZMvYm4btC0x3XZLG7ZTsYa:WyUeBFCUK7wu1Ko61V7bb7yB2Uoa)

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 anterior (Como solicitar o Token de Acesso (Bearer)) para geração de um novo token de acesso temporário.

2 – Como realizar a consulta à API

De posse do Token de Acesso (Bearer), faça uma requisição via GET ao gateway informando os parâmetros da API. Exemplo:

curl -X GET --header "Accept: application/json" --header "Authorization: Bearer c66a7de41c96f7008a0c397dc588b6d7" "https://apigateway.serpro.gov.br/api-siafi/1.0/ne/consultar"

No exemplo acima foram utilizados os seguintes parametros:

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

[HEADER] Authorization: Bearer c66a7de41c96f7008a0c397dc588b6d7 - Informamos o token de acesso recebido

[GET] https://apigateway.serpro.gov.br/consulta-cpf/v1/cpf/99999999999: chamamos a url da API informando o CPF. No caso a url é "consulta-cpf/v1/cpf/{numero do CPF}"

Nesse caso, espera-se que a resposta seja a seguinte:

{
  "ni": "91708635203", 
  "nome": "Nome do CPF 917.086.352-03", 
  "nascimento": "01011975", 
  "situacao": {
    "codigo" : "0", 
    "descricao" : "Regular"
  }
}