Perguntas frequentes
Dúvidas comuns na integração da API Smart POS.
O ConnectTEF processa o pagamento?
Não. O pagamento acontece no Smart POS da adquirente. O ConnectTEF faz a ponte entre o sistema comercial e o Smart POS, e padroniza o retorno.
Posso finalizar a venda com a resposta inicial?
Não. A resposta inicial só confirma que a operação foi aceita, enviada ou colocada na fila manual. Finalize a venda apenas quando receber um evento final como pagamento.aprovado.
O que é referência?
É o identificador da tentativa operacional enviada à API, não o número da venda, pedido, mesa, comanda ou cupom. Gere uma nova referência para cada pagamento, estorno ou impressão enviado, inclusive nova tentativa da mesma venda após cancelamento, recusa, troca de cartão ou falha de comunicação. Use preferencialmente um UUID começando no primeiro caractere. Se precisar identificar sistema, loja ou caixa, coloque essa informação somente depois do UUID, como sufixo.
O que acontece se eu repetir uma referência?
A API pode recusar a solicitação como duplicada. Repita a referência apenas para consultar, conciliar ou tratar webhook de uma operação já criada. Para qualquer nova tentativa enviada à API, mesmo da mesma venda, gere uma nova referência.
Preciso enviar a URL do webhook em cada operação?
Não. Configure a URL uma vez no portal do parceiro, no menu Integração. O token é recomendado, mas opcional.
smartposId é obrigatório?
Em pagamento imediato, sim. Em pagamento manual, pode ser omitido para publicar nos Smart POS disponíveis do cliente. Em estorno e impressão, sim, porque a operação precisa mirar um Smart POS específico.
Posso ler um novo QR Code em uma Smart POS já vinculada?
Sim, se for o mesmo Smart POS e o mesmo cliente. A leitura atualiza a identificação técnica do terminal e envia novamente o webhook smartpos.identificado. Ela não remove o vínculo atual, não bloqueia o terminal e não impede pagamentos que já estão funcionando. Trate o evento como idempotente: se o smartposId já existir no seu ERP, apenas atualize o cadastro existente. Não é necessário desvincular previamente.
Como coloco uma cobrança na fila do operador?
Use modoExecucao manual e envie comanda. O Smart POS exibirá um card para o operador iniciar quando decidir.
O que faço se o Smart POS recusar o pagamento?
Não finalize a venda. Trate pagamento.recusado como resultado final da operação, exiba a mensagem operacional quando disponível e permita nova tentativa quando fizer sentido.
Quais dados preciso guardar para estorno?
Guarde smartposId, autorizacao.codigo, autorizacao.numeroTransacao, autorizacao.dadosFinalizacao e autorizacao.tipoPagamento recebidos em pagamento.aprovado.
A API key pode ficar no frontend?
Não. Mantenha a chave no backend, função serverless ou cofre de segredo.
Como valido se minha chave está ativa?
Use GET /v1/health com o header x-api-key.
Meu webhook pode receber o mesmo evento mais de uma vez?
Sim. Reenvio manual e retentativas operacionais podem entregar o mesmo evento novamente. Use o campo id do evento para processar de forma idempotente.
O que fazer se meu webhook falhar?
Corrija URL, token, firewall, DNS, certificado ou disponibilidade do endpoint e use o portal para reenviar. A operação no Smart POS não é desfeita por falha de webhook.