Webhook (POST para o seu URL)
HTTP POST com um corpo JSON estruturado no momento em que uma leitura é bem-sucedida. Configure um URL, autenticação HTTP Basic opcional, e está pronto. iOS e Android.
Webhooks e Automação
iOSAndroidCinco gatilhos incorporados disparam no momento em que lê uma tag NFC, um código QR ou um código de barras - POST para o seu próprio servidor, abre o URL, executa um Atalho, lê o resultado em voz alta ou reproduz um som. A NFC.cool é o leitor; você controla a ação.
Os Cinco Gatilhos
Atalho (iOS)
Quando um URL lido tem um esquema `shortcuts://`, executa automaticamente o Atalho do iOS correspondente - sem um toque adicional. Encaminhe os dados da leitura para tudo o que os Atalhos conseguem alcançar.
Abrir Ligações (iOS)
Quando o payload é um URL normal, abre-o automaticamente no Safari (ou no destino de ligação direta correspondente). Salte o passo de 'tocar para abrir'.
Síntese de Voz (iOS)
Leia o payload lido em voz alta, com as mãos livres. Velocidade da fala configurável. Útil para acessibilidade, fluxos de trabalho com as mãos ocupadas, ou apenas uma confirmação satisfatória.
Reproduzir Áudio (iOS)
Reproduza um som de confirmação na leitura - o seu próprio ficheiro de áudio à escolha ou um dos tons incorporados.
Como Funciona o Webhook
Gatilhos - NFC, QR e Código de Barras
iOSAndroidOs webhooks disparam a partir de três fontes de eventos: leituras NFC, leituras QR e leituras de códigos de barras. Cada fonte tem o seu próprio interruptor de ativar/desativar, para que possa encaminhar as leituras NFC para o seu sistema de inventário sem que o leitor de câmara inunde o mesmo endpoint. O webhook em si é o mesmo - um URL, um payload JSON, um POST.
Estrutura do Payload
iOSAndroidCada POST envia um corpo JSON com esta forma:
{
"identifier": "04:A2:7F:1B:5E:80:00",
"date": "2026-05-12T14:23:01Z",
"content": "Filament Spool #1234",
"tagType": "openPrintTag",
"structured": {
"material": "PLA",
"color": "#FF6F4C",
"manufacturer": "Prusament",
"uuid": "5e8a-7c1d-4f90"
}
}Os campos tagType e structured aparecem apenas para formatos especiais como o OpenPrintTag; todas as outras leituras enviam apenas os três primeiros campos. A referência para programadores tem a descrição completa campo a campo, autenticação, curl e servidores de exemplo prontos a executar.
Servidor de Referência no GitHub
iOSAndroidA forma mais rápida de ver o ciclo completo de ponta a ponta: Servidor Web no GitHub. Um servidor de exemplo mínimo que aceita os payloads de webhook da NFC.cool, regista-os e mostra a estrutura ao vivo. Clone, execute, aponte o seu iPhone para ele e veja as leituras a chegar.
Detalhes Técnicos
Transporte
- HTTPS recomendado; HTTP permitido em desenvolvimento
- POST com `Content-Type: application/json`
- Autenticação HTTP Basic opcional (nome de utilizador + palavra-passe)
- Credenciais guardadas encriptadas no Keychain do iOS
Payload
- `identifier` - UID da tag ou código lido
- `date` - data e hora em ISO 8601
- `content` - payload descodificado (string de URL, texto, etc.)
- `tagType` - presente em tags estruturadas (ex.: `openPrintTag`)
- `structured` - JSON aninhado para tipos de tags estruturadas
Fontes
- Leituras NFC (leituras NDEF)
- Leituras QR
- Leituras de códigos de barras
- Cada fonte ativável de forma independente
Gratuito vs Platinum
| Gratuito | Platinum | |
|---|---|---|
| Webhook NFC e QR | ✗ | ✓ |
| Sintetizador de Voz | ✗ | ✓ |
| Atalhos | ✗ | ✓ |
| Sincronização iCloud | ✓ | ✓ |
Perguntas Frequentes
Isto funciona no Android?
Sim - os webhooks estão disponíveis nas versões iOS e Android da NFC.cool Tools. A estrutura do payload JSON é a mesma em todas as plataformas. (Os outros quatro gatilhos do iOS - Atalho automático, voz, áudio, abertura de ligações - são apenas para iOS.)
Quantos URLs posso configurar?
Um URL atualmente. O mesmo URL recebe todos os eventos de leitura, distinguidos pelos interruptores de fonte ativados e pelo tipo de payload.
Que autenticação é suportada?
Autenticação HTTP Basic - nome de utilizador + palavra-passe, guardados encriptados no Keychain do iOS. Tokens Bearer, cabeçalhos personalizados e assinatura HMAC não são atualmente suportados.
O que acontece se o meu servidor estiver offline?
O POST falha e o evento fica registado no dispositivo. Hoje não existe fila de repetição automática; se o seu servidor puder ser instável, conceba o seu handler para ser idempotente na repetição e volte a disparar a partir do histórico de leituras.
Existe um limite de tamanho do payload?
Nenhum limite rígido imposto pela NFC.cool. Os próprios payloads das tags estão limitados pelo padrão NFC (alguns KB para tags NDEF típicas).
Onde posso vê-lo a funcionar de verdade?
Clone o Servidor Web no GitHub, execute-o localmente, aponte a app para ele e verá cada leitura a chegar em tempo real.
Pronto para digitalizar?