Smart TEF
Guia rápido para integração externa com cards, webhooks e operações do Smart TEF.
O Smart TEF permite que ERPs, PDVs, sistemas de retaguarda e plataformas externas criem ordens de pagamento, impressão e coleta de dados por API. A aplicação cliente acompanha o processamento por consulta ativa ou por webhook.
Conectado via API ou pela criação manual de cards, o Smart TEF transforma a Smart POS em um terminal integrado ao seu sistema, sem cabos ou equipamentos adicionais.
Escopos de integração
A documentação está organizada por público de consumo:
| Escopo | Quando usar |
|---|---|
| ERP Loja | Integrações da própria loja: pagamentos, impressões, formulários, consultas, usuários, terminais, webhook e configuração da loja. |
| Integrador | Integrações que administram lojas vinculadas: ativação, bloqueio, geração ou revogação de token e reprocessamento de webhook no contexto do integrador. |
Use o token compatível com o escopo da operação. Um token de loja não substitui um token de integrador, e um token de integrador não deve ser usado para operações operacionais da loja fora das rotas previstas.
Objetivo
Servir como guia de referência para integração via API do Smart TEF com sistemas ERP, retaguarda e operações externas.
Público-alvo
Parceiros e clientes que precisam integrar sistemas externos ao Smart TEF.
Pré-requisitos
- Loja criada e habilitada no Smart TEF.
- Bearer Token para acesso à API.
- Gateway Token para chamadas protegidas.
- Credenciais do portal com usuário administrador e operador.
- URL pública para webhook, quando desejar receber atualizações automáticas.
- Terminal ativado no ambiente, quando a operação exigir envio para POS.
Parceiros White Label devem solicitar esses pré-requisitos ao atendimento comercial antes do início da integração.
O que você encontra nesta aba
- Autenticação com tokens, headers e boas práticas.
- Referência com status, tipos e convenções.
- Card de pagamento com criação, consulta, cancelamento e estorno.
- Card de impressão com criação, consulta e cancelamento.
- Formulários para coleta de dados estruturados.
- Webhook para callbacks de status e reprocessamento.
- Lupa online para pesquisa e criação de cards sob demanda.
- Anonimização para remoção de dados pessoais.
- Histórico com versões do guia.
Fluxo recomendado
- Configure loja, usuários, terminais e webhook quando necessário.
- Crie uma ordem de pagamento, impressão ou formulário.
- Guarde o identificador retornado pela API.
- Consulte o status por polling ou receba atualizações via webhook.
- Cancele ordens pendentes, solicite estorno de pagamentos concluídos ou anonimize dados pessoais quando aplicável.
Respostas e erros
As respostas de sucesso e erro seguem um envelope JSON com status e data. Em erros de validação ou regra de negócio, data.message pode retornar uma lista de mensagens ou objetos com o campo inválido.
| HTTP | Significado |
|---|---|
200 / 201 | Requisição aceita e processada. |
400 | Erro de validação ou regra de negócio. |
401 | Token ausente, inválido, bloqueado ou incompatível com a operação. |
404 | Recurso não encontrado. |
409 | Conflito, como duplicidade funcional ou operação incompatível com o estado atual. |
500 | Erro inesperado no processamento. |
Tabela de status de retorno
| Status | Descrição |
|---|---|
PDT | Pendente |
PROC_PAG | Processando pagamento |
CNC | Concluído |
CAN_ERP | Cancelado pelo ERP |
REJ_PAG | Pagamento rejeitado |
SOL_EST | Solicitou estorno |
PROC_EST | Processando estorno |
EST | Estornado |
REJ_EST | Estorno rejeitado |
IMP | Impresso |
REJ | Rejeitado |
PROC | Processando |
Tipos de pagamento
| Tipo | Descrição |
|---|---|
CREDIT | Crédito |
DEBIT | Débito |
PIX | Pix |
VOUCHER | Voucher |
OTHERS | Campo livre para o operador escolher a forma de pagamento no POS. |
Operações exibidas no POS
| Operação | Cor |
|---|---|
| Pagamento | Cinza |
| Cancelamento | Vermelho |
| Impressão | Amarelo |
Arquitetura
O ERP cria uma ordem no Smart TEF por API e passa a acompanhar o ciclo de vida dessa ordem por consulta ativa ou webhook. A API mantém o estado do card, entrega a solicitação ao Smart POS e recebe o resultado do processamento feito no terminal.
Principais endpoints
| Operação | Endpoint |
|---|---|
| Criar pagamento | POST /smarttef/commands/erp/order/create |
| Consultar pagamento | POST /smarttef/pooling/erp/order/get |
| Listar pagamentos por período | POST /smarttef/pooling/erp/order |
| Cancelar pagamento pendente | POST /smarttef/commands/erp/order/status/cancelar |
| Solicitar estorno | POST /smarttef/commands/erp/order/status/estornar |
| Criar impressão | POST /smarttef/commands/erp/print/create |
| Consultar impressão | POST /smarttef/pooling/erp/print/get |
| Cancelar impressão pendente | POST /smarttef/commands/erp/print/status/cancelar |
| Criar formulário | POST /smarttef/commands/erp/form/create |
| Configurar webhook da loja | POST /smarttef/manager/erp/store/update |
| Anonimizar pagamentos | POST /smarttef/manager/erp/store/payments/anonymize |