Ambientes
Quick Reference
WhatAmbientes de sandbox e produção
WhyConfigure endpoints, entenda o escopo das credenciais e faça sua primeira chamada à API
Reading Time5 min
DifficultyBeginner
PrerequisitesAutenticação
Por que isso importa
| Risco | Consequência | Como a A55 previne |
|---|---|---|
| Usar credenciais de produção em desenvolvimento | Cartões reais são cobrados durante os testes | Pares de credenciais separados por ambiente |
| Apontar para a URL errada por ambiente | Requisições falham ou atingem dados errados | Mesma URL para ambos — as credenciais determinam o comportamento |
| Sem checklist claro de go-live | Bugs vão para produção | Sandbox espelha produção 1:1 — o que funciona em sandbox funciona em produção |
Mesma URL — credenciais diferentes
Sandbox e produção compartilham a mesma URL base e o mesmo host Cognito. O ambiente é selecionado pelo par client_id / client_secret que você utiliza. Verifique quais credenciais você está implantando.
Endpoints
| Finalidade | URL |
|---|---|
| API REST | https://core-manager.a55.tech/api/v1 |
| Token OAuth 2.0 | https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token |
Ambas as URLs são idênticas para sandbox e produção. Suas credenciais determinam o ambiente.
Sandbox vs produção
| Sandbox | Produção | |
|---|---|---|
| Dinheiro | Simulado — sem liquidação | Cobranças e liquidação reais |
| Cartões | Cartões de teste e regras pelo último dígito | Autorização real do emissor |
| Credenciais | client_id / client_secret de sandbox | client_id / client_secret de produção |
| 3DS | Fluxos simulados | Desafios reais do emissor |
| Webhooks | Entregues no seu endpoint | Entregues no seu endpoint |
| Rate limits | Iguais aos de produção | Iguais aos de sandbox |
| Superfície da API | Idêntica | Idêntica |
Verifique seu setup
Defina suas credenciais como variáveis de ambiente, autentique-se e liste as wallets em um único passo.
- cURL
- Python
- JavaScript
# Definir credenciais de sandbox
export A55_CLIENT_ID="sandbox-xxxx-xxxx-xxxx"
export A55_CLIENT_SECRET="sandbox-secret-xxxx"
# Autenticar
TOKEN=$(curl -s -X POST \
https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=$A55_CLIENT_ID" \
-d "client_secret=$A55_CLIENT_SECRET" | jq -r '.access_token')
echo "Token obtido: ${TOKEN:0:20}..."
# Listar wallets
curl -s https://core-manager.a55.tech/api/v1/wallets \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" | jq .
import os
import requests
AUTH_URL = "https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token"
API_BASE = "https://core-manager.a55.tech/api/v1"
client_id = os.environ["A55_CLIENT_ID"]
client_secret = os.environ["A55_CLIENT_SECRET"]
token = requests.post(AUTH_URL, data={
"grant_type": "client_credentials",
"client_id": client_id,
"client_secret": client_secret,
}, headers={"Content-Type": "application/x-www-form-urlencoded"}).json()["access_token"]
print(f"Token obtido: {token[:20]}...")
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
wallets = requests.get(f"{API_BASE}/wallets", headers=headers).json()
print(wallets)
const AUTH_URL = "https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token";
const API_BASE = "https://core-manager.a55.tech/api/v1";
const clientId = process.env.A55_CLIENT_ID;
const clientSecret = process.env.A55_CLIENT_SECRET;
const tokenResp = await fetch(AUTH_URL, {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "client_credentials",
client_id: clientId,
client_secret: clientSecret,
}),
});
const { access_token } = await tokenResp.json();
console.log(`Token obtido: ${access_token.slice(0, 20)}...`);
const wallets = await fetch(`${API_BASE}/wallets`, {
headers: {
Authorization: `Bearer ${access_token}`,
"Content-Type": "application/json",
},
}).then(r => r.json());
console.log(wallets);
Execute agora
Copie o trecho acima, substitua as credenciais pelo seu par de sandbox e execute. Se você visualizar suas wallets, seu ambiente está configurado corretamente.
Configuração de credenciais
Armazene as credenciais por ambiente no seu gerenciador de segredos ou em arquivos .env (nunca versionados no controle de código-fonte).
Sandbox:
export A55_CLIENT_ID="sandbox-xxxx-xxxx-xxxx"
export A55_CLIENT_SECRET="sandbox-secret-xxxx"
export A55_ENV="sandbox"
Produção:
export A55_CLIENT_ID="prod-xxxx-xxxx-xxxx"
export A55_CLIENT_SECRET="prod-secret-xxxx"
export A55_ENV="production"
Nunca misture ambientes
Credenciais de produção em desenvolvimento cobram cartões reais. Credenciais de sandbox em produção falham silenciosamente. Sempre verifique qual par está implantado.
Checklist de go-live
| Etapa | Sandbox | Produção |
|---|---|---|
| 1. Credenciais provisionadas | client_id / client_secret de sandbox | client_id / client_secret de produção |
| 2. Autenticação funciona | Token obtido, API responde | Token obtido, API responde |
| 3. Criar uma cobrança | Cartão de teste, status paid | Cartão real, status paid |
| 4. Webhooks recebidos | Atualizações de status chegam ao seu endpoint | Atualizações de status chegam ao seu endpoint |
| 5. Reembolso testado | Reembolso concluído em sandbox | — |
| 6. 3DS testado | Fluxos frictionless e challenge passam | — |
| 7. Rotação de credenciais | — | Rotacione os segredos, confirme que não há downtime |
Práticas operacionais
| Prática | Descrição |
|---|---|
| Gerenciador de segredos | Armazene credenciais no AWS Secrets Manager, HashiCorp Vault ou equivalente da sua nuvem |
| Sem hardcoding | Nunca versione credenciais no controle de código-fonte |
| Valide em sandbox primeiro | Conclua todos os fluxos antes de solicitar acesso à produção |
| Rotacione regularmente | Rotacione segredos no mínimo trimestralmente |
| Monitore 401s | Alerte sobre falhas de autenticação inesperadas — podem indicar vazamento de credenciais |
Solicitar credenciais
Envie um e-mail para tech.services@a55.tech com o nome da empresa, CNPJ (se aplicável), e-mail de contato, ambiente desejado (sandbox / produção) e uma breve descrição do caso de uso.