Cada ambiente tem operador, chaves e dados próprios. Chaves de um ambiente nunca funcionam em outro.
| Ambiente | Uso | Prefixo da chave | Dados |
|---|---|---|---|
| Sandbox | Construção e homologação ponta a ponta (saiba mais) | bk_test_ |
Marca isolada, dados fictícios |
| Produção | Operação real | bk_live_ |
Reais |
O endereço da API é o mesmo nos dois ambientes: a chave define o ambiente. GET /api/v1/me confirma qual é.
Como solicitar acesso
Credenciais não são publicadas nesta documentação. Para receber as chaves de sandbox, fale com a equipe informando:
- o nome da operadora e o responsável técnico;
- os IPs de saída do seu servidor (a API pode restringir cada operador a uma lista de IPs);
- a URL HTTPS onde receberá os webhooks;
- os papéis e alçadas da sua equipe de operação.
O que você recebe
X-Operator-Key: identificador público da credencial (bk_test_…oubk_live_…).- Secret (
sk_…): usado para assinar as requisições com HMAC. É mostrado uma única vez. - Segredo de webhook (
whsec_…): usado para verificar as entregas de eventos. Também mostrado uma única vez. - O host da API do seu ambiente.
Boas práticas de guarda
- Armazene o secret em um cofre de segredos do seu servidor; nunca em repositório, front-end ou logs.
- Use credenciais diferentes por ambiente.
- Rotação sem parada: peça uma nova credencial (a antiga continua válida), troque no seu servidor e só então peça a revogação da antiga.
- Ao suspeitar de vazamento, peça a revogação imediata e uma nova credencial.
Limites padrão
Cada operador tem, por padrão, 600 requisições por minuto. Consulte limites de uso.
Validar a integração
A rota GET /api/v1/me devolve o operador, a marca e o ambiente (environment, brand.isSandbox) associados à credencial. É a forma mais simples de confirmar que a assinatura HMAC está correta. Depois siga os primeiros passos.