Configurar Webhooks e Notificações

Como as interações com os terminais físicos levam tempo (ex.: aguardar a digitação do PIN), a Get Smart API Cloud retorna o resultado final de uma transação de forma assíncrona.

Para receber este resultado, você deve expor um endpoint HTTP público (Webhook) no seu servidor. A API Cloud enviará uma requisição POST para esta URL contendo os detalhes finais da transação, códigos de autorização e dados do recibo.

Configuração

Você define para onde enviar a notificação por requisição. Isso significa que você pode direcionar diferentes transações para diferentes endpoints, se necessário.

Em cada chamada de API (Pagamento, Estorno, Pré-autorização), inclua o objeto notificacion:

{
  "info": {
    "notificacion": {
      "urlNotificacion": "https://your-server.com/api/webhooks/payments",
      "correoNotificacion": "admin@merchant.com"
    },
    ...
  }
}

• urlNotificacion: O canal principal. Deve ser uma URL HTTPS acessível publicamente.
• correoNotificacion: O canal de fallback. Se o seu servidor estiver indisponível ou retornar um erro (diferente de 200), o sistema enviará o resultado por e-mail para este endereço.

O Payload de Notificação

Quando o terminal terminar o processamento, seu servidor receberá um payload JSON.

Método: POST

Content-Type: application/json

Exemplo de Payload

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timeStamp": "20250428 111500",
    "datosRespuesta": {
      "tipoPago": "PAGO",
      "importe": "25.50",
      "moneda": "978",
      "factura": "ORD-2025-001",
      "resultado": "Autorizada",
      "codigoRespuesta": "998877",
      "estado": "F",
      "tarjetaClienteRecibo": "************1234",
      "marcaTarjeta": "1",
      "Literales": {
         "autenticadoPorPin": "OPERACION CON PIN. FIRMA NO NECESARIA."
      }
    }
  },
  "signature": "INCOMING_SERVER_SIGNATURE"
}

Campos Principais para Processar

Protegendo seu Webhook

Como a URL do seu webhook é pública, qualquer pessoa poderia, teoricamente, enviar requisições falsas para ela. Você deve verificar a assinatura de cada notificação recebida.

Passos para Verificação

1. Capturar o Corpo Bruto (Raw Body): Leia o corpo JSON recebido.
2. Extrair info: Separe o objeto info da signature.
3. Calcular o Hash: * Minimize a string JSON do info (remova espaços em branco).
   • Adicione sua Chave Secreta.
   • Calcule o SHA-256.
4. Comparar: Verifique se o hash que você calculou corresponde à signature no payload.

Aviso de Segurança: Se as assinaturas não corresponderem, descarte a requisição imediatamente. Não atualize o status do seu pedido nem libere as mercadorias.

Melhores Práticas

1. Idempotência

Retentativas de rede podem fazer com que você receba a mesma notificação duas vezes. Certifique-se de que seu sistema possa lidar com requisições duplicadas para a mesma factura (ID da Fatura) sem cobrar o cliente duas vezes ou corromper seu banco de dados.

2. Confirme (Acknowledge) Rapidamente

Seu servidor deve retornar um status 200 OK imediatamente após receber e armazenar os dados do webhook. Se você demorar muito para responder, a API Cloud pode considerar a entrega como falha e acionar o fallback por e-mail.

3. Trate os Fallbacks

Se você receber uma notificação por e-mail (porque seu servidor estava indisponível), ele conterá os mesmos dados em um formato legível por humanos. Você pode precisar de um processo manual para atualizar os pedidos com base nesses e-mails caso seu sistema automatizado falhe.

Solução de Problemas

Próximos Passos

• Consultar Histórico de Transações: Se você perdeu um webhook, use o endpoint de Consulta para buscar o status manualmente.
• Especificações de Impressão de Recibos: Aprenda como formatar os dados de Literales e datosDCC em comprovantes impressos.