Ir para o conteúdo

Guias rápidos

Como autenticar na API

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 a API.

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 em https://cliente.serpro.gov.br.

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.

2. Segundo passo - Solicite o Bearer Token e JWT Token

Para consultar as APIs, é necessário obter um token de acesso temporário (Bearer) e um JWT token. O token de acesso possui um tempo de validade e sempre que expirado, este passo de requisição de um novo token de acesso deve ser repetido.

API protegida com Certificado Digital SSL

Todo Bearer Token gerado solicitará o certificado digital (e-CNPJ nos padrões ICP Brasil). Esse certificado digital deve ser o mesmo utilizado na contratação do produto. Para utilizar o Integra Contador o Contratante deve utilizar o seu certificado junto com as credenciais da API Serpro que são disponibilizadas após contratação. A obrigatoriedade da utilização do certificado digital e-CNPJ obedece o padrão de acesso aos sistemas da Receita Federal do Brasil (RFB).

Como solicitar os Tokens de Acesso Bearer e JWT token

Para solicitar os tokens temporários, é necessário realizar uma requisição HTTP POST para o endpoint authenticate https://autenticacao.sapi.serpro.gov.br/authenticate, com as seguintes características:

a) Certificado Digital e-CNPJ padrão ICP-Brasil válido;

b) HTTP Header:

- "Authorization": "Basic (base64(consumerKey:consumerSecret))"
- "role-type": "TERCEIROS"
- "content-type": "application/x-www-form-urlencoded"

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 -i -X POST \
   -H "Authorization:Basic ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg" \
   -H "Role-Type:TERCEIROS" \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -d 'grant_type=client_credentials' \
   --cert-type P12 \
   --cert arquivo_certificado.p12:senha_certificado \
   'https://autenticacao.sapi.serpro.gov.br/authenticate'

API protegida com Certificado Digital SSL

Toda requisição de autenticação na loja do Serpro deverá ser informado o arquivo do certificado digital do tipo .p12 ou .pfx acompanhado da senha do certificado. Para executar esse script via curl, é necessário mudar para a pasta do arquivo do certificado.

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

[HEADER] Content-type: "application/x-www-form-urlencoded"

3. Terceiro passo - Receba o Token

Access token e JWT token

O retorno da autenticação será o "payload" demonstrado abaixo, com os dois tokens temporários (access_token e jwt_token) para serem utilizados no consumo dos serviços até a expiração (expires_in):

Exemplos do Json de retorno:

{
  "expires_in": 2008,
  "scope": "default",
  "token_type": "Bearer",
  "access_token": "af012866-daae-3aef-8b40-bd14e8cfac99",
  "jwt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

ou

{
  "expires_in": 2008,
  "scope": "default",
  "token_type": "Bearer",
  "access_token": "eyJ4NXQiOiJOamMyWkRabU5XWXlZVFF4T1ROaE4yVTFNell6TWpobVpEbGlaREU0WWpkaU1tVTNZV1kxTUEiLCJraWQiOiJORFUwTXpBMU1XWTJNVGxrT1RKaU1UWTFNemczT1dJeVpETXhaV1UxWlRnME0yTTBORFF4T1dWaFlUTTJOamhpWlRZd01XRTJaR0U0TnpnelpqYzRPUV9SUzI1NiIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJ1c2VydGVzdCIsImF1dCI6IkFQUExJQ0FUSU9OIiwiYXVkIjoiWEkxYVBmWXllcmVURmhLTFRuMTRXRmhOdmhJYSIsIm5iZiI6MTY3Nzg1MjAyMSwiYXpwIjoiWEkxYVBmWXllcmVURmhLTFRuMTRXRmhOdmhJYSIsInNjb3BlIjoiZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9wdWJsaXNoZXIuYXBpc2VycHJvLnNlcnByby5nb3YuYnI6NDQzXC9vYXV0aDJcL3Rva2VuIiwicmVhbG0iOnsic2lnbmluZ190ZW5hbnQiOiJjYXJib24uc3VwZXIifSwiZXhwIjoxNjc3ODU1NjIxLCJpYXQiOjE2Nzc4NTIwMjEsImp0aSI6ImM0OWM1NWVjLWU4YjEtNGFiNi05YThiLTdhZDEzMTFkNjA0NSJ9.U11tZXy6XoT64AMMCUdMd5Yv8j9q5fzNKwnRT89R_expGIY_PPh3vRyckaqcW6NHWklMHMIgDbDJ-wKeoLWrBHW4F4Z_f8v-zXAlLduoqtJv55x7sjr2cevP4_hHqRTARX-lbK7Mx3MmChLWkNZN_DQ-DJjaXbczxIv6u7YgNdlVJ6jHm7TYPv8iRl4qV7x8KNFTP4H6JfWQQQaSO15AGJsLJ83X8PNQHnjmcFDecd_05IYEpTrTXb9eAQbFNu90ZziWpx0rmDB3wtd_OutnpDgQO8JTtbmhREzjB1wbrqHzqa4O1Qo-3DnQKkZhE5bvzM-lJHTbxnX6NRYsJ8ehrQ",
  "jwt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Renovação do access token e JWT token

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 Segundo Passo Solicite o Bearer Token e JWT Token) para uma nova autenticação.

4. Quarto passo - Fazendo uma requisição

De posse dos access_token e jwt_token, faça a requisição a API.

curl -i -X POST \
   -H "Authorization:Bearer af012866-daae-3aef-8b40-bd14e8cfac99" \
   -H "Content-Type:application/json" \
   -H "jwt_token:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" \
   -d \
'{
  "contratante": {
    "numero": "00000000000000",
    "tipo": 2
  },
  "autorPedidoDados": {
    "numero": "00000000000000",
    "tipo": 2
  },
  "contribuinte": {
    "numero": "00000000000000",
    "tipo": 2
  },
  "pedidoDados": {
    "idSistema": "PGDASD",
    "idServico": "CONSEXTRATO16",
    "versaoSistema": "1.0",
    "dados": "{ \"numeroDas\": \"99999999999999999\" }"
  }  
}' \
 'https://gateway.apiserpro.serpro.gov.br/integra-contador/v1/Consultar'

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 f4fb70c9-83d8-3996-9e7c-e481d8200527
    Informamos o token de acesso recebido

  • [HEADER] jwt_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiO... Informamos um jwt token válido retornado na autenticação via SAPI.

  • [POST] https://gateway.apiserpro.serpro.gov.br/integra-contador/v1/Consultar Chamamos a url da API e o método desejado. No caso, a url base é "https://gateway.apiserpro.serpro.gov.br/integra-contador/v1/", e o método é "Consultar/.

  • [BODY]: Neste exemplo a requisição está ocorrendo no sistema PGDASD no serviço Consulta Extrato do DAS. Vide a sessão Documentação/Integra Contador para mais detalhes de cada solução disponível para consumo.

Exemplo do body para envio no post:

{
  "contratante": {
    "numero": "00000000000000",
    "tipo": 2
  },
  "autorPedidoDados": {
    "numero": "00000000000000",
    "tipo": 2
  },
  "contribuinte": {
    "numero": "00000000000000",
    "tipo": 2
  },
  "pedidoDados": {
    "idSistema": "PGDASD",
    "idServico": "CONSEXTRATO16",
    "versaoSistema": "1.0",
    "dados": "{ \"numeroDas\": \"99999999999999999\" }"
  }  
}

Exemplo de resposta esperada:

{
  "contratante": {
    "numero": "string",
    "tipo": number
  },
  "autorPedidoDados": {
    "numero": "string",
    "tipo": number
  },
  "contribuinte": {
    "numero": "string",
    "tipo": number
  },
  "pedidoDados": {
    "idSistema": "string",
    "idServico": "string",
    "versaoSistema": "string",
    "dados": "string"
  },
  "status": number,
  "dados": "string",
  "mensagens": [{
    "codigo": "string",
    "texto": "string"
  }]
 }