Autenticação

Envie sua chave no cabeçalho Authorization. Ela é permanente: não precisa gerar token, não vence.

Authorization: Bearer vd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternativa equivalente: cabeçalho X-API-Key.

URL base

https://api-204-168-233-94.sslip.io

Endpoints

Esquema OpenAPI: /v1/openapi.json.

Consulta por CPF

curl -X POST https://api-204-168-233-94.sslip.io/v1/consultas \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "111.222.333-44",
    "exigir_whatsapp": true,
    "profundidade": "completa"
  }'

Parâmetros

Resposta

{
  "id": "cns_2f9a...",
  "documento": "11122233344",
  "encontrado": true,
  "origem": "consulta",
  "creditos_consumidos": 2,
  "tempo_ms": 812,
  "registro": {
    "tipo": "pessoa_fisica",
    "identificacao": {
      "cpf": "11122233344", "nome": "MARIA DA SILVA", "nome_mae": "ANTONIA DA SILVA",
      "sexo": "feminino", "nascimento": "1987-12-19", "idade": 38,
      "faixa_etaria": "adulto", "geracao": "millennial", "signo": "sagitario",
      "estado_civil": "solteiro", "situacao_receita": "regular"
    },
    "perfil": {
      "profissao": "SUPERVISOR DE ATENDIMENTO", "escolaridade": "superior",
      "renda_faixa": { "minimo": 2001, "maximo": 3000 }, "renda_mensal_estimada": null,
      "classe_economica": "C", "poder_aquisitivo": "medio", "segmento": "adulto_classe_c",
      "fonte_de_renda": "assalariado"
    },
    "score": {
      "valor": 602, "faixa": "medio", "classificacao_credito": "regular",
      "propensao_pagamento": 589, "nivel_propensao": "boa", "afinidade_digital": "muito_alta"
    },
    "whatsapps": [
      { "e164": "+5511991255105", "ddd": "11", "numero": "991255105",
        "formatado": "(11) 99125-5105", "tipo": "celular", "whatsapp": true,
        "operadora": "VIVO", "procon": false, "melhor_horario": "manha", "alta_atividade": true }
    ],
    "telefones": [ "... todos os números, com a flag whatsapp em cada um ..." ],
    "telefones_descartados": [ "... números marcados como ruins ..." ],
    "emails": [ { "endereco": "exemplo@dominio.com.br", "prioridade": 1 } ],
    "enderecos": [
      { "logradouro": "R PROFESSOR ARTUR RAMOS", "numero": "250", "complemento": "APT 22",
        "bairro": "JARDIM PAULISTANO", "cidade": "SAO PAULO", "uf": "SP", "cep": "01454010",
        "latitude": -23.5825687, "longitude": -46.6872481,
        "linha": "R PROFESSOR ARTUR RAMOS, 250, APT 22, JARDIM PAULISTANO, SAO PAULO/SP, 01454010" }
    ],
    "sinais": {
      "obito": false, "possui_veiculo": true, "possui_imovel": false,
      "beneficio_social": false, "divida_ativa_uniao": false,
      "pessoa_politicamente_exposta": false,
      "fgts": { "possui": true, "valor_presumido": 27108, "ja_sacou": false }
    },
    "comportamento": {
      "categorias_de_consumo": ["alimentos e afins", "beleza e estetica", "pets"],
      "consultas_ultimos_6_meses": 11, "consultas_ultimos_12_meses": 20
    },
    "empresas": [ { "cnpj": "11222333000144", "razao_social": "EXEMPLO LTDA",
                    "participacao_percentual": 100.0, "situacao": "ativa", "vinculo": "socio" } ],
    "relacionados": [ { "cpf": "99988877766", "nome": "ANTONIA DA SILVA", "vinculo": "mae" } ]
  }
}

Escalas e vocabulário

Os campos categóricos usam valores fixos, em snake_case, estáveis entre versões. Pode indexar e comparar direto, sem normalizar do seu lado.

Consulta por nome, telefone ou e-mail

curl -X POST https://api-204-168-233-94.sslip.io/v1/consultas \
  -H "Authorization: Bearer SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{ "nome": "MARIA APARECIDA DA SILVA", "limite": 5 }'

A resposta traz uma lista em resultados, com o mesmo formato de registro. Só entram os que passaram no filtro de WhatsApp.

Lote

Ideal para automação: mande a lista inteira e receba tudo junto. O paralelismo é nosso.

curl -X POST https://api-204-168-233-94.sslip.io/v1/consultas/lote \
  -H "Authorization: Bearer SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{
    "documentos": ["11122233344", "55566677788", "11222333000144"],
    "exigir_whatsapp": true,
    "profundidade": "completa"
  }'

{
  "id": "lot_8c1d...", "total": 3, "encontrados": 2, "creditos_consumidos": 5,
  "resultados": [ { "documento": "11122233344", "encontrado": true, "registro": { } },
                  { "documento": "55566677788", "encontrado": false, "motivo": "sem_whatsapp" } ]
}

Créditos

Um documento consultado = 1 consulta, independente de quantos blocos de dado voltam. O campo origem diz de onde veio: consulta, cache ou parcial_cache. Saldo e fatura ficam no painel.

Erros

Todo erro tem o mesmo formato, com um codigo estável para tratar em código e uma referencia para citar no suporte.

{ "erro": { "codigo": "sem_whatsapp",
            "mensagem": "Registro localizado, mas sem número de WhatsApp.",
            "referencia": "err_7d2c91a0b3" } }

Boas práticas para automação

• Trate 404 sem_whatsapp como resposta normal do fluxo, não como falha.
• Em 503, tente de novo com espera progressiva. O serviço se recupera sozinho.
• Guarde o id da consulta: GET /v1/consultas/{id} devolve o registro depois, de graça.
• Prefira /v1/consultas/lote a mil chamadas soltas — é mais rápido e não bate no limite por segundo.
• Não precisa cachear do seu lado: repetição de documento não consome crédito.

Painel

Em https://api-204-168-233-94.sslip.io/painel você entra com a mesma chave e vê saldo restante, consumo por dia, taxa de aproveitamento e a fatura em aberto.