# Integrar a Lunium pelo ChatGPT ou por um agente

Revisão: 17/09/2026. Entrada guiada: https://luniumpay.com/integrar . Contrato legível por máquina: https://docs.luniumpay.com/integration.json .

## Começar dentro do ChatGPT

Uma conta/workspace elegível pode habilitar o modo de desenvolvedor e adicionar um app/plugin MCP remoto. A disponibilidade e os nomes dos menus dependem da conta e da política do workspace. Siga as instruções oficiais: https://developers.openai.com/plugins/deploy/connect-chatgpt .

1. Nas configurações do ChatGPT, habilite Developer Mode, quando disponível.
2. Crie a conexão **Lunium — integração**, com URL `https://api.luniumpay.com/mcp/onboarding`. Escolha sem autenticação para esta conexão pública.
3. Revise as ferramentas e adicione a conexão à conversa. Peça: “Planeje uma integração Lunium para receber PIX em custódia usando Node.js. Execute uma demonstração de sandbox e prepare o código para meu projeto.”
4. O agente consulta `lunium_plan_integration`, inicia `lunium_start_sandbox_demo` com um UUID e `flow` igual a `custody`, `cashin`, `payout` ou `cashout`, e acompanha `lunium_get_sandbox_demo`. A simulação termina em `COMPLETED`; nenhum dinheiro se move.
5. Continue com o kit de código e a lista de prontidão. Se quiser acompanhamento humano, forneça o e-mail e autorize `lunium_contact`. Esse contato é opcional.

A conexão pública faz planejamento, consulta de catálogo, testes sintéticos e contato consentido. Ela não vincula contas de produção. OAuth de conta Lunium para ChatGPT ainda não está implementado; as exigências estão em https://developers.openai.com/plugins/build/auth . O MCP completo em `/mcp` também tem ferramentas de conta, para hosts que configurem `X-API-Key` de forma segura. Não cole chaves de produção no chat.

A existência de um endpoint MCP não significa publicação automática no diretório de apps do ChatGPT. Se a opção de conexão não aparecer na sua conta, use o briefing e o kit abaixo.

## Começar com qualquer IA de programação

Abra https://luniumpay.com/integrar , escolha o fluxo e a linguagem e copie o briefing. Inclua o projeto em que deseja trabalhar. O briefing aponta para o contrato vigente e pede implementação, testes e explicação do que ainda precisa ser validado.

Baixe https://docs.luniumpay.com/starter/lunium-starter.zip . Execute `node sandbox.mjs all` (Node 20+) ou `python3 sandbox.py all` (Python 3.9+). Não há bibliotecas extras. Os scripts criam uma chave de teste em memória, simulam o fluxo escolhido (ou todos com `all`), consultam o estado e recusam chaves de produção. Você pode reutilizar sua chave `lun_test_` por variável de ambiente `LUNIUM_API_KEY`.

O arquivo `AGENTS.md` do kit orienta a IA no repositório. Não substitui as instruções do seu projeto. Código de teste: https://docs.luniumpay.com/starter/sandbox.mjs e https://docs.luniumpay.com/starter/sandbox.py .

## Qual fluxo implementar

- **Receber PIX na custódia:** `POST /cashin/charge` com `destino: "saldo"`. Crédito em BRL; não exige carteira fixa. O `payer_tax_number` é o documento do pagador real. `customer_ref` escolhe a subconta.
- **Sacar cripto da custódia:** consulte disponível em `/saldo`, rotas em `/cashin/catalog` e escolha moeda, `chain`, endereço e memo quando exigido. Envie `POST /saldo/sacar-cripto`. Não prometa toda moeda listada: confira `entregavel` e limites.
- **PIX com entrega direta em cripto:** use `destino: "cripto"`, catálogo de entrega e `POST /cashin/preview` antes de criar a cobrança.
- **Cripto para PIX:** use `/catalog`, `POST /cash-outs`, aceite e acompanhamento. Esse fluxo também está disponível no sandbox.
- **Payout PIX:** confirme capacidades em `/keys/me`, saldo disponível e taxas em `/saldo`; crie em `POST /payouts` e acompanhe o ID retornado.

Em cash-in e saque cripto o campo da rede é `chain`; em cash-out é `network`. Valores em reais usam centavos inteiros; quantidades de cripto usam strings decimais. Consulte o schema de cada rota em https://docs.luniumpay.com/openapi.json .

## O que o teste comprova

O sandbox cobre PIX de entrada, crédito de custódia, saque e entrega cripto, payout PIX, transferência interna e cash-out. O QR não é bancário: o pagamento é confirmado em `POST /sandbox/cashin/{cashin_id}/pay`. Tudo é fictício, sem chamada a banco, MEXC ou blockchain. Consulte https://docs.luniumpay.com/sandbox para cenários de falha, retenção, saldo insuficiente, resultado incerto, webhooks assinados e diferenças de produção.

A demonstração pública usa dados sintéticos fixos. Não recebe carteira, PIX, valor ou chave de produção. O identificador do teste expira após duas horas; o estado financeiro fictício persiste após reinício; cash-out tem retenção de duas horas. Reutilize `request_id` em retries e o `demo_id` para acompanhamento. Um teste concluído não certifica sua integração inteira.

## Antes de operar dinheiro real

Leia https://docs.luniumpay.com/manual . Verifique permissões e limites da chave, mínimos e taxas por rota, documentos e destinatários reais, saldo disponível e retenções. Implemente `external_id` persistente por intenção, retries sem alterar o pedido, verificação HMAC do corpo bruto do webhook, timestamp e deduplicação de eventos. Após timeout, consulte a operação original.

Cash-in só conclui com `status=paid` **e** `settlement_status=sent`; cash-out com `state=COMPLETED`; payout com `status=sent`. Não trate `delayed` como falha. Armazene chaves e segredos somente no backend. Autorize conscientemente a primeira operação real do fluxo escolhido.