Ir para o conteúdo

Guías rápidas

Cómo autenticarse con la API de consulta CPF

Las API proporcionadas por la plataforma API SERPRO utilizan el protocolo OAuth2 para realizar la autenticación y autorización de acceso de las API contratadas. Siga los pasos a continuación para autenticar y consumir esta API.

1. Primer paso: obtener la clave del consumidor y el secreto del consumidor

Para consumir las API, debe usar los dos códigos (Clave del consumidor y Secreto del consumidor) disponibles en el Área del cliente. Estos códigos se utilizan para identificar el contrato. Las credenciales de acceso deben obtenerse deÁrea de clientes Serpro.

Ejemplos de código: 

Consumer Key: djaR21PGoYp1iyK2n2ACOH9REdUb   
Consumer Secret: ObRsAJWOL4fv2Tp27D1vd8fB3Ote

Aviso importante

Consumer Key y Consumer Secret identifican a su usuario y su contrato con SERPRO. Mantenga esta información protegida.

2. Segundo paso: solicitar el token de portador

Para consultar las APIs, es necesario obtener un token de acceso temporal (Portador). Este token tiene una (1) hora de caducidad y siempre que caduque, este paso de solicitar un nuevo token de acceso debe repetirse.

Cómo solicitar el token de acceso (portador)

Para solicitar el token temporal, es necesario realizar una solicitud HTTP POST al punto final del token https://gateway.apiserpro.serpro.gov.br/token, informar las credenciales de acceso (consumerKey: consumerSecret) en la Autorización de encabezado HTTP, en formato base64, como se muestra a continuación.

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

Para usar en el parámetro * Autorización , es necesario concatenar los códigos de Consumer Key e Consumer Secret, separados por el carácter ":", y convertir el resultado a BASE64. En el siguiente ejemplo, se devuelve la cadena ZGphUjIx[...]IzT3RlCg*:

echo -n "djaR21PGoYp1iyK2n2ACOH9REdUb:ObRsAJWOL4fv2Tp27D1vd8fB3Ote" | base64

Resultado:

ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg

A continuación se muestra un ejemplo de una llamada a través de cUrl:

curl -k -d "grant_type=client_credentials" \
-H "Authorization: Basic ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg" \
https://gateway.apiserpro.serpro.gov.br/token

Content-type

Si experimenta errores "415 Unsupported Media Type" en la llamada de solicitud de token, use el Header "Content-Type" con el valor "application/x-www-form-urlencoded"

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

3. Tercer paso: recibir el token

Como resultado del paso anterior, el endpoint informará el token de acceso a la API, en el campo access_token del mensaje de retorno json. Este token debe informarse en los próximos pasos. Preste atención al tiempo de renovación del token de acceso.

Recibe el token

Como resultado, el punto final informará al token de acceso API, en el campo access_token del mensaje de retorno json. Este token debe ser informado en los próximos pasos.

{
    "scope": "am_application_scope default", 
    "token_type": "Bearer", 
    "expires_in": 3295, 
    "access_token": "c66a7def1c96f7008a0c397dc588b6d7"
}

Renovación de token de acceso

El token de acceso tiene una (1) hora de caducidad. Se recomienda generar un token de acceso por hora. Utilice el token de acceso hasta que la puerta de enlace devuelva un CÓDIGO HTTP 401 después de realizar una solicitud a una API. Para la renovación del token, repita el segundo paso Cómo solicitar el token de acceso (portador).

4. Paso cuatro: hacer una solicitud

Consultando las API

En posesión del token de acceso, realice la solicitud a la API de prueba de CPF. 

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

En el ejemplo anterior, se usaron los siguientes parámetros:

  • [HEADER] Accept: application/json
    Informamos el tipo de datos que estamos solicitando, en este caso JSON

  • [HEADER] Authorization: Bearer 4e1a1858bdd584fdc077fb7d80f39283
    Informamos el token de acceso recibido

  • [GET] https://gateway.apiserpro.serpro.gov.br/consulta-cpf-df-trial/api/v1/cpf/40442820135
    Llamamos a la URL del API y al método deseado. En este caso, la url base es "https://gateway.apiserpro.serpro.gov.br/consulta-cpf-df-trial/v1/”, y el método es el "cpf/40442820135".

Ejemplo de respuesta esperada:

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

IMPORTANTE

La consulta de API CPF anterior es solo para fines de demostración. Las APIs disponibles y sus respectivas URLs (endpoints) para consumo están disponibles (a través de la documentación de sus respectivos swaggers) en la sección Referencia de API. La puerta de enlace interpreta las letras mayúsculas y minúsculas de manera diferente. Asegúrese de enviar los endpoints de acuerdo con la Referencia de API sin cambiar ninguna parte del endpoint a mayúsculas o minúsculas.

Cómo usar la API de demostración de CPF

API CPF Demo es el entorno de prueba de la API de CPF, con datos de muestra (simulados), para demostrar el funcionamiento de la API. Para usarlo:

  1. Acceda a la API de demostración de CPF
  2. Elija el método (punto final) para probar
  3. Haga clic enTry it Out
  4. Inserte los encabezados que desee y / o cambie el contenido del cuerpo de la solicitud
  5. Haga clic en Execute

Datos de prueba

Para probar el entorno de prueba, use uno de los CPF ficticios que se enumeran a continuación.

CPF Situación de registro
40442820135 CPF regular
63017285995 CPF regular
91708635203 CPF regular
58136053391 CPF regular
40532176871 Suspendido
47123586964 Suspendido
07691852312 Regularización Pendiente
10975384600 Regularización Pendiente
01648527949 Cancelado por multiplicidad
47893062592 Cancelado por multiplicidad
98302514705 Nulo
18025346790 Nulo
64913872591 Oficina cancelada
52389071686 Oficina cancelada
05137518743 Titular fallecido
08849979878 Titular fallecido