API tokens
A API ValePix usa API tokens opacos no padrão Bearer token. O cliente recebe o token completo uma única vez por canal seguro e deve armazená-lo como segredo.
Como autenticar chamadas
Envie o token somente no header Authorization:
Authorization: Bearer <VALEPIX_API_TOKEN>
Exemplo:
curl --request GET \
--url "https://routes.valepix.com.br/api/v1/valepix/employees/situations" \
--header "Authorization: Bearer $VALEPIX_API_TOKEN" \
--header "Accept: application/json"
Não envie o token em query string, corpo da requisição, planilhas, tickets públicos ou logs.
Validação do token
Use um API token autorizado para acessar as rotas públicas de produtos, benefícios, colaboradores, lotes, financeiro e distribuições.
Na prática, uma chamada precisa passar por duas verificações:
- O token existe, está ativo e não expirou.
- O token tem acesso ao recurso solicitado.
Erros comuns de autenticação
| HTTP | Causa provável | Ação recomendada |
|---|---|---|
401 | Token ausente, inválido, expirado ou revogado | Conferir header e solicitar novo token se necessário |
403 | Token sem acesso ao recurso solicitado | Confirmar token com a ValePix |
Boas práticas de segurança
- Armazene o token em secret manager, cofre de credenciais ou variável segura do ambiente.
- Restrinja acesso ao token somente aos serviços que chamam a API.
- Nunca registre o token completo em logs de aplicação, observabilidade ou auditoria.
- Mascare tokens em telas internas, exibindo no máximo um prefixo não sensível.
- Use HTTPS sempre.
- Rotacione o token periodicamente ou quando houver suspeita de exposição.
- Revogue o token quando a integração for desativada.
Informações recebidas da ValePix
O cliente deve receber:
- Base URL da API.
- API token completo, entregue uma única vez.
- Exemplos de payload e IDs necessários para a integração, quando aplicável.