API Lume · v1
Conta, PIX e extrato por API
Abra a conta de pagamento do seu cliente, consulte saldo e extrato, cadastre chaves PIX, transfira e cobre por QR Code. Uma chave de sandbox sai em uma chamada, sem cadastro.
A primeira chamada
Se você preferir o terminal, o passo acima também é uma requisição. Estas duas linhas levam de zero a uma resposta real do sandbox:
curl -X POST https://sandbox.api.lumecoding.com/v1/sandbox/keys \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]","company":"Sua Empresa"}'A resposta traz apiKey e uma conta de testes com R$ 5.000,00 de saldo fictício. Guarde a chave: ela aparece uma vez só.
curl https://sandbox.api.lumecoding.com/v1/accounts/balance \
-H 'X-API-Key: lume_sk_sandbox_sua_chave_aqui'{
"balanceCents": 500000,
"heldCents": 0,
"currency": "BRL",
"asOf": "2026-09-05T14:00:00Z"
}Transferir
A conta de testes já tem saldo, e o sandbox tem contas fictícias para receber. Uma transferência PIX de R$ 50,00:
curl -X POST https://sandbox.api.lumecoding.com/v1/pix/transfers \
-H 'X-API-Key: lume_sk_sandbox_sua_chave_aqui' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 6f1e2a94-7c3d-4b58-9e21-0a8c5d3f7b62' \
-d '{
"key": "[email protected]",
"amountCents": 5000,
"description": "Pagamento da nota 8841"
}'O que a resposta diz
A transferência responde 202, e não 201: ela foi aceita, mas o desfecho pode ainda não existir. Acompanhe pelo status da transação.
| Status | O que aconteceu | O que fazer |
|---|---|---|
PROCESSING | Enviada ao arranjo, aguardando liquidação. | Consulte GET /v1/transactions/{id}. |
COMPLETED | Liquidada. | Nada. |
HELD_FOR_REVIEW | O motor de risco reteve. riskSignals explica o que chamou atenção e o que foi conferido e está normal. | O titular decide em POST /v1/transactions/{id}/review. Bloquear devolve o dinheiro na hora. |
FAILED | Recusada pelo arranjo. | Leia code no erro. Tabela de códigos. |
Módulos que a instalação liga
Conta, saldo, extrato, limites e segurança estão sempre lá. O resto é funcionalidade do catálogo: cada instalação liga só o que oferece, e GET /v1/features, público e sem credencial, diz o que está ligado. Os módulos abaixo nascem desligados e estão em construção. São só de sessão de cliente, e chave de API recebe 403 FORBIDDEN — com uma exceção: a tabela e a cotação de tarifas (GET /v1/fees e GET /v1/fees/quote) a chave lê com accounts:read.
| Módulo | Funcionalidade | Na referência |
|---|---|---|
| Planos e assinaturas | subscriptions | Assinaturas |
| Portal do estabelecimento | merchant_portal | Estabelecimento |
| Rede de indicação | affiliate_network (com referrals) | Indicação |
| Benefícios e vitrine | marketplace | Benefícios |
| Tarifas por serviço | service_fees | Tarifas |
| Portabilidade e reivindicação de chave PIX | pix_key_claims | PIX |
| Abertura de conta de empresa MEI e EI | business_opening_own | Abertura de conta |
Com o módulo desligado, as rotas dele respondem 403 FEATURE_DISABLED, com details.feature dizendo qual. Não repita nem troque de credencial: esconda da tela o que não está ligado. A exceção é a assinatura viva: GET /v1/subscription e POST /v1/subscription/cancel continuam valendo, para o cliente poder sair do plano a qualquer momento. Tabela de códigos.