Acesso
Toda chamada do ERP à ETech passa pelo gateway de integração. Ela usa três credenciais que a ETech entrega por canal seguro.
- URL base (staging):
https://vm-integration.staging.etechsa.com.br, confirmada na entrega das credenciais. - Produção: a URL será informada na liberação do ambiente.
Credenciais
| Credencial | Onde vai | Para quê |
|---|---|---|
| API key | header x-api-key, em toda chamada | Identifica o cliente no gateway e aplica o limite de uso dele |
client_id | corpo do POST /oauth2/token | Identifica a credencial de integração |
client_secret | corpo do POST /oauth2/token | Prova a posse da credencial |
- O
client_secreté mostrado uma única vez, na entrega. A ETech não consegue recuperá-lo, só gerar outro. - Na troca do segredo, o anterior continua valendo por 7 dias, para a substituição sem parada.
- As três credenciais ficam só no backend do ERP, nunca no app instalado no celular do consumidor.
Token
O backend do ERP troca client_id e client_secret por um token de 30 minutos (OAuth 2.0, client_credentials) e o reaproveita até vencer.
POST /oauth2/token
x-api-key: <api key>
User-Agent: <nome-do-sistema>/<versão>
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>
{ "access_token": "eyJhbGciOi…", "token_type": "Bearer", "expires_in": 1800 }
Toda chamada seguinte leva três headers:
x-api-key: <api key>
Authorization: Bearer <access_token>
User-Agent: <nome-do-sistema>/<versão>
User-Agent obrigatório
O WAF recusa com 403 {"message":"Forbidden"} a requisição sem User-Agent. Alguns clientes HTTP de servidor não o mandam por padrão, como o HttpClient do .NET. Qualquer valor serve; o ideal é o nome e a versão do sistema.
- Não há refresh token. Peça um token novo um pouco antes de
expires_interminar, ou ao receber401. - Credencial errada ou desativada responde
401com"error": "invalid_client". - O token só vale nas rotas
/integration/v1/*. Em qualquer outra rota da ETech, ele é recusado com403.
O exemplo de token mostra o cache e a renovação em C#, Node.js, Python e Java.
Erros comuns a todas as rotas
O corpo do erro vem como { "request": ["<CÓDIGO>"] }. Cada frente lista os códigos próprios; estes valem para todas.
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 401 | — | Token ausente, vencido ou de credencial desativada | Pedir um token novo; se repetir, falar com a ETech |
| 403 | — (gateway) | API key ausente ou inválida, ou requisição sem User-Agent | Conferir os headers x-api-key e User-Agent |
| 403 | AUTH.INTEGRATION_TOKEN_REQUIRED | Token que não veio do client_credentials de integração | Usar o token desta seção |
| 429 | — (gateway) | Limite de uso do cliente atingido | Esperar e reenviar com intervalo crescente |
| 5xx | — | Falha do lado da ETech | Reenviar com intervalo crescente |
Limites e segurança
- Limite inicial de uso: 20 requisições por segundo (picos de 40) e 100 mil por dia, por cliente. Acima disso o gateway responde
429. - Só HTTPS. Chamadas HTTP são recusadas.
- LGPD. CPF e e-mail do consumidor são dados pessoais. Eles não devem ir para log, URL de chamada nem ferramenta de terceiros, nem no backend nem no app.