Ambientes
Duas URLs, dois prefixos de chave. O que você construir contra o sandbox funciona em produção trocando esses dois valores.
| Ambiente | URL base | Prefixo da chave |
|---|---|---|
| Sandbox | https://sandbox.api.lumecoding.com | lume_sk_sandbox_ |
| Produção | https://api.lumecoding.com | lume_sk_live_ |
O que o sandbox é
O mesmo código de produção, com banco de dados isolado, dados fictícios e um provedor de pagamentos simulado no lugar do arranjo real. O que é simulado é só a liquidação: as validações, os limites, o motor de risco, a idempotência e o razão são os de produção.
- Cada chave tem a própria conta. Se todas apontassem para uma conta comum, a primeira transferência de um desenvolvedor mudaria o saldo que o próximo vê, e o extrato viraria a soma dos testes de estranhos.
- As respostas têm a mesma forma nos dois ambientes. Mesmos campos, mesmos códigos de erro, mesmos estados de transação.
- Nada aqui liquida de verdade. O dinheiro é fictício e nenhuma movimentação sai do ambiente de testes.
Como provocar os caminhos de erro
Testar só o caminho feliz é como não testar. O provedor simulado do sandbox tem gatilhos determinísticos — o mesmo dado produz sempre o mesmo desfecho, então dá para escrever teste automatizado em cima deles:
| Para obter | Faça |
|---|---|
PROVIDER_ERROR — chave inexistente no DICT | Use uma chave cujo último caractere seja zero: um CPF terminado em 0, como 637.129.261-70, ou um telefone terminado em 0. Qualquer outra chave sintaticamente válida existe no DICT. Responde 422, e não 404: quem recusou foi o arranjo. |
STEP_UP_REQUIRED | Transfira R$ 1.000,00 ou mais sem o cabeçalho X-Step-Up — ou faça duas de R$ 600,00 no mesmo dia: a que leva a soma do dia a R$ 1.000,00 também pede o código. |
LIMIT_EXCEEDED | Some mais de R$ 5.000,00 no mesmo dia, mandando X-Step-Up: depois que a soma do dia chega a R$ 1.000,00, cada envio pede o código, e o step-up é conferido antes do limite. O mesmo vale para o teto por operação (R$ 2.000,00) e o noturno (R$ 1.000,00). |
HELD_FOR_REVIEW | Não tem gatilho fixo: a retenção vem do motor de risco, que soma sinais (contato novo, horário, aparelho desconhecido, ritmo de envios, conta recente) e só retém com pelo menos dois. Os que pesaram voltam em riskSignals. Entre 20h e 6h, mais de R$ 100,00 para uma chave nunca usada não retém: é recusado com LIMIT_EXCEEDED. |
IDEMPOTENCY_KEY_REUSED | Repita a mesma chave de idempotência com um valor diferente no corpo. |
O nome do titular que a consulta ao DICT devolve no sandbox é fictício e sorteado a partir da própria chave — não é o nome de nenhuma conta de teste sua. Sempre o mesmo para a mesma chave, o que mantém os testes estáveis.
Como trocar de ambiente
Duas variáveis. Se a sua integração tem qualquer outra coisa dependendo do ambiente, é sinal de que algo específico do sandbox vazou para o código:
# sandbox
LUME_BASE_URL=https://sandbox.api.lumecoding.com
LUME_API_KEY=lume_sk_sandbox_…
# produção
LUME_BASE_URL=https://api.lumecoding.com
LUME_API_KEY=lume_sk_live_…A chave carrega o próprio ambiente: apontar uma chave de sandbox para produção responde 401, e a mensagem diz exatamente qual dos dois valores está errado. É uma conferência a mais de propósito — trocar a URL e esquecer a chave é o erro mais comum da virada.
Chave de produção
Não sai por autoatendimento. É emitida comercialmente, depois da assinatura, e vinculada à conta do cliente. Fale com quem cuida da sua conta, ou escreva para o suporte a desenvolvedores.
O segredo é entregue na emissão, mas a chave só passa a valer depois de uma segunda aprovação interna do banco. Até lá, toda chamada com ela recebe 401 com a mensagem “aguardando a aprovação do banco” — não é a sua integração que está errada. A chave de produção é só de leitura e pode ser restrita aos endereços de onde o seu sistema sai: de fora deles, a resposta é 403. Para mudar endereços, ritmo ou acesso, o banco emite outra chave e revoga a antiga.
Rodar contra a sua máquina
O backend sobe sem banco de dados nenhum, com carga de demonstração em memória. Útil para depurar sem rede:
cd backend && go run ./cmd/api # :8080
curl -X POST http://localhost:8080/v1/sandbox/keys \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]"}'Nada persiste entre execuções — é modo de demonstração. Para um sandbox que sobrevive a um reinício, aponte DATABASE_URL para um Postgres e declare LUME_ENV=development (com banco, a API não sobe sem o ambiente declarado): as migrações rodam sozinhas no arranque.