Primeira requisição

Este passo a passo leva você até a primeira consulta bem-sucedida no Localize, usando a consulta por CPF como exemplo.

Pré-requisitos

Credenciais

Ter suas credenciais de aplicação (Client ID e Secret).

Token de acesso

Ter gerado um token de acesso — veja Autenticação.

Monte a consulta por CPF

GET /localize/v3/cpf — dados cadastrais a partir de um CPF

Parâmetros (query):

Parâmetro	Obrigatório	Descrição
`cpf`	sim	Um único CPF, com ou sem máscara. Zeros à esquerda são opcionais.
`idFinalidade`	sim	Finalidade de uso LGPD (`1`, `2` ou `5`).

Os valores abaixo são fictícios, apenas para ilustração. Use dados reais só em produção e conforme a finalidade declarada.

Faça a chamada

GET /localize/v3/cpf

curl -X GET \
  "https://api.assertivasolucoes.com.br/localize/v3/cpf?cpf=123.456.789-01&idFinalidade=1" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

// Node 18+ possui fetch nativo.
const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

const url = new URL("https://api.assertivasolucoes.com.br/localize/v3/cpf");
url.searchParams.set("cpf", "123.456.789-01");
url.searchParams.set("idFinalidade", "1");

const resposta = await fetch(url, {
  headers: { Authorization: `Bearer ${accessToken}` }
});
if (!resposta.ok) throw new Error(`Consulta falhou: ${resposta.status}`);
const dados = await resposta.json();
console.log(dados.resposta.dadosCadastrais.nome);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

resposta = requests.get(
    "https://api.assertivasolucoes.com.br/localize/v3/cpf",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"cpf": "123.456.789-01", "idFinalidade": 1},
)
resposta.raise_for_status()
dados = resposta.json()
print(dados["resposta"]["dadosCadastrais"]["nome"])

Entenda a resposta

A resposta de sucesso (200) traz três blocos principais:

cabecalho: metadados da consulta, incluindo o protocolo — guarde-o, pois algumas consultas secundárias (como mais telefones e possíveis decisores) o exigem.
resposta: os dados encontrados (dadosCadastrais, telefones, enderecos, emails, entre outros).
alerta: mensagens adicionais, quando houver.

Exemplo resumido (dados fictícios da documentação)

{
  "cabecalho": {
    "protocolo": "da758c2a-e689-4759-b7d1-009e15b1f302",
    "produto": "Localize",
    "funcionalidade": "CPF",
    "finalidade": "Confirmação de identidade"
  },
  "resposta": {
    "dadosCadastrais": {
      "cpf": "123.456.789-01",
      "nome": "JOAO MARIO DE ANDRADAS",
      "dataNascimento": "14/04/1970"
    }
  },
  "alerta": ""
}

Principais respostas de erro

Código	Significado
`400`	Parâmetros em desacordo com a documentação.
`401`	Credenciais inválidas ou expiradas.
`403`	Usuário sem permissão para o recurso.
`422`	Requisição válida, mas com erros que impedem o processamento.
`500` / `502` / `503` / `504`	Erros/instabilidades do servidor; tente novamente.

Próximo passo

Veja como encadear consultas em fluxos reais nos casos de uso.