Per chi costruisce

Dove si collega NFC.cool

Un webhook non è altro che un POST in JSON verso un indirizzo che controlli tu, quindi va bene qualsiasi cosa parli HTTP.

Gli scenari più diffusi

• Inventario e tracciabilità. Avvicini il telefono al tag di un oggetto, NFC.cool invia il POST a un foglio di calcolo o al gestionale di magazzino e compare una riga con data e ora, identificativo del tag e payload.

• Raccolta dei contatti agli eventi. Il visitatore avvicina il telefono al tag sul banner dello stand e il tuo CRM manda in automatico un’email di ricontatto.

• Comandi per la casa intelligente. Avvicini il telefono al tag sulla porta di casa per segnalare che sei rientrato e Home Assistant, Homey o Hubitat ricevono il webhook.

• Gestione dei beni aziendali. I manutentori avvicinano il telefono ai tag sui macchinari per registrare i controlli e il backend costruisce il registro per le verifiche di conformità.

• Accrediti ai convegni. Basta scansionare il badge NFC del partecipante e il webhook aggiorna in tempo reale la piattaforma dell’evento.

Webhook

La configurazione sta nell’app, in scheda Altro → Webhook: inserisci un indirizzo HTTPS e, se vuoi, un nome utente e una password per l’HTTP Basic Auth, poi attiva separatamente “scansioni NFC” e “scansioni QR e codici a barre”. Disponibile su iOS e Android.

L’app manda un solo POST per scansione all’indirizzo che hai configurato. Non c’è una coda di reinvio separata: se l’endpoint non risponde o restituisce un codice diverso da 2xx, il POST di quella scansione fallisce. In caso di successo conviene rispondere 204 No Content; qualsiasi 2xx viene considerato un’accettazione.

Questa pagina è la documentazione tecnica. Per una panoramica della funzione, con gli altri quattro agganci di automazione su iOS, i prezzi e le domande frequenti, vai alla pagina su webhook e automazioni.

Il payload del webhook

Content-type application/json, il corpo è un JSON formattato in modo leggibile:

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

I tag strutturati (al momento solo OpenPrintTag) aggiungono altri due campi:

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

Descrizione dei campi:

• identifier - Nelle scansioni NFC è l’UID hardware del tag, in esadecimale maiuscolo separato dai due punti (per esempio 04:A2:7F:1B:5E:80:00). Resta stabile per ogni tag, quindi si presta a scartare i duplicati. Nelle scansioni di codici QR e codici a barre è invece un UUID nuovo a ogni lettura, non un identificativo stabile del codice. Nelle vecchie modalità di compatibilità NFC di iOS, che non espongono l’UID, il valore è la stringa NoIdentifierInCompatibilityMode.

• date - In formato ISO 8601, indica quando è avvenuta la scansione sul dispositivo.

• content - Il contenuto decodificato: per l’NFC il valore del record NDEF (URI o testo), per i codici QR e a barre la stringa grezza appena letta.

• tagType - Assente nelle scansioni semplici. Vale "openPrintTag" quando si legge un OpenPrintTag.

• structured - Assente nelle scansioni semplici. Contiene il payload strutturato già interpretato quando è presente tagType.

Autenticazione

I webhook supportano soltanto l’HTTP Basic Auth. Da scheda Altro → Webhook puoi salvare un nome utente e una password nel portachiavi di iOS. A quel punto l’app risponde con quelle credenziali alle richieste standard 401 / WWW-Authenticate: Basic del tuo server.

È quindi il tuo endpoint a decidere se l’autenticazione serve o no. Se non ti serve, lascia vuoti nome utente e password nell’app e non richiedere nulla dal server. Se invece ti serve, al primo POST rispondi con un 401 e l’intestazione WWW-Authenticate: Basic realm="…": il dispositivo riprova con Authorization: Basic … e le credenziali salvate. Tutto viaggia su TLS e i server di NFC.cool non vedono mai le tue credenziali.

Al momento non sono supportati token Bearer, chiavi API o firme HMAC. Se ti servono, gestiscili su un reverse proxy (un Cloudflare Worker, nginx o simili) che converta il Basic Auth nello schema che usi tu.

Ricevitori di esempio

Vuoi vedere tutto il flusso dall’inizio alla fine? Clona il server webhook di riferimento su GitHub, che registra ogni payload in diretta. Qui sotto trovi invece dei ricevitori minimi da adattare alla tua infrastruttura.

cURL - prova al volo

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 - ricevitore con 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, // tells NFC.cool to retry with credentials
  }),
  (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 - ricevitore con 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 Comandi Rapidi

Su iOS, NFC.cool Tools mette a disposizione alcuni App Intents da collegare all’app Comandi Rapidi, alle automazioni, alle modalità di concentrazione o ad Apple Intelligence.

Le varianti dedicate di iOS 18 (NFC Scan, QR Scan, Document Scan, Object Scan, Room Scan) compaiono direttamente in Spotlight e nel selettore del tasto Azione.

Schemi URL

Per i collegamenti diretti da altre app iOS, dai widget o dalle scorciatoie sulla schermata Home, NFC.cool Tools registra questi indirizzi:

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

Aprendone uno si arriva subito allo scanner corrispondente. Sono registrati anche gli schemi nfc:// e geo://, che ricevono i link a tag e coordinate provenienti da altre app.

Risorse leggibili dalle macchine

Feed pensati per strumenti automatici, motori di ricerca e agenti di IA:

Stai costruendo qualcosa su NFC.cool? Oppure conosci un servizio che meriterebbe di stare in questa pagina? Scrivici due righe.