# Nucleo Pay — Documentação para LLMs

> Índice completo da API. Use este arquivo para descobrir páginas e endpoints antes de integrar.

## Páginas da documentação

- Bem-vindo: https://nucleopay.com.br/docs/api
- Chaves de API: https://nucleopay.com.br/docs/authentication
- Webhooks: https://nucleopay.com.br/docs/webhooks
- Referência (introdução): https://nucleopay.com.br/docs/reference
- SDKs: https://nucleopay.com.br/docs/sdks
- CLI: https://nucleopay.com.br/docs/cli
- IA / MCP: https://nucleopay.com.br/docs/ai
- Ecossistema: https://nucleopay.com.br/docs/ecosystem
- Changelog: https://nucleopay.com.br/docs/changelog

## Espelho no GitHub (Markdown)

- Repositório público: https://github.com/nucleocompany/Nucleo-pay-API-SERVERS
- Hub: docs/README.md (no repo público) / docs/developers/ (neste vault)
- REST + OpenAPI, MCP, CLI, produto, snippets — ver o repo público

## URLs técnicas

- Manifesto JSON: https://nucleopay.com.br/api/integrations/mcp/manifest
- Guia MCP: https://nucleopay.com.br/api/integrations/mcp/guide
- Base URL da API: https://nucleopay.com.br

## Autenticação

- Tipo: Bearer token
- Header: `Authorization: Bearer SEU_TOKEN`
- Criar token: `POST /api/auth/token/create` (painel ou API autenticada)

## Endpoints principais

- `POST /api/pix/charge/create` — Cria cobrança PIX (body: value, title)
- `GET /api/pix/charge/status?charge_id=` — Consulta status
- `GET /api/pix/charges` — Lista cobranças recentes
- `GET /api/webhooks` — Lista webhooks
- `POST /api/webhooks/create` — Cadastra webhook (url, events)
- `POST /api/webhooks/test` — Envia evento de teste

## Webhooks

- Header de assinatura: `X-NucleoPay-Signature`
- Algoritmo: HMAC-SHA256
- Formato: `sha256={hex}`
- Eventos: charge.created, charge.approved, charge.declined, charge.refund, charge.updated, charge.pending, webhook.test

## Resposta padrão

```json
{ "success": true, "data": { ... } }
```

Em erro: `{ "success": false, "error": "mensagem" }`

## CLI e MCP (instalação local)

```bash
git clone https://github.com/nucleocompany/Nucleo-pay-API-SERVERS.git
cd Nucleo-pay-API-SERVERS
python3 -m pip install -e .
python -m nucleopay_cli --version
```

Windows: rode `mcp_server\setup-mcp.ps1` para instalar e gerar o JSON do MCP.

No Windows, **não use** `"command": "python"` no Cursor — use caminho completo do `python.exe` (o Cursor usa o Python interno do Hermes).

## Integração com IA (MCP)

O MCP roda localmente (`python -m mcp_server` com `cwd` na raiz do clone do GitHub).
Ferramentas: get_integration_manifest, create_pix_charge, get_pix_charge_status, list_pix_charges, list_webhooks, create_webhook, test_webhook, verify_webhook_signature, generate_integration_snippet, list_api_tokens