Chaves de API
Toda chamada em nome do vendedor é autenticada por uma chave criada no painel. Existem dois tipos: chave secreta e par de chaves.
Dois tipos de chave
| Tipo | Como autentica | Quando usar |
|---|---|---|
| Chave secreta | Header X-API-Key com o segredo pk_live_… | Integração rápida; o segredo trafega em toda chamada |
| Par de chaves | Você assina cada requisição com a chave privada | Recomendado: o segredo nunca sai do seu servidor e a requisição não pode ser reenviada |
As duas valem nas mesmas rotas. Veja chave assinada para o segundo tipo.
Chave secreta
Crie em Integrações & APIs no painel. O segredo aparece uma única vez.
Header
X-API-Key: pk_live_a1b2c3d4...Use apenas no seu servidor. Uma chave exposta no navegador ou no aplicativo permite criar cobranças e pedir saques em seu nome.
Permissões
Cada chave carrega as permissões escolhidas no cadastro. Sem a permissão, a rota responde 403.
| Permissão | Libera |
|---|---|
| sales | Criar cobranças e consultar pagamentos |
| balance:read | Consultar o saldo da conta |
| withdraw:create | Pedir saques e consultar um saque |
IPs autorizados
Você pode restringir a chave a uma lista de IPs. A comparação é exata: se o seu servidor sai por IPv6, cadastre o endereço IPv6 (dá para cadastrar IPv4 e IPv6 na mesma chave). Fora da lista, a resposta é 403. Na chave assinada, informar ao menos um IP é obrigatório.
Limites e erros
| Situação | Resposta |
|---|---|
| Chave ausente | 401 · API key não fornecida |
| Chave inválida, pausada ou revogada | 401 |
| Vendedor bloqueado | 401 |
| IP fora da lista | 403 |
| Permissão faltando | 403 · Esta API key não possui a permissão '…' |
| Mais de 10 chaves ativas | 400 no momento de criar |
Testar a chave (consulta de saldo)
curl "https://api.apix.tec.br/@seller/withdraw/balance" -H "X-API-Key: pk_live_a1b2c3d4..."