Introdução à KnotAPI

A KnotAPI é uma API HTTP para consultar dados cadastrais por CPF. Ela foi desenhada para integrações de backend, automações e agentes de IA, sempre com autenticação por chave e resposta JSON previsível.

O que você pode fazer

URL base

Formato das respostas

As respostas REST usam JSON e preservam nomes de campos estáveis. Datas de exibição seguem o padrão brasileiro; datas para cálculos também são entregues em ISO 8601.

Antes de começar

Crie sua conta, ative um plano e gere uma chave no portal. Você verá o segredo completo uma única vez; salve-o em um gerenciador de segredos ou variável de ambiente.

Autenticação

Toda requisição REST precisa de uma API Key ativa no header x-api-key. A chave identifica sua conta, aplica quota, rate limit e restrições configuradas.

Obtenha sua API Key

No portal, abra a área de chaves e crie uma chave para o projeto. O plano Grátis permite 1 chave, Developer 3, Profissional 5 e Escala 10. Use nomes como “Site institucional”, “CRM” ou “Typebot” para reconhecer a origem.

Envie a chave no header

CopiarGET /api?modulo=cpf&consulta=12345678909 HTTP/1.1
Host: knotapi.online
Accept: application/json
x-api-key: knot_live_SUA_CHAVE

Não use a URL

Chaves em query string são rejeitadas. URLs podem aparecer em histórico, analytics, logs de proxy e ferramentas de monitoramento.

Erros de autenticação

Faça sua primeira chamada

Com uma chave ativa, você só precisa enviar o CPF e o header de autenticação. O exemplo abaixo funciona em qualquer terminal com curl.

1. Crie uma API KeyEntre no portal, crie a chave e copie o valor completo quando ele for exibido. KNOT_API_KEY é apenas o nome da variável onde você guardará esse valor.
2. Guarde no servidorUse o arquivo de ambiente suportado pelo projeto no desenvolvimento e o cofre de segredos da hospedagem em produção.
3. Faça o GETValide o CPF, leia o status HTTP e nunca envie a chave ao navegador.

Exemplo

Copiarcurl --request GET \
  --url 'https://knotapi.online/api?modulo=cpf&consulta=12345678909' \
  --header 'accept: application/json' \
  --header "x-api-key: $KNOT_API_KEY"

Resposta esperada

Copiar{
  "sucesso": true,
  "dados": {
    "CPF": "12345678909",
    "NOME": "NOME DO TITULAR",
    "NASCIMENTO": "15-01-1990",
    "MAE": "NOME DA MÃE"
  },
  "meta": {
    "quota_remaining": 998,
    "quota_debited": true
  }
}

Escolha sua linguagem ou framework

Cada guia usa recursos nativos ou bibliotecas populares e mantém a API Key exclusivamente no servidor. Os exemplos são pontos de partida; o prompt para IA manda analisar e preservar a arquitetura real do projeto.

Node.jsfetch nativo›Next.jsRoute Handler›ExpressREST proxy›PHPcURL server-side›LaravelHTTP Client›Pythonrequests›Gonet/http›JavaHttpClient›.NETHttpClient›RubyNet::HTTP›RailsNet::HTTP›Rustreqwest›ElixirReq›curlCLI / REST›

Consulta de CPF

Retorna os dados cadastrais disponíveis para um CPF válido. A chamada é síncrona, somente leitura e consome uma unidade quando processada pela API pública.

Endpoint

Autenticação

Envie x-api-key no header. Também recomendamos Accept: application/json.

Parâmetros

Exemplo de requisição

Copiarcurl 'https://knotapi.online/api?modulo=cpf&consulta=12345678909' \
  -H 'accept: application/json' \
  -H "x-api-key: $KNOT_API_KEY"

Comportamento

• O CPF é normalizado antes da validação.
• Restrições de IP e origem são avaliadas por chave.
• Quota e velocidade são informadas em headers de resposta.
• CPF sem registro retorna 404, sem inventar dados.

Resposta e datas brasileiras

Uma resposta bem-sucedida separa os dados consultados de informações operacionais da sua chave. Assim, seu sistema pode exibir o resultado e controlar consumo sem misturar responsabilidades.

Estrutura de sucesso

Copiar{
  "sucesso": true,
  "dados": {
    "CPF": "12345678909",
    "NOME": "NOME DO TITULAR",
    "NASCIMENTO": "15-01-1990",
    "MAE": "NOME DA MÃE"
  },
  "meta": {
    "quota_remaining": 998,
    "quota_reset": "05-09-2026 09:00:00",
    "quota_reset_iso": "2026-09-05T12:00:00.000Z",
    "timezone": "America/Sao_Paulo"
  }
}

Campos de dados

Qual data devo usar?

Códigos de resposta

A KnotAPI usa códigos HTTP para indicar se a chamada foi aceita, rejeitada pelo cliente ou interrompida temporariamente no servidor. Sempre verifique o status antes de consumir o JSON.

Estrutura de um erro

Copiar{
  "sucesso": false,
  "erro": "Descrição legível do problema"
}

Referência completa

Retry e resiliência

Copiarif (response.status === 429 || response.status >= 500) {
  const retryAfter = Number(response.headers.get('retry-after') || 1);
  await wait(Math.min(retryAfter * 1000, 10_000));
  // repita com limite de tentativas; nunca crie loop infinito
}

Quota e rate limits

Quota controla o total de consultas do ciclo. Rate limit controla quantas chamadas podem chegar em uma janela curta. São controles diferentes e devem ser tratados separadamente.

O que consome uma requisição

Cada consulta REST ou chamada MCP confirmada consome uma unidade. O teste autenticado dentro do portal é gratuito e retorna quota_debited: false.

Headers de quota

Headers de velocidade

Estratégia recomendada

• Monitore X-Quota-Remaining sem depender apenas do painel.
• Não dispare chamadas em paralelo sem controle de concorrência.
• Ao receber 429, respeite Retry-After.
• Use backoff exponencial limitado para falhas 5xx.

Restrições por IP e domínio

Cada chave pode ter sua própria lista de IPs/CIDRs e origens HTTPS. Use essas restrições como uma segunda barreira, além de manter o segredo no backend.

Como escolher

Exemplos aceitos

Typebot, n8n, Make e Zapier

A integração segue o mesmo contrato REST: método GET, CPF na query e API Key no header. O ponto importante é guardar a chave no cofre da plataforma e confirmar onde o bloco HTTP é executado.

Configuração em três passos

1. Crie uma chave exclusivaNomeie como “Typebot”, “n8n” ou o nome do fluxo para poder revogar sem afetar outros projetos.
2. Use o cofre de credenciaisCadastre x-api-key como segredo. Nunca mostre o valor em mensagem ou variável pública.
3. Mapeie o resultadoLeia dados.NOME, dados.NASCIMENTO e trate cada código HTTP.

Exemplo de configuração

Typebot

Use um bloco HTTP apenas se a execução e os headers permanecerem no servidor da plataforma. Se o request aparecer no painel de rede do visitante, crie uma rota proxy no seu backend e chame essa rota pelo bot.

Tratamento do fluxo

Proteja sua API Key

A chave concede acesso à sua franquia. Se ela estiver no frontend, qualquer pessoa pode copiá-la. A arquitetura segura coloca a chamada em um servidor controlado por você.

Fluxo recomendado

Exemplo de proxy seguro

Copiar// A rota roda no servidor. KNOT_API_KEY nunca vai para o navegador.
const response = await fetch(
  `https://knotapi.online/api?modulo=cpf&consulta=${encodeURIComponent(cpf)}`,
  { headers: { 'x-api-key': process.env.KNOT_API_KEY } }
);

return Response.json(await response.json(), { status: response.status });

Checklist antes de publicar

• A chave existe apenas em variável de ambiente server-side.
• Logs nunca registram o header x-api-key.
• A rota exige autenticação do seu próprio usuário, quando aplicável.
• CPF é validado antes de chamar a KnotAPI.
• Timeout, rate limit e tratamento de erros estão ativos.
• A chave tem restrição por IP quando o backend possui IP fixo.

Ferramentas para agentes de IA

A KnotAPI oferece superfícies complementares para agentes: MCP para ferramentas estruturadas, Agent Skill para instruções portáteis, OpenAPI para geração de clientes e llms.txt para descoberta da documentação.

O que está disponível

Casos de uso

Prompt para integrar com IA

Copie este prompt no seu assistente de programação. Ele orienta a implementação para backend, inclui o contrato oficial e impede que a chave seja colocada no frontend.

Prompt completo

Integre a KnotAPI neste projeto usando https://knotapi.online/llms-full.txt. Primeiro inspecione a arquitetura, autenticação, configuração de ambiente e testes existentes. KNOT_API_KEY é o nome da variável, não uma chave automática. Se ela ainda não estiver configurada, explique que o usuário deve criar uma API Key no portal KnotAPI e guardar o valor no ambiente server-side ou secret manager; não invente uma chave nem peça que ela seja colada no chat. Mantenha o arquivo real fora do Git e adicione somente o nome vazio ao arquivo de exemplo. Preserve autenticação, autorização e rate limit existentes. Valide formato e dígitos verificadores do CPF. Aplique timeout, trate conexão e 400/401/403/404/429/500/503, preserve Retry-After e não faça retry em erros permanentes. Nunca exponha ou registre a chave nem o CPF completo. Escreva testes com mock HTTP cobrindo configuração ausente, CPF inválido, sucesso, erros e timeout, sem chamada real.

O que a IA deve entregar

• Orientação para criar a API Key quando ela ainda não existir.
• Passos exatos para configurar o segredo no ambiente local e na hospedagem.
• Rota server-side protegida pela autenticação já usada no projeto.
• Falha segura quando KNOT_API_KEY estiver ausente.
• Validação de CPF, timeout e tratamento dos códigos documentados.
• Testes com mock HTTP, sem segredo ou consulta real.

Servidor MCP

O endpoint MCP remoto é stateless e compatível com Streamable HTTP. A ferramenta disponível recebe um CPF e devolve a mesma resposta cadastral da API REST.

Endpoint

Configuração

Copiar{
  "mcpServers": {
    "knotapi": {
      "type": "http",
      "url": "https://knotapi.online/mcp",
      "headers": {
        "Authorization": "Bearer ${KNOT_API_KEY}"
      }
    }
  }
}

Ferramenta disponível

Agent Skill da KnotAPI

A skill reúne instruções de uso, contrato e um script de exemplo. Ela ajuda agentes compatíveis a implementar a integração sem adivinhar endpoints ou expor a chave.

Estrutura

knotapi-cpf/
├── SKILL.md
├── references/
│   └── API.md
└── scripts/
    └── consult-cpf.js

Arquivos

Documentação para máquinas

Use o índice curto para descoberta e a versão completa quando um modelo precisar do contrato técnico em uma única leitura.

Recursos

Como usar em um prompt

CopiarLeia https://knotapi.online/llms-full.txt antes de implementar.
Use apenas endpoints e campos presentes no documento.
Mantenha KNOT_API_KEY exclusivamente no backend.

Perguntas frequentes

Respostas diretas para as dúvidas mais comuns de integração, segurança e consumo.

Compliance e LGPD

CPF e dados cadastrais são dados pessoais. Integrar tecnicamente a KnotAPI não cria, por si só, autorização jurídica para consultar, armazenar ou compartilhar informações.

Princípios de implementação

Checklist operacional

• Documente finalidade, base legal e responsáveis.
• Defina prazo de retenção e descarte seguro.
• Restrinja acesso por função e revise permissões.
• Mantenha trilha de auditoria sem registrar segredos.
• Tenha processo para incidentes e direitos do titular.
• Revise fornecedores e operadores envolvidos.