> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantumpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Usar com IA e ferramentas de código

> Integre a documentação da Quantum Pay com ChatGPT, Claude, GitHub Copilot, Cursor e outros assistentes de IA

A Quantum Pay disponibiliza sua documentação em formato otimizado para inteligências artificiais, seguindo o padrão [llms.txt](https://llmstxt.org) e com servidor **MCP** (Model Context Protocol) nativo. Isso permite que você conecte qualquer assistente de IA às nossas docs e receba ajuda precisa na integração.

## Conectar via MCP

O MCP permite que ferramentas de IA acessem a documentação completa em tempo real, com recursos estruturados e prompts pré-definidos para as integrações mais comuns.

**Claude**

```bash theme={null}
claude mcp add quantumpay --scope user --transport http https://quantum-pay-mcp.quantumpay.workers.dev/mcp
```

**VS Code** — adicione ao `settings.json`:

```json theme={null}
{
  "mcp": {
    "servers": {
      "quantumpay": {
        "type": "http",
        "url": "https://quantum-pay-mcp.quantumpay.workers.dev/mcp"
      }
    }
  }
}
```

**OpenAI Codex**

```bash theme={null}
codex mcp add --name quantumpay --url https://quantum-pay-mcp.quantumpay.workers.dev/mcp
```

Após conectar, sua IA terá acesso a:

* Documentação completa de todos os endpoints
* Guias separados por seção (autenticação, PIX IN, PIX OUT, webhooks)
* Prompts pré-definidos para integrações comuns

***

## Formatos disponíveis

<CardGroup cols={2}>
  <Card title="Servidor MCP" icon="server" href="https://quantum-pay-mcp.quantumpay.workers.dev/mcp">
    Endpoint MCP nativo. Compatible com Claude, VS Code Copilot, Codex e qualquer cliente MCP.
  </Card>

  <Card title="llms.txt — resumido" icon="file-text" href="https://docs.quantumpay.com.br/llms.txt">
    Versão concisa da API com todos os endpoints essenciais. Ideal para contexto inicial e prompts rápidos.
  </Card>

  <Card title="OpenAPI (YAML)" icon="code" href="https://docs.quantumpay.com.br/openapi.yaml">
    Especificação OpenAPI 3.1 completa. Compatível com Postman, Insomnia e geração automática de clientes.
  </Card>

  <Card title="Referência da API" icon="book" href="/pages/reference/errors">
    Códigos de erro, status e rate limits documentados em detalhe.
  </Card>
</CardGroup>

***

## Como conectar sua IA favorita

### Claude (chat)

Abra uma conversa no Claude e cole o prompt abaixo:

```
Leia a documentação da API da Quantum Pay em:
https://docs.quantumpay.com.br/llms.txt

Me ajude a integrar o PIX IN (recebimento via QR Code PIX)
em um projeto Node.js.
```

Ou acesse diretamente: [claude.ai/new](https://claude.ai/new)

***

### ChatGPT

Abra o ChatGPT e cole:

```
Use a documentação da API Quantum Pay disponível em:
https://docs.quantumpay.com.br/llms.txt

Preciso integrar pagamentos PIX no meu sistema. Me guie passo a passo.
```

***

### GitHub Copilot / VS Code

Crie o arquivo `.github/copilot-instructions.md` na raiz do seu projeto:

```markdown theme={null}
# Instruções para integração Quantum Pay

Este projeto usa a API Quantum Pay para processamento de pagamentos PIX.

Documentação da API: https://docs.quantumpay.com.br/llms.txt

## Pontos importantes:
- URL base: https://api.quantumpay.com.br
- Autenticação: Basic Auth (API Key + Secret) → Bearer Token JWT (30 min)
- Valores monetários: SEMPRE em centavos (R$ 10,00 = 1000)
- PIX IN: POST /api/v1/pix/in/qrcode
- PIX OUT: POST /api/v1/pix/out/pixkey com Idempotency-Key
- Webhooks: validar assinatura X-Signature com HMAC-SHA256
```

***

### Cursor

Crie o arquivo `.cursorrules` na raiz do projeto:

```
# Quantum Pay API Integration

Documentação completa: https://docs.quantumpay.com.br/llms.txt

Regras:
- Todos os valores são em centavos
- Sempre renovar o Bearer Token antes de expirar (30 min)
- Usar Idempotency-Key em transferências PIX OUT
- Validar assinatura HMAC-SHA256 em todos os webhooks recebidos
- Retornar HTTP 200 imediatamente no endpoint de webhook
```

No chat do Cursor use:

```
@docs https://docs.quantumpay.com.br/llms.txt
Me ajude a integrar PIX IN e PIX OUT da Quantum Pay
```

***

### Gemini

```
Leia a documentação da API Quantum Pay em:
https://docs.quantumpay.com.br/llms.txt

Preciso de ajuda para:
1. Autenticar com Basic Auth e obter Bearer Token
2. Criar uma cobrança PIX (QR Code)
3. Configurar webhook para confirmar pagamento
```

***

## Prompts prontos para uso

<AccordionGroup>
  <Accordion title="Integração PIX IN básica" icon="qrcode">
    ```
    Usando a documentação em https://docs.quantumpay.com.br/llms.txt,
    crie uma classe em Node.js que:
    1. Autentica com a Quantum Pay usando API Key e API Secret
    2. Cria uma cobrança PIX com QR Code
    3. Exibe o QR Code e o código "copia e cola" para o cliente
    4. Trata erros de autenticação e rate limit
    ```
  </Accordion>

  <Accordion title="Webhook completo com validação" icon="webhook">
    ```
    Usando a documentação em https://docs.quantumpay.com.br/llms.txt,
    crie um endpoint de webhook em Express que:
    1. Valida a assinatura HMAC-SHA256 no header X-Signature
    2. Processa o evento transaction_paid para liberar o produto
    3. Processa o evento transfer_completed para confirmar saque
    4. Retorna HTTP 200 imediatamente em todos os casos
    5. Loga eventos inválidos sem quebrar
    ```
  </Accordion>

  <Accordion title="PIX OUT com idempotência" icon="bolt">
    ```
    Usando a documentação em https://docs.quantumpay.com.br/llms.txt,
    crie uma função para enviar transferência PIX OUT que:
    1. Gera um Idempotency-Key único por transferência (UUID v4)
    2. Envia para qualquer tipo de chave PIX (CPF, CNPJ, email, telefone, EVP)
    3. Verifica o status da transferência via webhook
    4. Trata o caso de transferência já enviada (idempotência)
    ```
  </Accordion>

  <Accordion title="SDK completo" icon="package">
    ```
    Usando a especificação OpenAPI em https://docs.quantumpay.com.br/openapi.yaml,
    gere um SDK em TypeScript para a Quantum Pay que:
    1. Tipagem completa de todos os requests e responses
    2. Gerenciamento automático de token (renovação antes de expirar)
    3. Retry automático com exponential backoff para erros 429 e 5xx
    4. Suporte a todos os endpoints: auth, pix-in, pix-out, webhooks
    ```
  </Accordion>
</AccordionGroup>

***

## Dúvidas frequentes das IAs

<AccordionGroup>
  <Accordion title="Como a autenticação funciona?" icon="key">
    A autenticação é em **dois passos**:

    1. `POST /api/auth` com `Authorization: Basic base64(apiKey:apiSecret)` — retorna Bearer Token (JWT, 30 min)
    2. Todas as outras requisições usam `Authorization: Bearer <token>`

    O token expira em 30 minutos. Renove automaticamente antes de expirar.
  </Accordion>

  <Accordion title="Os valores são em reais ou centavos?" icon="dollar-sign">
    **Sempre em centavos (inteiros).** Nunca use ponto decimal.

    * R\$ 1,00 = `100`
    * R\$ 10,50 = `1050`
    * R\$ 250,00 = `25000`

    O campo se chama `amountInCents` em todos os endpoints.
  </Accordion>

  <Accordion title="Como sei que o pagamento foi confirmado?" icon="check">
    Via **webhook** do evento `transaction_paid`. Configure um endpoint público e registre via `POST /api/v1/webhook`. Nunca confie apenas no status retornado na criação — ele sempre começa como `pending`.
  </Accordion>

  <Accordion title="Como evitar PIX OUT duplicado?" icon="copy">
    Use o header `Idempotency-Key` com um UUID único por operação. Se você reenviar a mesma requisição com o mesmo `Idempotency-Key`, a API retorna o resultado da primeira chamada sem criar uma nova transferência.
  </Accordion>
</AccordionGroup>

***

## Suporte

<CardGroup cols={2}>
  <Card title="Suporte por e-mail" icon="envelope" href="mailto:contato@quantumhubpay.com">
    [contato@quantumhubpay.com](mailto:contato@quantumhubpay.com)
  </Card>

  <Card title="Acessar dashboard" icon="layout-dashboard" href="https://app.quantumpay.com.br">
    Gere suas credenciais e configure webhooks
  </Card>
</CardGroup>