---
name: knotapi-cpf
description: Integra e consulta a KnotAPI de CPF com segurança. Use quando o usuário pedir consulta cadastral por CPF, integração KnotAPI em backend, tratamento de quota/erros, MCP KnotAPI ou automação Typebot, n8n e agentes.
license: Proprietary
compatibility: Requer acesso HTTPS a knotapi.online. Se a API Key ainda não existir, oriente o usuário a criá-la no portal e configurá-la no ambiente server-side.
metadata:
  author: KnotAPI
  version: "1.2.0"
---

# KnotAPI CPF

Use esta skill somente com autorização do usuário. Se a API Key legítima ainda não existir, faça primeiro o onboarding seguro abaixo; não invente nem solicite o segredo em chat.

## Onboarding da chave

1. Explique que `KNOT_API_KEY` é o nome da variável, não uma chave automática.
2. Oriente o usuário a entrar no portal KnotAPI, criar uma API Key para o projeto e guardar o valor completo quando ele for exibido.
3. Identifique como o projeto já carrega segredos. Em desenvolvimento, use o arquivo de ambiente suportado e ignorado pelo Git; em produção, use o secret manager da hospedagem.
4. Adicione apenas `KNOT_API_KEY=` ao arquivo de exemplo, quando existir. Nunca coloque o valor real em código, commit ou saída para o navegador.
5. Não peça que o usuário cole a chave no chat. Se a configuração ainda não puder ser concluída, entregue os passos exatos e pare antes de fazer uma chamada real.

## Regras obrigatórias

1. Nunca peça para colocar a chave em HTML, JavaScript do navegador, URL, repositório ou mensagem pública.
2. Leia a chave de `KNOT_API_KEY` no backend.
3. Valide o CPF localmente antes da chamada.
4. Envie a chave apenas no header `x-api-key`.
5. Trate 400, 401, 403, 404, 429, 500 e 503 sem inventar dados.
6. Não registre a chave nem o CPF completo em logs.
7. Minimize e proteja os dados retornados conforme a finalidade e a legislação aplicável.

## Fluxo

1. Identifique a linguagem e confirme que existe um backend.
2. Se o projeto for somente frontend, crie primeiro uma rota server-side/proxy.
3. Confirme o onboarding e configure `KNOT_API_KEY` fora do código, sem valor padrão.
4. Chame `GET https://knotapi.online/api?modulo=cpf&consulta=CPF`.
5. Mapeie `dados.CPF`, `dados.NOME`, `dados.NASCIMENTO`, `dados.MAE` e `meta`.
6. Respeite `Retry-After` em 429 e nunca repita indefinidamente. Não faça retry em 400, 401, 403 ou 404.
7. Escreva testes com mock HTTP para configuração ausente, autenticação local, CPF inválido, sucesso, erros e timeout; nunca use a API real no teste.

Consulte [a referência detalhada](references/API.md) quando precisar de contratos e erros. O script [consult-cpf.js](scripts/consult-cpf.js) é um exemplo Node.js executável.

## MCP remoto

Quando a plataforma aceitar MCP Streamable HTTP, configure `https://knotapi.online/mcp` e envie `Authorization: Bearer <KNOT_API_KEY>`. A ferramenta disponível é `consultar_cpf`.