Ein Händler kann in seinem Bestellablauf einen QR-Code nur für den jeweiligen Artikel oder die System ID des Käufers als Text anbieten. Der Käufer bestätigt dies auf qevik.com.
Anmelden
Sie melden Ihre Domain, Ihre Rücksprungadresse und Ihre öffentlichen Schlüssel an. Ein Konto ist nicht nötig.
Domain nachweisen
Sie veröffentlichen eine Prüfdatei, und Qevik gibt Ihnen einen Produktions- und einen Test-Client.
Einbinden
Ihr Server ruft die Schnittstelle auf, der Käufer bestätigt, und Sie erhalten den QR-Code oder die System ID jedes Artikels.
Füllen Sie das Anmeldeformular aus und nehmen Sie die Bedingungen der Händlerschnittstelle an.
Veröffentlichen Sie die Datei https://ihre-domain/.well-known/qevik-verification.txt: den erhaltenen Wert allein in einer Zeile, danach je Schlüssel eine Zeile qevik-key=.
Starten Sie die Prüfung innerhalb von 72 Stunden. Der Wert wird nur einmal angezeigt.
Bewahren Sie Ihre beiden Kennungen auf: mrc_… für die Produktion und mrc_test_… für Tests. Diese Kennungen gelten nicht für die Plattform-Schnittstelle.
Die Anmeldung umfasst alle Schlüssel: Einen Schlüssel hinzuzufügen oder zu entfernen erfordert eine neue Anmeldung. Codes zum Aktivieren werden im selben Formular angefragt und nach der Domainprüfung geöffnet, gelegentlich mit kurzer Verzögerung, wenn sich viele Händler am selben Tag anmelden. Lassen Sie die Prüfdatei veröffentlicht: Qevik liest sie regelmäßig, und die Aktivierungscodes werden entzogen, wenn sie nicht mehr lesbar ist.
Authentifizierung von Server zu Server mit private_key_jwt (ES256): Sie melden Ihre öffentlichen Schlüssel an, Qevik speichert kein Geheimnis.
Jeder Aufruf von Server zu Server wird mit einer JWT-Assertion signiert: nur Algorithmus ES256, kid gleich dem Fingerabdruck eines aktiven Schlüssels dieser Umgebung, iss und sub gleich Ihrem Client, aud gleich der exakt aufgerufenen Adresse, exp höchstens 300 Sekunden, jti einmalig.
// Header
{ "alg": "ES256", "kid": "<RFC 7638 thumbprint of an active key>" }
// Claims
{
"iss": "mrc_YOUR_CLIENT_ID",
"sub": "mrc_YOUR_CLIENT_ID",
"aud": "https://qevik.com/api/v1/public/merchant/oauth/par",
"exp": 1893456000,
"jti": "a-unique-value"
}Wählen Sie den Ablauf passend zu Ihrem Bestellprozess. Alle nutzen dieselbe Authentifizierung. Eine Anfrage umfasst höchstens 10 Artikel.
Ihr Server hinterlegt die Anfrage, der Käufer wird zu qevik.com weitergeleitet, meldet sich an und bestätigt, und kehrt dann mit einem einlösbaren Code zu Ihrer Rücksprungadresse zurück.
| POST | /api/v1/public/merchant/oauth/par | Anfrage hinterlegen (PKCE S256 erforderlich) |
| GET | /api/v1/public/merchant/oauth/authorize | Browser des Käufers weiterleiten |
| POST | /api/v1/public/merchant/oauth/token | Code gegen die Artikel einlösen |
curl -X POST "https://qevik.com/api/v1/public/merchant/oauth/par" \
-d response_type=code \
-d client_id=mrc_YOUR_CLIENT_ID \
-d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
-d client_assertion=$SIGNED_JWT \
-d redirect_uri=https://shop.qevik.com/return \
-d state=$STATE \
-d code_challenge=$PKCE_CHALLENGE \
-d code_challenge_method=S256 \
--data-urlencode 'authorization_details=[{
"type": "qevik_item",
"lineRef": "o-123/1",
"label": "Backpack",
"sellerName": "Qevik Shop",
"allowedForms": ["QR", "TEXT"],
"chosenForms": ["QR"]
}]'Antwort auf die Einlösung, ein Eintrag je angefragtem Artikel. qrPayload ist nur vorhanden, wenn die Form QR gewählt wurde, systemId nur, wenn Text gewählt und vom Käufer angenommen wurde.
{
"token_type": "qevik-merchant-items",
"items": [
{
"lineRef": "o-123/1",
"qrPayload": "HTTPS://QEVIK.COM/F/7K2M9X4P0Q.ABCDEFGHJKMNPQRSTVWXYZ0123",
"systemId": "4821-BK7M"
}
]
}Der Käufer gibt seine System ID bei Ihnen ein. Qevik sendet ihm einen sechsstelligen Code, den er bei Ihnen eingibt, und Ihr Server erhält mit der Bestätigung die Artikel. Die Antwort auf die Anfrage ist für jede System ID gleich.
| POST | /api/v1/public/merchant/codes | Versand des Codes anfordern |
| POST | /api/v1/public/merchant/codes/confirm | Code bestätigen und Artikel erhalten |
Sie bestellen Code-Pakete ohne Personenbezug, drucken sie auf Ihre Träger, und der Käufer aktiviert seinen Code nach dem Scannen in seinem Konto. Dieser Ablauf überträgt nie eine System ID. Anfängliche Obergrenzen: 1.000 nicht aktivierte Codes, 10.000 ausgegebene Codes insgesamt. Darüber antwortet die Bestellung mit outstanding_limit.
| POST | /api/v1/public/merchant/blank-codes/batches | Paket bestellen |
| POST | /api/v1/public/merchant/blank-codes/batches/read | Paket erneut lesen (höchstens 5-mal, innerhalb von 7 Tagen) |
| POST | /api/v1/public/merchant/blank-codes/sold | Codes als verkauft markieren |
| POST | /api/v1/public/merchant/blank-codes/revoke | Paket zurückziehen |
| POST | /api/v1/public/merchant/blank-codes/stats | Zahlen eines Pakets oder Monats lesen |
Der Client mrc_test_… nutzt eigene Schlüssel und erreicht nur Konten, die Qevik als Testkonten markiert hat. Seine Artikel werden nie angerechnet und bleiben öffentlich unauffindbar. Die übergebene System ID ist ein fiktiver Alias, der mit UTST beginnt, nie eine echte Kennung.