Webhook

Configure um webhook para receber atualizações de status sem depender apenas de consultas por polling.

O webhook é indicado para acompanhar eventos de pagamento e impressão. Para formulários, use a consulta do próprio formulário quando precisar confirmar preenchimento ou cancelamento.

Configurar webhook da loja

POST /smarttef/manager/erp/store/update

{
  "webhookUrl": {
    "url": "https://erp.example.com/webhooks/smart-tef",
    "authorization_token": "Bearer token-do-erp"
  },
  "payment_external_hook": {
    "url": "https://erp.example.com/smart-tef/busca",
    "authorization_token": "Bearer token-do-erp"
  },
  "name": "Loja Exemplo",
  "trademark": "Loja Exemplo",
  "contact_tel": "71999999999",
  "city": "Salvador",
  "uf": "BA",
  "district": "Centro",
  "address": "Rua Exemplo, 100",
  "zip_code": "40000000"
}

Campo	Obrigatório	Descrição
`webhookUrl.url`	Não	URL que receberá eventos de status.
`webhookUrl.authorization_token`	Não	Valor enviado no header `Authorization` do callback.
`payment_external_hook.url`	Não	URL usada para busca externa de pagamentos, quando contratada.
`name`	Não	Razão social ou nome da loja.
`trademark`	Não	Nome fantasia.
`contact_tel`	Não	Telefone de contato.
`city`	Não	Cidade.
`uf`	Não	UF.
`district`	Não	Bairro.
`address`	Não	Endereço.
`zip_code`	Não	CEP.

O campo payment_external_hook também é usado no fluxo de Lupa online.

Quando o webhook é enviado

Evento	Comportamento
Pagamento processado no POS	Envia o payload de pagamento com o status atualizado.
Impressão processada no POS	Envia o payload de impressão com o status atualizado.
Criação ou cancelamento pelo ERP	A operação altera o status e pode ser consultada por polling. Use reprocessamento quando precisar reenviar um evento.

O endpoint do parceiro deve responder com sucesso HTTP para evitar necessidade de reprocessamento operacional. Guarde o identificador do card recebido no payload para conciliar eventos duplicados ou reenviados.

Exemplo de payload enviado para pagamento

Quando um POS altera o estado de um card, o Smart TEF envia o JSON correspondente para o webhook configurado.

{
  "acquirer": null,
  "acquirer_cnpj": null,
  "autorization_code": null,
  "batt_level": 58,
  "card_brand": null,
  "charge_id": "570",
  "charging": false,
  "cnpj": "22140418000160",
  "conn_type": 1,
  "controle_versao": "Versão 1.3.4",
  "coupon": null,
  "create_at": "2026-02-25T16:05:56.853Z",
  "extras": {},
  "fee_type": null,
  "has_details": false,
  "installments": 1,
  "location": {
    "lat": "1231311",
    "long": "1231313"
  },
  "nsu_host": null,
  "nsu_sitef": null,
  "order_type": "NRM",
  "payment_date": null,
  "payment_extras": null,
  "payment_identifier": "019c9631-91d1-72ca-9fdf-aed3a471b92b",
  "payment_status": "PROC_PAG",
  "payment_type": "OTHERS",
  "payment_value": null,
  "reason": null,
  "refound_coupon": null,
  "refund_autorization_code": null,
  "refund_date": null,
  "refund_serial_pos": null,
  "refund_user_id": null,
  "serial_pos": "6502T1",
  "type": "PAYMENT",
  "update_at": "2026-02-25T16:05:58.690Z",
  "user_id": 24,
  "value": "10"
}

Importante

No card de pagamento, a propriedade type será sempre PAYMENT.

Os campos seguem a mesma estrutura descrita em Card de pagamento. Campos enviados pela adquirente podem permanecer null até a conclusão.

Exemplo de payload enviado para impressão

{
  "cnpj": "22140418000160",
  "create_at": "2026-02-25T16:13:46.286Z",
  "file": "https://storage.example.com/smart-tef/019c9638-print.png",
  "has_details": true,
  "location": {
    "lat": "12",
    "long": "12"
  },
  "order_type": "CRD_UNICO",
  "print_id": "460",
  "print_identifier": "019c9638-bb85-7e8f-8a5a-6899ee9f6f9a",
  "print_status": "PROC",
  "reason": null,
  "serial_pos": "6502T1",
  "type": "PRINT",
  "update_at": "2026-02-25T16:13:50.773Z",
  "user_id": 24
}

Importante

No card de impressão, a propriedade type será sempre PRINT.

Os campos seguem a mesma estrutura descrita em Card de impressão.

Reprocessar webhook

Para reenviar um evento no contexto da loja:

POST /smarttef/commands/erp/webhook/send

Para reenviar um evento no contexto de integrador:

POST /smarttef/commands/erp/webhook/send

Use o reprocessamento quando o endpoint parceiro estiver indisponível, responder com erro ou precisar receber novamente o evento após correção operacional.

No contexto de integrador, o reprocessamento deve ser usado apenas para eventos de lojas vinculadas ao integrador autenticado.