Ambientes
Sandbox e produção na mesma organização, separados por workspace e por API key.
Cada organização tem dois ambientes financeiros: sandbox, com a Stripe em test mode, e produção, com dinheiro real. Eles são workspaces da mesma organização, e cada um tem a sua conta conectada. Clientes, produtos, preços, pagamentos, páginas de checkout e endpoints de webhook ficam no ambiente em que foram criados.
Como o ambiente é escolhido
A credencial da requisição define o ambiente. A URL da API e a organização no caminho são as mesmas nos dois.
| Credencial | Ambiente da operação |
|---|---|
API key pk_test_… | Sandbox |
API key pk_live_… | Produção |
| Sessão no painel | Ambiente do workspace selecionado |
Escolha o ambiente ao criar a chave, no campo Ambiente da tela de API keys (Teste ou Produção). Ele não muda depois: para trocar de ambiente, crie outra chave.
Uma chave por ambiente
Guarde a chave de sandbox e a de produção em configurações separadas do seu servidor. Uma chave pk_test_ nunca alcança dados de produção, e uma pk_live_ nunca alcança dados de sandbox.
Configure ADILA_PAY_BASE_URL com https://api-pay.adila.co. Não use o endereço da documentação como base da API.
Acesso dos membros
Owner e admin operam nos dois ambientes. developer e viewer só operam no ambiente de workspaces a que têm acesso. Fora deles, a API responde 403 com code: "workspace_access_required".
Cada pessoa tem uma organização. Criar uma segunda organização retorna 409: use os workspaces de sandbox e produção da mesma organização.
Prepare o teste
- Crie uma API key com o ambiente Teste e as permissões necessárias.
- Conclua o onboarding da conta conectada de sandbox.
- Configure URL, UUID da organização e API key no servidor da aplicação.
- Faça uma consulta de clientes antes de executar operações de escrita.
IDs de clientes, produtos e preços de sandbox não existem em produção. Recrie o catálogo no ambiente de produção antes de operar.
O que validar
| Cenário | Verificação |
|---|---|
| Consulta inicial | A chave acessa apenas os recursos da organização e do ambiente esperados |
| Catálogo | Produto e preço foram criados no mesmo ambiente do checkout |
| Nova operação | A chave de idempotência foi persistida antes da requisição |
| Repetição de operação | O retry usa a mesma chave e os mesmos parâmetros |
| Checkout | A sessão abre a página hospedada da conta conectada |
| Confirmação | Seu servidor consulta o estado financeiro antes de liberar acesso |
| Falhas | A aplicação trata erros de credencial, permissão e disponibilidade |
Erros de ambiente
| Resposta | Causa provável |
|---|---|
403 workspace_access_required | O membro não tem acesso a um workspace desse ambiente |
409 | A conta conectada desse ambiente ainda não existe, tem onboarding pendente ou foi desconectada |
503 | O ambiente não está habilitado nesta instalação |
Webhooks também seguem o ambiente: o envelope traz livemode, e eventos sintéticos de teste só existem no sandbox.
Continue com Primeira integração ou revise o guia de produção.