API

Writer- und Query-API fuer eigene Tools (ESP32, USB-Reader, Scripts). Antworten sind JSON.

Technische Referenz als OpenAPI-Datei: Swagger UI · openapi.yaml

Authentifizierung

Jeder Writer-Call braucht user + key. Der Key wird auf /user/collectibles → Writer API erzeugt und ist nur 1 Stunde aktiv — danach ist er automatisch deaktiviert. Falsches Paar oder abgelaufener Key → 401.

GET /api/mchips

Deine Collectibles auflisten — zur Auswahl vor dem Schreiben.

https://mtag.cc/api/mchips?user=USER&key=YOUR_API_KEY

GET /api/chip

UID eintragen, Status abfragen und optional einem Collectible zuordnen (aktivieren).

https://mtag.cc/api/chip?user=USER&key=YOUR_API_KEY&uid=04A1B2C3D4E5F6&mchip=phoenix-coin-v1

status	Bedeutung
`inserted`	UID war unbekannt — wurde unter deinem Account registriert
`registered`	bekannt, aber noch keinem Collectible zugeordnet
`activated`	einem Collectible zugeordnet, Serial vergeben
`claimed`	wurde bereits von einem User geclaimt
`activated_conflict`	gehoert schon zu einem anderen Collectible — nichts geaendert

GET /api/writer_setup

Einmaliges Geraete-Pairing — liefert dieselben Daten wie der Writer-QR (base, user, key, key_until) und verbrennt den Code beim Einloesen. Code unter Writer API → Setup-Code generieren erzeugen (aktiviert die API gleich mit), 5 Minuten gueltig.

https://mtag.cc/api/writer_setup?code=XXXX-XXXX

HTTP	error	Ursache
200	—	Pairing-Daten; Code ist danach verbraucht
400	`invalid code format`	kein 8-stelliger Code
404	`invalid or expired code`	unbekannt, abgelaufen (>5 Min) oder schon eingeloest
410	`writer api expired`	API-Key lief zwischen Generieren und Einloesen ab

Fehler

HTTP	error	Ursache
401	`api disabled / invalid credentials`	Key fehlt, abgelaufen oder gehoert nicht zu `user`
400	`invalid uid`	UID-Format ungueltig
400	`unknown mchip`	kein Collectible mit dieser ID/Slug auf deinem Account
409	`foreign`	UID gehoert einem anderen Creator — wird nicht veraendert

URLs auf dem Tag

`/{username}?chip={UID}`	Standard — oeffnet dein Profil mit Claim-Sheet
`/t/{public_id}`	direkte Chip-/Claim-Seite (opake ID, nicht die physische UID)

Tools & Setup

Fertige Writer fuer die beiden API-Endpunkte — herunterladen, Zugangsdaten eintragen, loslegen.

WebNFC-Writer Direkt im Browser (Android Chrome)

Oeffnen →

Kein Download noetig: Unter Collectibles → Writer API Collectible auswaehlen, mit oder ohne Lock-Bit (Read-Only-Schreibschutz) einstellen und Tags direkt ans Android-Handy halten. Nutzt die laufende Login-Session.

write_chip.py USB-Reader (ACR122U u.a.)

Download .py

Liest die UID vom aufgelegten Tag, ruft /api/chip und schreibt die zurueckgegebene URL als NDEF-Record — in einer Schleife, Tag fuer Tag. Optional mit --lock fuer permanenten Schreibschutz (Lock-Bit).

pip install nfcpy requests
# ACR122U unter Windows: libusb-Treiber einmalig via Zadig installieren

python write_chip.py --user USER --key YOUR_API_KEY \
    --mchip phoenix-coin-v1 --base https://mtag.cc [--lock]

esp32_writer.ino ESP32 + PN532

Download .ino

Arduino-Sketch mit eigenem Web-Interface: Erststart spannt WLAN MTAG-SETUP auf → unter 192.168.4.1 WLAN-Daten + Setup-Code eintragen → Geraet paired sich einmalig per /api/writer_setup und speichert alles. Danach laeuft auf der LAN-IP eine Status-Seite mit Design-Auswahl, waehlbarem Lock-Bit (mit/ohne Schreibschutz) und Schreib-Log. Kein Editieren des Sketches noetig.

mchip-preview.ini PHP-Limits (Docker/Dev)

Download .ini

Empfohlene PHP-Einstellungen, damit 3MF-Uploads (25 MB) und das serverseitige Rendern nicht an Limits scheitern — fuer eigene Docker-/Dev-Setups, nicht fuer den Writer.

App-Setup per QR

Unter Writer API wird bei aktivem Key ein QR-Code gezeigt. Eine Writer-App scannt ihn und bekommt damit komplette Zugangsdaten — kein Abtippen. Der QR ist nur gueltig, solange der Key laeuft.

Der QR-Code enthaelt dieses JSON:

{
  "t":    "mtag-writer",
  "v":    1,
  "base": "https://mtag.cc",
  "user": "USER",
  "key":  "YOUR_API_KEY"
}

Feld	Beschreibung
`t`	Payload-Typ — immer `"mtag-writer"`
`v`	Format-Version (aktuell `1`)
`base`	Basis-URL der Instanz — alle API-Calls gehen dorthin
`user`	Username des Accounts
`key`	API-Key — gueltig bis `key_until` (1h ab Aktivierung)
`key_until`	Unix-Timestamp des Key-Ablaufs (optional, nur bei `writer_setup`)

App-Flow: QR scannen → GET {base}/api/mchips?user=…&key=… zur Chip-Auswahl → pro Tag GET {base}/api/chip?…&uid=UID&mchip=SLUG → zurueckgegebene url als NDEF auf den Tag schreiben.