A API Assertiva Localize permite consultar informações cadastrais e de contato de pessoas físicas e jurídicas a partir de diferentes dados de entrada, como CPF, CNPJ, e-mail, telefone, nome e endereço.
A API também disponibiliza consultas complementares, relatórios de utilização e recursos para que a empresa adicione informações próprias, como telefones, e-mails, endereços e comentários vinculados aos documentos consultados.
A integração deve ser realizada por uma equipe técnica. Para consultar a documentação completa, acesse a https://integracao.assertivasolucoes.com.br/v3/portal
1. Como funciona a integração
A utilização da API Localize ocorre em duas etapas principais:
Obter um token de acesso utilizando as credenciais da API.
Enviar o token nas requisições realizadas aos endpoints do Localize.
O token deve ser enviado no cabeçalho das requisições no formato:
Authorization: Bearer SEU_TOKEN_DE_ACESSO
As credenciais e o token são descritos no artigo Como gerar credenciais e token de acesso para as APIs da Assertiva.
2. Ambiente e URL base
As requisições devem ser realizadas no ambiente de produção utilizando a seguinte URL base:
https://api.assertivasolucoes.com.br
Os endpoints do Localize são disponibilizados sob os caminhos:
/localize/v3
Algumas consultas complementares utilizam caminhos específicos, como:
/localize-api/v1/feedback/v3/meu-portal/v3/ultimas-consultas/v3
3. Finalidade de uso e LGPD
As consultas que envolvem dados pessoais devem informar a finalidade de uso por meio do parâmetro idFinalidade.
As finalidades disponíveis são:
ID | Finalidade | Descrição |
| Confirmação de identidade | Utilização do dado pessoal para combate à fraude, identificação correta ou confirmação de identidade. |
| Ciclo de crédito | Utilização do dado pessoal no ciclo de proteção ao crédito, incluindo cobrança, verificação da situação financeira e correta identificação. |
| Execução de contrato | Utilização do dado pessoal para atualização ou execução de contrato e procedimentos preliminares relacionados ao contrato. |
| Legítimo interesse | Utilização do dado pessoal para atender aos interesses legítimos do controlador ou de terceiros, respeitando os direitos e as liberdades fundamentais do titular. |
O valor informado deve corresponder à finalidade real da consulta.
4. Consultas principais
As consultas principais permitem localizar informações usando diferentes tipos de dados.
4.1 Consulta por CPF
Retorna informações cadastrais e de contato de uma pessoa física.
Endpoint:
GET https://api.assertivasolucoes.com.br/localize/v3/cpf
Parâmetros
Parâmetro | Obrigatório | Descrição |
| Sim | CPF a ser consultado, com ou sem máscara. Os zeros à esquerda são opcionais. |
| Sim | Finalidade de uso da consulta. |
Exemplo
GET https://api.assertivasolucoes.com.br/localize/v3/cpf?cpf=123.456.789-01&idFinalidade=1
A resposta pode conter, entre outros dados:
CPF;
Nome;
Sexo;
Data de nascimento;
Idade;
Situação cadastral;
Nome e informações da mãe;
Telefones fixos e móveis;
Endereços;
E-mails;
Participações em empresas;
Possível histórico profissional;
Registros profissionais;
Redes sociais;
Comentários e informações adicionadas pela empresa.
4.2 Consulta por CNPJ
Retorna informações cadastrais e de contato de uma empresa.
Endpoint:
GET https://api.assertivasolucoes.com.br/localize/v3/cnpj
Parâmetros
Parâmetro | Obrigatório | Descrição |
| Sim | CNPJ a ser consultado, com ou sem máscara. Os zeros à esquerda são opcionais. |
| Sim | Finalidade de uso da consulta. |
Exemplo
GET https://api.assertivasolucoes.com.br/localize/v3/cnpj?cnpj=01.234.567%2F0001-89&idFinalidade=1
A resposta pode conter:
CNPJ;
Razão social;
Nome fantasia;
Data de abertura;
Situação cadastral;
Porte da empresa;
Quantidade de funcionários;
CNAE principal e secundários;
Natureza jurídica;
Endereço;
Telefones;
E-mails;
Sócios;
Participações em empresas;
Site;
Presença no Google Meu Negócio;
Comentários e dados adicionados pela empresa.
4.3 Consulta por e-mail
Localiza pessoas físicas e jurídicas relacionadas a um endereço de e-mail.
Endpoint:
GET https://api.assertivasolucoes.com.br/localize/v3/email
Parâmetros
Parâmetro | Obrigatório | Descrição |
| Sim | Endereço de e-mail válido. |
| Sim | Finalidade de uso da consulta. |
Exemplo
GET https://api.assertivasolucoes.com.br/localize/v3/email?email=jma%40assertivasolucoes.com&idFinalidade=1
Os resultados podem incluir:
Pessoas físicas relacionadas ao e-mail;
CPF;
Nome;
Data de nascimento;
Nome da mãe;
Cidade e UF;
Empresas relacionadas;
CNPJ;
Razão social;
Data de abertura;
Sócios;
Cidade e UF.
4.4 Consulta por telefone
Localiza pessoas físicas e jurídicas relacionadas a um número de telefone.
Endpoint:
GET https://api.assertivasolucoes.com.br/localize/v3/telefone
Parâmetros
Parâmetro | Obrigatório | Descrição |
| Sim | Número com 10 ou 11 dígitos, com ou sem máscara. |
| Sim | Finalidade de uso da consulta. |
Exemplo
GET https://api.assertivasolucoes.com.br/localize/v3/telefone?telefone=%2811%29%2099898-9898&idFinalidade=1
A resposta pode conter:
Pessoas relacionadas ao telefone;
CPF;
Nome;
Data de nascimento;
Nome da mãe;
Cidade e UF;
Empresas relacionadas;
CNPJ;
Razão social;
Data de abertura;
Sócios;
Cidade e UF.
4.5 Consulta por nome ou endereço
Permite localizar pessoas físicas, empresas ou ambas a partir de nome, razão social, CEP ou endereço.
Endpoint:
GET https://api.assertivasolucoes.com.br/localize/v3/nome-endereco
Parâmetros
Parâmetro | Obrigatório | Descrição |
| Sim | Tipo de resultado esperado: |
| Condicional | Nome da pessoa ou razão social da empresa. |
| Não | Define se o resultado deve conter exatamente o nome informado. |
| Não | Sexo da pessoa. Aceita |
| Não | Data de nascimento ou abertura no formato |
| Não | Unidade federativa do endereço. |
| Não | Cidade. Deve ser utilizada junto com a UF. |
| Não | Bairro. Deve ser utilizado junto com UF e cidade. |
| Condicional | CEP ou nome da rua. |
| Não | Número inicial do intervalo de endereços. |
| Não | Número final do intervalo de endereços. |
| Não | Complemento do endereço. |
| Sim | Finalidade de uso da consulta. |
É necessário informar, no mínimo:
O parâmetro
buscarPor; eUm nome ou razão social válido, ou um CEP ou nome de rua válido.
Exemplo
GET https://api.assertivasolucoes.com.br/localize/v3/nome-endereco?buscarPor=ambas&nomeOuRazaoSocial=João%20Mário%20de%20Andradas&idFinalidade=1
Quando a busca for realizada por endereço, alguns filtros dependem de outros:
Para utilizar
cidade, informe tambémuf.Para utilizar
bairro, informeufecidade.Para utilizar uma rua em
cepOuNomeRua, informeuf, cidade e bairro.Para utilizar
complemento, informe UF, cidade, bairro e rua.
5. Consultas secundárias
As consultas secundárias complementam uma consulta principal. Alguns endpoints exigem que o mesmo CPF ou CNPJ tenha sido consultado anteriormente.
5.1 Consulta de mais telefones
Retorna telefones relacionados a um CPF ou CNPJ, como telefones de parentes, mãe, possíveis parentes, sócios ou empresas relacionadas.
Endpoint:
GET https://api.assertivasolucoes.com.br/localize/v3/mais-telefones
Parâmetros
Parâmetro | Obrigatório | Descrição |
| Sim | Tipo do documento: |
| Sim | CPF ou CNPJ consultado. |
| Sim | Protocolo retornado na consulta anterior de CPF ou CNPJ. |
Antes de utilizar esse endpoint, é necessário realizar uma consulta principal de CPF ou CNPJ com o mesmo documento.
5.2 Consulta de pessoas de referência
Retorna pessoas relacionadas a um CPF, como mãe, filhos, irmãos e sócios. Esses dados podem auxiliar na confirmação de identidade.
Endpoint:
GET https://api.assertivasolucoes.com.br/localize/v3/pessoas-de-referencia
Parâmetros
Parâmetro | Obrigatório | Descrição |
| Sim | CPF consultado. |
| Sim | Define se os dados da mãe devem ser retornados. |
| Não | Protocolo da consulta anterior de CPF. |
| Sim | Finalidade de uso da consulta. |
A consulta de CPF deve ter sido realizada anteriormente para o mesmo documento.
5.3 Consulta de possíveis decisores
Retorna possíveis decisores relacionados a um CNPJ, auxiliando atividades de prospecção e relacionamento comercial.
Endpoint:
GET https://api.assertivasolucoes.com.br/localize/v3/possiveis-decisores
Parâmetros
Parâmetro | Obrigatório | Descrição |
| Sim | CNPJ consultado. |
| Sim | Protocolo retornado na consulta anterior de CNPJ. |
A resposta pode conter:
Nome;
CPF;
Cargo;
Data de nascimento.
5.4 Consulta de conexões
Retorna pessoas, empresas e telefones relacionados a um CPF ou CNPJ.
Endpoint:
GET https://api.assertivasolucoes.com.br/localize-api/v1/base-cadastral/conexoes
Parâmetros
Parâmetro | Obrigatório | Descrição |
| Sim | CPF ou CNPJ. |
| Sim | Tipo do documento: |
| Sim | Finalidade de uso da consulta. |
| Não | Quando informado, pode retornar o cônjuge em consultas por CPF. |
| Não | Quando informado, retorna o primeiro contato de cada pessoa conectada. |
As conexões podem incluir:
Parentes;
Empregadores;
Sócios;
Empresas relacionadas;
Pessoas do convívio familiar;
Possíveis decisores;
Empresas com participação.
6. Feedback de telefones
A API permite avaliar telefones retornados nas consultas. O feedback pode indicar se o telefone está correto ou se precisa ser desconsiderado.
Essa avaliação pode ser compartilhada com a Assertiva e com outros usuários da mesma organização.
Só é possível avaliar um telefone relacionado a um documento que tenha sido previamente consultado.
6.1 Consultar avaliações e justificativas
Endpoint:
GET https://api.assertivasolucoes.com.br/feedback/v3/telefone
Esse endpoint retorna os IDs e as descrições das avaliações e justificativas disponíveis.
As avaliações previstas são:
Avaliação positiva;
Avaliação negativa.
A justificativa é necessária quando a avaliação for negativa.
6.2 Adicionar feedback
Endpoint:
POST https://api.assertivasolucoes.com.br/feedback/v3/telefone
Corpo da requisição
{ "tipo": "CPF", "documento": "123.456.789-01", "telefone": "(11) 99898-9898", "idAvaliacao": 2, "idJustificativa": 1 }
O documento pode ser informado com ou sem máscara.
6.3 Alterar feedback
Endpoint:
PUT https://api.assertivasolucoes.com.br/feedback/v3/telefone/{id}
Substitua {id} pelo identificador do feedback que será alterado.
O corpo da requisição segue o mesmo formato utilizado para adicionar um feedback.
6.4 Excluir feedback
Endpoint:
DELETE https://api.assertivasolucoes.com.br/feedback/v3/telefone/{id}
Substitua {id} pelo identificador do feedback que será excluído.
7. Meu Portal
Os endpoints do grupo Meu Portal permitem adicionar informações próprias aos documentos consultados. Esses dados podem ser visualizados por outros usuários da mesma organização.
As informações adicionadas ficam vinculadas ao CPF ou CNPJ consultado.
É necessário consultar previamente o documento antes de adicionar informações relacionadas a ele.
7.1 Adicionar comentário
Endpoint:
POST https://api.assertivasolucoes.com.br/meu-portal/v3/comentario
{ "tipo": "CPF", "documento": "123.456.789-01", "comentario": "Última tentativa de contato realizada sem sucesso." }
7.2 Alterar comentário
Endpoint:
PUT https://api.assertivasolucoes.com.br/meu-portal/v3/comentario/{id}
7.3 Excluir comentário
Endpoint:
DELETE https://api.assertivasolucoes.com.br/meu-portal/v3/comentario/{id}
7.4 Adicionar e-mail
Endpoint:
POST https://api.assertivasolucoes.com.br/meu-portal/v3/email
{ "tipo": "CPF", "documento": "123.456.789-01", "email": "contato@exemplo.com.br" }
7.5 Alterar e-mail
Endpoint:
PUT https://api.assertivasolucoes.com.br/meu-portal/v3/email/{id}
7.6 Excluir e-mail
Endpoint:
DELETE https://api.assertivasolucoes.com.br/meu-portal/v3/email/{id}
7.7 Adicionar endereço
Endpoint:
POST https://api.assertivasolucoes.com.br/meu-portal/v3/endereco
{ "tipo": "CPF", "documento": "123.456.789-01", "tipoLogradouro": "Av", "logradouro": "João Erbolato", "numero": 364, "complemento": "Ap 22", "bairro": "Jardim Chapadão", "cidade": "Campinas", "uf": "SP", "cep": "13070-070" }
Os campos obrigatórios são:
tipo;documento;logradouro;bairro;cidade;uf;cep.
7.8 Alterar endereço
Endpoint:
PUT https://api.assertivasolucoes.com.br/meu-portal/v3/endereco/{id}
7.9 Excluir endereço
Endpoint:
DELETE https://api.assertivasolucoes.com.br/meu-portal/v3/endereco/{id}
7.10 Adicionar telefone
Endpoint:
POST https://api.assertivasolucoes.com.br/meu-portal/v3/telefone
{ "tipo": "CPF", "documento": "123.456.789-01", "tipoTelefone": "móvel", "telefone": "(11) 99898-9898", "aplicativos": { "whatsApp": true } }
O telefone pode ser informado com ou sem máscara.
7.11 Alterar telefone
Endpoint:
PUT https://api.assertivasolucoes.com.br/meu-portal/v3/telefone/{id}
7.12 Excluir telefone
Endpoint:
DELETE https://api.assertivasolucoes.com.br/meu-portal/v3/telefone/{id}
8. Relatórios de utilização
A API Localize disponibiliza endpoints para consultar o histórico de utilização das consultas.
8.1 Consultar relatório de uso
Endpoint:
GET https://api.assertivasolucoes.com.br/localize/v3/report/usage
Parâmetros
Parâmetro | Obrigatório | Descrição |
| Não | Status da consulta: |
| Não | Data inicial no formato |
| Não | Data final no formato |
| Não | Número da página. O padrão é |
| Não | Quantidade de itens por página. O padrão é |
O relatório pode apresentar informações como:
Data e hora;
Grupo;
Usuário;
Funcionalidade consultada;
Documento utilizado;
Status;
Protocolo e resultado;
Consultas secundárias relacionadas.
O resultado depende das permissões do usuário. Conforme o perfil, podem ser exibidas consultas do próprio usuário, do grupo ou de toda a empresa.
8.2 Exportar relatório em CSV
Endpoint:
GET https://api.assertivasolucoes.com.br/localize/v3/report/usage/export
Esse endpoint utiliza os seguintes filtros:
status;startDate;endDate.
A resposta retorna uma URL temporária para baixar o arquivo CSV.
8.3 Consultar últimas consultas
Retorna até 30 registros das consultas principais realizadas pelo usuário no Localize.
Endpoint:
GET https://api.assertivasolucoes.com.br/ultimas-consultas/v3
Parâmetro
Parâmetro | Obrigatório | Descrição |
| Sim | Informe o valor |
Exemplo
GET https://api.assertivasolucoes.com.br/ultimas-consultas/v3?produto=Localize
O retorno pode incluir:
Protocolo;
Data e hora;
Tipo de consulta;
Documento ou dado utilizado;
Nome localizado.
9. Estrutura das respostas
As respostas das consultas principais normalmente possuem três áreas:
{ "cabecalho": {}, "resposta": {}, "alerta": "" }
cabecalho
Contém informações sobre a requisição, como:
Data e hora;
Protocolo;
Produto;
Funcionalidade;
Finalidade;
Descrição da finalidade;
Indicação de reconsulta;
Dados utilizados na entrada.
resposta
Contém os dados encontrados na consulta. A estrutura varia de acordo com o endpoint e o tipo de pesquisa.
alerta
Pode conter mensagens complementares relacionadas ao processamento ou ao resultado da consulta.
O campo protocolo deve ser armazenado pela aplicação, pois pode ser necessário em consultas secundárias, como Mais telefones, Pessoas de referência e Possíveis decisores.
10. Códigos de resposta
A API pode retornar os seguintes códigos HTTP:
Código | Significado | Descrição |
| OK | A requisição foi processada com sucesso. |
| Created | Um novo registro foi criado com sucesso, como um comentário ou feedback. |
| Bad Request | Os parâmetros estão incorretos, incompletos ou não atendem à documentação. |
| Unauthorized | O token está ausente, inválido ou expirado. |
| Forbidden | O usuário não possui permissão para realizar a operação. |
| Unprocessable Entity | A solicitação é válida, mas contém dados que impedem o processamento. |
| Internal Server Error | Ocorreu um erro inesperado no servidor. |
| Bad Gateway | O servidor recebeu uma resposta inesperada de outro serviço. |
| Service Unavailable | O serviço está temporariamente indisponível, em manutenção ou sobrecarregado. |
| Gateway Timeout | A resposta não foi obtida dentro do tempo limite de processamento. |
Como solucionar erros comuns
401: gere um novo token e confirme se ele está sendo enviado como
Bearer.403: confirme se o usuário e a empresa possuem permissão para o produto ou endpoint.
400: verifique os nomes dos parâmetros, valores obrigatórios, formato dos documentos e a finalidade informada.
422: confira as regras específicas do endpoint e se o documento foi previamente consultado quando necessário.
504: tente realizar a requisição novamente e verifique a disponibilidade do serviço.
11. Boas práticas de integração
Armazene o token de acesso somente em local seguro.
Nunca exponha o
Client IDe oSecretno código do front-end.Utilize variáveis de ambiente ou um gerenciador de segredos.
Não registre tokens completos em logs.
Renove o token quando ele expirar.
Armazene os protocolos retornados nas consultas.
Valide CPF, CNPJ, telefone e e-mail antes de enviar as requisições.
Envie uma finalidade compatível com o uso real dos dados.
Respeite a LGPD e as políticas internas de tratamento de dados pessoais.
Implemente tratamento para respostas de erro e indisponibilidade.
Evite repetir consultas desnecessariamente.
Utilize os exemplos da documentação oficial para validar os formatos de requisição e resposta.
12. Suporte e documentação
Para consultar os modelos completos de requisição, respostas, parâmetros e códigos de erro, acesse a https://integracao.assertivasolucoes.com.br/v3/portal
Em caso de problemas relacionados à integração, entre em contato pelo e-mail: