Geliştirenler için

NFC.cool’u nereye bağlayabilirsin

Webhook, denetimindeki bir adrese giden JSON POST isteğinden ibaret; yani HTTP konuşan her şey oyunun içinde.

Sık kullanılan akış kalıpları

• Stok ve denetim kaydı. Ürünün üstündeki tag’i okut, NFC.cool bir tabloya ya da depo sistemine POST atsın; zaman damgası, tag kimliği ve içerikle birlikte satır düşsün.

• Etkinlikte müşteri adayı toplama. Stant afişindeki tag’i okut, CRM’in takip e-postasını kendiliğinden göndersin.

• Akıllı ev tetikleyicileri. Kapıdaki tag’i okutup “evdeyim” işaretle; Home Assistant, Homey ya da Hubitat bunu webhook üzerinden alsın.

• Varlık takibi. Bakım ekibi ekipmandaki tag’leri okutup denetimleri kaydetsin; uyum kaydını arka uç oluştursun.

• Konferans girişleri. Katılımcının NFC yakasını okut, webhook etkinlik platformunu anlık güncellesin.

Webhook’lar

Uygulama içinde Daha fazla sekmesi → Webhook yolundan aç: tek bir HTTPS adresi gir, istersen HTTP Basic kimlik doğrulaması için kullanıcı adı ve parola ekle, sonra “NFC taramaları” ile “QR ve barkod taramaları” anahtarlarını ayrı ayrı aç. iOS ve Android’de var.

Uygulama, ayarladığın adrese tarama başına tek bir POST gönderir. Ayrı bir yeniden deneme kuyruğu yok: uç noktana ulaşılamıyorsa ya da 2xx dışında yanıt dönüyorsa tarama POST’u başarısız olur. Başarıda 204 No Content dönmeyi hedefle; herhangi bir 2xx kabul sayılır.

Bu sayfa teknik başvuru kaynağı. Özelliğin genel tanıtımı için (diğer dört iOS otomasyon kancası, fiyatlandırma ve sık sorulanlar) Webhook ve Otomasyon özellik sayfasına bak.

Webhook yükü

İçerik türü application/json, gövde biçimlendirilmiş JSON:

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

Yapılandırılmış tag’ler (şu anda OpenPrintTag) iki alan daha ekler:

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

Alan açıklamaları:

• identifier - NFC taramalarında tag’in donanım UID’si, iki nokta ile ayrılmış büyük harf onaltılık olarak (örneğin 04:A2:7F:1B:5E:80:00). Tag başına sabittir, yani yinelenenleri ayıklamak için kullanabilirsin. QR ve barkod taramalarında ise her tarama için taze bir UUID gelir; kodun sabit kimliği değildir. UID’yi açığa çıkarmayan eski iOS uyumluluk modlarında değer düz metin olarak NoIdentifierInCompatibilityMode olur.

• date - ISO 8601 biçiminde, taramanın cihazda gerçekleştiği an.

• content - Çözülmüş içerik. NFC’de NDEF kaydının değeri (URI ya da metin); QR ve barkodda ham çözülmüş dize.

• tagType - Düz taramalarda gönderilmez. OpenPrintTag taramalarında "openPrintTag" olur.

• structured - Düz taramalarda gönderilmez. tagType varsa çözümlenmiş yapılandırılmış yük gelir.

Kimlik doğrulama

Webhook’lar yalnızca HTTP Basic kimlik doğrulamasını destekler. Daha fazla sekmesi → Webhook yolundan istersen kullanıcı adı ve parolayı iOS Anahtar Zinciri’nde saklarsın. Uygulama da sunucundan gelen standart 401 / WWW-Authenticate: Basic isteklerine bu bilgilerle yanıt verir.

Yani kimlik doğrulamanın gerekip gerekmediğine uç noktan karar verir. Gerekmiyorsa uygulamada kullanıcı adı ve parolayı boş bırak, sunucuda da istekte bulunma. Gerekiyorsa ilk POST’ta WWW-Authenticate: Basic realm="…" başlığıyla 401 dön; cihaz saklanan bilgileri taşıyan Authorization: Basic … başlığıyla yeniden dener. Her şey TLS üzerinden gider ve NFC.cool sunucuları kimlik bilgilerini hiç görmez.

Bugün Bearer token, API anahtarı ya da HMAC imza desteği yok. Bunlara ihtiyacın varsa Basic’i kendi şemana çeviren bir ters vekil sunucuda (Cloudflare Worker, nginx ve benzeri) sonlandır.

Örnek alıcılar

Döngünün tamamını uçtan uca mı görmek istiyorsun? GitHub’daki örnek webhook sunucusunu klonla, her yükü canlı kaydeder. Aşağıdaki parçalar ise kendi sistemin için en yalın alıcılar.

cURL - hızlı deneme

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 - Express alıcısı

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 - FastAPI alıcısı

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 ve Kısayollar

iOS’taki NFC.cool Tools, Kısayollar uygulamasına, otomasyonlara, odak modlarına ya da Apple Intelligence’a bağlayabileceğin birkaç App Intent ile geliyor.

iOS 18’e özel sürümler (NFC Scan, QR Scan, Document Scan, Object Scan, Room Scan) doğrudan Spotlight’ta ve aksiyon düğmesi seçicisinde görünür.

URL şemaları

Diğer iOS uygulamalarından, widget’lardan ya da ana ekran kısayollarından derin bağlantı vermek için NFC.cool Tools şu adresleri kaydeder:

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

Bunlardan herhangi birini açmak doğrudan ilgili tarayıcıya götürür. Dışarıdan gelen tag ve konum bağlantılarını devralmak için nfc:// ve geo:// şemaları da kayıtlıdır.

Makine tarafından okunabilir kaynaklar

Araçlar, arama motorları ve yapay zeka ajanları için keşfedilebilir akışlar:

NFC.cool üzerine bir şey mi kuruyorsun? Ya da bu sayfada olması gereken bir entegrasyon ortağı mı gördün? Bize yaz.