Para quem constrói

Onde pode integrar a NFC.cool

Um webhook é apenas um POST JSON para um URL que você controla - por isso, tudo o que fala HTTP é jogo limpo.

Padrões comuns de fluxo de trabalho

• Inventário + registo de auditoria. Toque numa tag colocada num artigo e a NFC.cool faz POST para uma folha de cálculo ou sistema de armazém; surge uma linha com o carimbo de data/hora, o identificador da tag e o payload.

• Captura de leads em eventos. Toque numa tag no painel do seu stand e o seu CRM dispara automaticamente um email de seguimento.

• Acionadores de casa inteligente. Toque numa tag na porta de entrada para marcar “Estou em casa” - o Home Assistant / Homey / Hubitat capta-o via webhook.

• Rastreio de ativos. O pessoal de manutenção toca em tags nos equipamentos para registar inspeções; o backend constrói o registo de conformidade.

• Check-ins em conferências. Toque no crachá NFC de um participante; o webhook atualiza a sua plataforma de eventos em tempo real.

Webhooks

Ative em separador Mais → Webhook dentro da app: introduza um URL HTTPS, opcionalmente um nome de utilizador/palavra-passe para HTTP Basic Auth e, depois, ative “leituras NFC” e “leituras de QR e códigos de barras” de forma independente. Disponível em iOS e Android.

A app dispara um único POST por leitura para o URL que configurou. Não há uma fila de repetição em separado: se o seu endpoint não estiver acessível ou devolver uma resposta que não seja 2xx, o POST da leitura falha. Procure devolver 204 No Content em caso de sucesso; qualquer 2xx é tratado como aceite.

Esta página é a referência técnica. Para a visão geral da funcionalidade - os outros quatro ganchos de automação do iOS, preços e perguntas frequentes - consulte a página da funcionalidade Webhooks e Automação.

Payload do webhook

Content-type application/json, o corpo é JSON formatado:

{
  "identifier" : "04:A2:7F:1B:5E:80:00",
  "date" : "2026-05-12T14:23:01Z",
  "content" : "https://example.com/check-in/abc123"
}

As tags estruturadas (atualmente OpenPrintTag) acrescentam mais dois campos:

{
  "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"
  }
}

Referência dos campos:

• identifier - Para leituras NFC, o UID de hardware da tag em hexadecimal maiúsculo separado por dois pontos (por exemplo, 04:A2:7F:1B:5E:80:00). Estável por tag, por isso pode usá-lo para desduplicação. Para leituras de QR e códigos de barras, é um UUID novo por leitura - não é um ID de código estável. Em modos de compatibilidade NFC mais antigos do iOS que não expõem o UID, o valor é a cadeia literal NoIdentifierInCompatibilityMode.

• date - ISO 8601, quando a leitura ocorreu no dispositivo.

• content - Conteúdo descodificado. Para NFC, o valor do registo NDEF (URI ou texto); para QR/código de barras, a cadeia descodificada em bruto.

• tagType - Omitido em leituras simples. Definido como "openPrintTag" para leituras de OpenPrintTag.

• structured - Omitido em leituras simples. Payload estruturado interpretado quando tagType está presente.

Autenticação

Os webhooks suportam apenas HTTP Basic Auth. Em separador Mais → Webhook pode, opcionalmente, guardar um nome de utilizador e palavra-passe no Keychain do iOS. A app responde então aos desafios HTTP padrão 401 / WWW-Authenticate: Basic do seu servidor com essas credenciais.

Isso significa que é o seu endpoint que controla se a autenticação é necessária. Se não precisar de autenticação, deixe o nome de utilizador e a palavra-passe em branco na app e dispense o desafio no servidor. Se precisar, devolva um 401 com WWW-Authenticate: Basic realm="…" no primeiro POST - o dispositivo volta a tentar com Authorization: Basic … transportando as credenciais guardadas. Tudo viaja por TLS; os servidores da NFC.cool nunca veem as suas credenciais.

Hoje não há suporte para token Bearer, chave de API ou assinatura HMAC. Se precisar disso, termine-os num proxy inverso (Cloudflare Worker, nginx, etc.) que traduza Basic para o seu esquema.

Exemplos de recetores

Precisa do ciclo completo, de ponta a ponta? Clone o servidor de webhook de referência no GitHub - regista cada payload ao vivo. Os excertos abaixo são recetores mínimos para a sua própria stack.

cURL - teste rápido de fumo

curl -X POST https://your-server.example/webhook \
  -u 'nfc-cool:your-password' \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"04:A2:7F:1B:5E:80:00","date":"2026-05-12T14:00:00Z","content":"hello"}'

Node.js - recetor com Express

import express from "express";
import basicAuth from "express-basic-auth";

const app = express();
app.use(express.json());

app.post(
  "/webhook",
  basicAuth({
    users: { "nfc-cool": process.env.WEBHOOK_PASSWORD },
    challenge: true, // indica à NFC.cool que volte a tentar com credenciais
  }),
  (req, res) => {
    const { identifier, date, content, tagType } = req.body;
    console.log(`scan ${tagType ?? "plain"} ${content} id=${identifier} at ${date}`);
    res.status(204).end();
  }
);

app.listen(3000);

Python - recetor com FastAPI

import os
import secrets
from fastapi import FastAPI, Depends, HTTPException, Request, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials

app = FastAPI()
security = HTTPBasic()

def check(creds: HTTPBasicCredentials = Depends(security)):
    ok_user = secrets.compare_digest(creds.username, "nfc-cool")
    ok_pass = secrets.compare_digest(creds.password, os.environ["WEBHOOK_PASSWORD"])
    if not (ok_user and ok_pass):
        raise HTTPException(
            status.HTTP_401_UNAUTHORIZED,
            headers={"WWW-Authenticate": 'Basic realm="nfc-cool"'},
        )

@app.post("/webhook")
async def webhook(request: Request, _: None = Depends(check)):
    body = await request.json()
    print(f"scan: {body['content']} id={body['identifier']}")
    return {"status": "ok"}

App Intents e Atalhos

A NFC.cool Tools no iOS inclui um conjunto de App Intents que pode ligar à app Atalhos, a automações, a modos de concentração ou ao Apple Intelligence.

As variantes dedicadas do iOS 18 (NFC Scan, QR Scan, Document Scan, Object Scan, Room Scan) aparecem diretamente no Spotlight / no seletor do botão de ação.

Esquemas de URL

Para deep-linking a partir de outras apps iOS, widgets ou atalhos do ecrã principal, a NFC.cool Tools regista estes URLs:

nfcforiphone://scan-nfc
nfcforiphone://scan-code
nfcforiphone://scan-document
nfcforiphone://scan-object       (iOS 17 ou posterior)
nfcforiphone://scan-room         (iOS 17 ou posterior)

Abrir qualquer um destes leva-o diretamente ao leitor correspondente. Os esquemas nfc:// e geo:// também estão registados para entregar ligações externas de tags/coordenadas.

Recursos legíveis por máquina

Feeds detetáveis para ferramentas, motores de busca e agentes de IA:

A construir algo sobre a NFC.cool? Ou descobriu um parceiro de integração que devia estar nesta página? Deixe-nos uma nota.