Primeiros passos
Autenticação
Tokens, headers e credenciais necessários para consumir a API Smart TEF.
Os endpoints da API Smart TEF usam JSON e autenticação por Bearer Token. Em rotas protegidas, também pode ser necessário enviar o Gateway Token no header de assinatura.
Headers comuns
| Nome | Descrição | Valor |
|---|---|---|
Authorization | Bearer Token recebido na criação da loja ou do integrador. | Bearer <token> |
ocp-apim-subscription-key | Gateway Token recebido na criação da loja. | <subscription-key> |
Content-Type | Tipo de conteúdo da requisição. | application/json |
Token da loja
Use o token da loja para operações do dia a dia, como criar pagamentos, consultar status, configurar webhook, gerenciar usuários e terminais da própria loja.
Quando a loja for gerenciada por um integrador, o token pode ser gerado pela rota:
POST /smarttef/manager/integrator/store/get/tokenToken do integrador
Use o token do integrador apenas para operações de gestão sobre lojas integradas, como ativação, bloqueio, desbloqueio, reativação e revogação de token.
Escopo e autorização
| Contexto | Regra |
|---|---|
| Loja | A operação fica limitada à loja representada pelo token. Quando um payload aceitar cnpj, ele deve ser o mesmo CNPJ associado ao token. |
| Integrador | O integrador precisa estar ativo e autorizado a operar sobre a loja informada. Operações de integrador não substituem o token operacional da loja. |
| Terminal | Operações executadas no POS dependem de terminal ativo, pertencente à loja e não bloqueado. |
| Operador | Quando a operação receber user_id, o usuário deve pertencer à loja e estar apto a operar no Smart TEF. |
Direcionamento de ordens
Ordens podem ser abertas para a lista geral ou direcionadas para um destino específico:
order_type: "NRM"deixa o card disponível na lista de operações.order_type: "CRD_UNICO"direciona o card para um único destino e exige apenasuser_idou apenasserial_pos.user_ideserial_posnão devem ser enviados juntos na mesma ordem.
Credenciais de portal
Tenha disponível pelo menos:
- Um usuário administrador para configurações.
- Um usuário operador para fluxos operacionais.
- Loja criada e habilitada no ambiente correto.
- Terminal ativado, quando o fluxo depender de card direcionado a POS.
Observações
- Parceiros White Label devem solicitar habilitação comercial antes de começar.
- Nem todos os endpoints exigem as mesmas credenciais, mas o
Authorizationdeve ser tratado como obrigatório na integração. - Use HTTPS para webhook e para qualquer endpoint exposto publicamente pelo ERP.
Boas práticas de segurança
- Guarde tokens em variáveis de ambiente ou cofre de segredos.
- Não exponha tokens em aplicações frontend.
- Revogue e gere um novo token quando houver suspeita de vazamento.
- Registre somente identificadores técnicos nos logs e evite armazenar payloads completos com dados pessoais.