Integração do ERP com a ETech

A integração liga a plataforma de vending da ETech ao backend do cliente em cinco frentes. Este portal é o guia para o time que desenvolve o lado do ERP. Ele traz as rotas, os contratos, os erros e o roteiro de homologação.

As cinco frentes

Frente	Quem chama	O que passa
Verificação de maioridade	ERP → ETech	O resultado da validação feita no app do cliente
Webhook de venda	ETech → ERP	Cada venda concluída, estornada, com NFC-e emitida ou com a nota pedida por e-mail
Produto e estoque	ERP → ETech	Cadastro por EAN, entrada no depósito e consulta de saldo
Benefícios do consumidor	ETech → ERP	Saldo, regra e código de confirmação do programa de fidelidade
NFC-e pelo ERP externo	ETech → ERP	A ordem de emitir, o pedido de e-mail e o cancelamento. Opcional: o ERP devolve a chave da nota

Os benefícios do consumidor e a NFC-e pelo ERP externo dependem do webhook de venda: os dois movimentam saldo e nota a partir dos eventos dele. Implemente o webhook antes dessas duas frentes.

Direção das chamadas

• ERP → ETech. O ERP chama as rotas /integration/v1/* pelo gateway de integração, com as credenciais descritas em Acesso.
• ETech → ERP. A ETech chama o endereço e o header de autenticação que o administrador da organização cadastra no painel. O ERP implementa as rotas descritas em cada frente.

Ambientes

Ambiente	URL base	Situação
Staging	https://vm-integration.staging.etechsa.com.br	Confirmada na entrega das credenciais
Produção	Informada na liberação do ambiente	Liberada depois da homologação

Toda frente passa pelo checklist de homologação em staging antes de ir para produção. As frentes de venda usam uma máquina de teste da ETech.

Como começar

1. Peça as credenciais de staging ao seu contato na ETech. Elas chegam por canal seguro.
2. Obtenha um token seguindo Acesso e o exemplo de token.
3. Escolha as frentes do seu projeto e implemente cada uma pelo guia dela.
4. Teste na Referência da API, que chama staging com as suas credenciais:
   1. Informe a API key em Authentication.
   2. Rode POST /oauth2/token com o seu client_id e client_secret.
   3. Cole o access_token devolvido no campo Bearer e chame as outras rotas.
5. Passe pelo checklist de homologação e combine a liberação de produção.

Contrato versionado

O documento OpenAPI da integração está em /openapi/integration-v1.yaml. Ele pode gerar clientes e ser importado no Postman ou no Insomnia. As mudanças ficam no Changelog.