Perguntas frequentes
Dúvidas comuns na integração da API SmartPOS.
O ConnectTEF processa o pagamento?
Não. O pagamento acontece no SmartPOS da adquirente. O ConnectTEF faz a ponte entre o sistema comercial e o SmartPOS, 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 SmartPOS disponíveis do cliente. Em estorno e impressão, sim, porque a operação precisa mirar um SmartPOS específico.
Como coloco uma cobrança na fila do operador?
Use modoExecucao manual e envie comanda. O SmartPOS exibirá um card para o operador iniciar quando decidir.
O que faço se o SmartPOS 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 SmartPOS não é desfeita por falha de webhook.