# API Lume API bancária para integração servidor-a-servidor. Abre e opera conta de pagamento no Brasil: saldo (inclusive valor bloqueado), extrato, chaves PIX, consulta de titular no DICT, transferência PIX, geração, leitura e pagamento de BR Code (QR Code PIX), TED, cobrança por boleto, beneficiários, limites, tarifas, funcionalidades ligadas na instalação e eventos de segurança. Para telas do cliente, há também cartões, pagamento de contas, recarga de celular, agendamentos e módulos que cada instalação liga ou desliga: planos e assinaturas, rede de indicação, portal do estabelecimento, vitrine de benefícios e portabilidade de chave PIX. Todo o dinheiro é representado como inteiro em centavos. ## Especificação OpenAPI 3.1: https://docbank.lumecoding.com/openapi.json Mesmo conteúdo em YAML: https://docbank.lumecoding.com/openapi.yaml O spec descreve apenas endpoints que existem e respondem. Endpoint planejado não entra nele: o que estiver em construção aparece em https://docbank.lumecoding.com/roteiro/. ## URLs base Sandbox: https://sandbox.api.lumecoding.com Produção: https://api.lumecoding.com ## Autenticação Cabeçalho: X-API-Key Formato da chave: lume_sk_sandbox_<44 caracteres> ou lume_sk_live_<44 caracteres> Chave de sandbox, sem cadastro e sem aprovação: POST /v1/sandbox/keys Content-Type: application/json {"email": "voce@empresa.com.br", "company": "Sua Empresa"} A resposta traz a chave (exibida uma única vez), uma conta de testes isolada com R$ 5.000,00 de saldo fictício e o segredo TOTP dessa conta. Chave de produção não sai por autoatendimento: é emitida comercialmente, só com escopos de leitura, e só vale depois de uma segunda aprovação interna do banco. Antes disso, a chamada com ela recebe 401 "aguardando a aprovação do banco". Pode ser restrita a endereços de origem: de fora deles, 403. O ambiente está embutido na chave. Uma chave de sandbox apresentada em produção responde 401, e o contrário também. A chave expira depois de 30 dias sem uso. Limite de 60 requisições por minuto por chave no sandbox; na produção, o ritmo é gravado na emissão, até 120 por minuto. Escopos: accounts:read (perfil, saldo, extrato, transação, limites, beneficiários, eventos de segurança, tabela e cotação de tarifas), pix:read, pix:write, pix:keys:write (só cadastrar chave; excluir é de sessão) e beneficiaries:write. Existe também autenticação de sessão para telas (POST /v1/auth/login, depois POST /v1/auth/mfa, produzindo Authorization: Bearer). Uma integração servidor-a-servidor quase nunca precisa dela. Chave de API não alcança, com escopo nenhum, as rotas que o contrato declara só de sessão, que são todas as que os escopos acima não abrem: entre elas POST /v1/auth/step-up, POST /v1/transactions/{id}/review, POST /v1/ted/transfers, a cobrança por boleto (/v1/billets), o pagamento de contas (POST /v1/billets/pay), os agendamentos, os cartões (/v1/cards*), a recarga (/v1/topups*), a exclusão e a portabilidade de chave PIX, a contestação de Pix, a segurança da conta, as assinaturas (/v1/subscription-plans, /v1/subscription*), a rede de indicação (/v1/referrals*), o portal do estabelecimento (/v1/merchant/*), a vitrine de benefícios (GET /v1/marketplace) e o aceite de avisos pelo WhatsApp (/v1/notifications/whatsapp). Elas respondem 403 FORBIDDEN a quem apresenta X-API-Key. O security de cada operação no spec diz qual credencial ela aceita. Públicas, sem credencial: GET /v1/features (funcionalidades ligadas nesta instalação), GET /v1/app/versions, GET /health e GET /ready. ## Módulos por instalação Cada módulo é uma funcionalidade do catálogo que a instalação liga ou desliga; GET /v1/features lista as ligadas. Nascem desligados, em construção: subscriptions planos e assinaturas (tag Assinaturas; só onde há internal_transfer) merchant_portal portal do estabelecimento (tag Estabelecimento) affiliate_network rede de indicação (tag Indicação; só com referrals) marketplace benefícios e vitrine (tag Benefícios) service_fees tarifas por serviço (tag Tarifas; só onde há internal_transfer) pix_key_claims portabilidade de chave (tag PIX; só com pix_keys) business_opening_own abertura de empresa MEI e EI (tag Abertura de conta) GET /v1/fees e GET /v1/fees/quote são os únicos destes que a chave de API lê (accounts:read). Com service_fees ligada, o Pix por chave de API exige expectedFeeCents, a tarifa cotada. Desligado, as rotas do módulo respondem 403 FEATURE_DISABLED com details.feature. Exceção: GET /v1/subscription e POST /v1/subscription/cancel continuam valendo, para o cliente ver e cancelar o plano vivo. Nada na rede de indicação nem na vitrine credita saldo. ## Regras obrigatórias 1. Idempotency-Key é obrigatório em toda chamada que move dinheiro (POST /v1/pix/transfers, POST /v1/pix/brcode/pay, POST /v1/ted/transfers). De 8 a 128 caracteres, único por operação. Sem ele, a resposta é 400 antes de qualquer efeito. POST /v1/billets, POST /v1/subscription (a adesão debita a primeira mensalidade do saldo) e POST /v1/subscription/cancel também o exigem. Derive a chave do pedido que originou o pagamento. Não a gere dentro da função de envio: repetir a mesma operação precisa produzir a mesma chave, senão a repetição vira uma segunda transferência. Repetir a mesma chave com o mesmo corpo devolve a resposta original com o cabeçalho Idempotent-Replay: true. Com corpo diferente, responde 409 IDEMPOTENCY_KEY_REUSED. Enquanto a primeira ainda roda, responde 409 IDEMPOTENCY_IN_FLIGHT com Retry-After. A chave é lembrada por 90 dias. 2. Valores são sempre inteiros em centavos. amountCents: 5000 são R$ 50,00. Não existe campo em reais em lugar nenhum da API. Nunca use ponto flutuante para dinheiro. 3. Transferências a partir de R$ 1.000,00 (100000 centavos, inclusive) exigem um token de step-up no cabeçalho X-Step-Up, e também o envio que leva a soma dos PIX do dia a esse valor (stepUpDailyThresholdCents em GET /v1/limits). O cadastro de chave PIX exige sempre. Obtenha o token em POST /v1/auth/step-up com {"code": "", "purpose": "transfer" | "pix_key" | "review" | "ted" | "subscription" | …} (a lista completa está no spec). A rota é de sessão (Authorization: Bearer), não aceita X-API-Key. A TED exige step-up com purpose "ted" sempre, qualquer que seja o valor; aderir a um plano e cancelá-lo exigem purpose "subscription" sempre. O token vale 5 minutos e serve apenas para o purpose declarado. Se a operação responder 403 BIOMETRIC_REQUIRED, emita a prova de novo com o campo "selfie" (imagem em base64). O step-up é de sessão: o token sai de uma sessão do titular (login e MFA) e vale na chamada seguinte, mesmo que ela use X-API-Key. O cadastro de chave PIX (escopo pix:keys:write, que exige step-up sempre) e o Pix a partir de R$ 1.000,00 dependem desse token. No sandbox, faça login e MFA com as credentials de POST /v1/sandbox/keys e calcule o código (RFC 6238) com o totpSecret. Em produção, o token vem de uma sessão do próprio titular. 4. Trate HELD_FOR_REVIEW como desfecho normal da transferência, e não como erro. A transação foi retida pelo motor de risco e espera a decisão do titular em POST /v1/transactions/{id}/review, com {"decision": "release" | "block"}. Liberar exige X-Step-Up com purpose "review"; bloquear devolve o dinheiro à conta na hora e não exige. 5. Trate erro pelo campo "code", nunca comparando o texto de "message". A mensagem muda com revisão de texto e tradução. ## Formato de erro Toda resposta de erro: {"code": "INSUFFICIENT_FUNDS", "message": "Saldo insuficiente para esta operação.", "requestId": "7c3d4b589e21"} Códigos: INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_IN_FLIGHT, INSUFFICIENT_FUNDS, LIMIT_EXCEEDED, STEP_UP_REQUIRED, BIOMETRIC_REQUIRED, APPROVAL_REQUIRED, RATE_LIMITED, TOO_MANY_ATTEMPTS, PROVIDER_ERROR, FEATURE_DISABLED, DEVICE_NOT_ENABLED, CARD_TERMS_REQUIRED, CARD_ELIGIBILITY_REQUIRED, CARD_KIND_UNAVAILABLE, CARD_BLOCKED_BY_INSTITUTION, CARD_NOT_ACTIVE, CARD_USE_REVEAL, CARD_USE_SECURE_VIEW, INTERNAL_ERROR. PROVIDER_ERROR (503) com details.reason LOCATION_REQUIRED: faltou o cabeçalho X-Client-Location (latitude,longitude), que o provedor exige nas operações em nome da pessoa; nada foi enviado. Mande a localização e repita. BIOMETRIC_REQUIRED (403): valor alto confirmado só com o código, e a instalação exige também a selfie. FEATURE_DISABLED (403, details.feature): funcionalidade desligada nesta instalação; consulte GET /v1/features. APPROVAL_REQUIRED (422): acima da alçada de aprovação conjunta da conta da empresa. Repita apenas 429, 500 e 503, com espera crescente e sempre com a mesma chave de idempotência. Respeite o cabeçalho Retry-After. ## Estados de transação PENDING, PROCESSING, COMPLETED, FAILED, REVERSED, HELD_FOR_REVIEW, BLOCKED. PROCESSING não é estado de repouso: ou o provedor confirma, ou a conciliação resolve. A transferência responde 202, não 201 — o desfecho pode ainda não existir no momento da resposta. ## Webhooks O banco cadastra, a seu pedido, uma URL https que recebe cada mudança de estado de transação da conta como o evento transaction.updated (seção "webhooks" do spec). O corpo é magro: id da transação, tipo, estado e valor em centavos com o mesmo sinal do GET. Confira a assinatura antes de confiar no corpo: X-Lume-Signature é "v1=" + HMAC-SHA256 hexadecimal de ".", com o segredo lume_whsec_ entregue no cadastro; recuse carimbo a mais de 5 minutos. Deduplique por X-Lume-Event-Id. Responda 2xx em até 10 s; outra resposta gera retentativa por até 24 h. Não há ordem garantida: antes de mudar estado, consulte GET /v1/transactions/{id}, que é a fonte de verdade. Com mTLS, o banco apresenta certificado de cliente. POST /v1/webhooks/{provider} existe, mas é o contrário: é por onde o provedor financeiro avisa o Lume, e quem instala o configura. A sua integração não o chama. ## Guardrails Use apenas chaves de sandbox em contexto de ferramenta de IA de terceiros. Uma chave de produção move dinheiro de verdade e não deve entrar no histórico de conversa de nenhum assistente. Não envie dados pessoais reais ao sandbox. A conta emitida já vem com documento, nome e saldo fictícios válidos para teste. ## Páginas https://docbank.lumecoding.com/ Visão geral e primeira chamada https://docbank.lumecoding.com/autenticacao/ Chave, sessão e step-up https://docbank.lumecoding.com/ambientes/ Sandbox e produção https://docbank.lumecoding.com/referencia/ Referência de endpoints https://docbank.lumecoding.com/idempotencia/ Idempotência em detalhe https://docbank.lumecoding.com/erros/ Códigos de erro https://docbank.lumecoding.com/limites/ Limites de taxa e de valor https://docbank.lumecoding.com/postman/ Coleção do Postman https://docbank.lumecoding.com/agentes/ Guia de integração com agentes de IA https://docbank.lumecoding.com/roteiro/ O que ainda não existe https://docbank.lumecoding.com/changelog/ Mudanças por versão Contato: contato@lumecoding.com