Un marchand peut proposer, dans son parcours d'achat, un code QR propre à chaque article ou le System ID de l'acheteur en texte. L'acheteur le confirme sur qevik.com.
Déclarer
Vous déclarez votre domaine, votre adresse de retour et vos clés publiques. Aucun compte n'est nécessaire.
Prouver le domaine
Vous publiez un fichier de vérification, et Qevik vous remet un client de production et un client de test.
Intégrer
Votre serveur appelle l'API, l'acheteur confirme, et vous recevez le code QR ou le System ID de chaque article.
Remplissez le formulaire de déclaration et acceptez les conditions de l'API marchands.
Publiez le fichier https://votre-domaine/.well-known/qevik-verification.txt : la valeur reçue seule sur une ligne, puis une ligne qevik-key= par clé.
Lancez la vérification dans les 72 heures. La valeur n'est affichée qu'une fois.
Conservez vos deux identifiants : mrc_… pour la production et mrc_test_… pour le test. Ces identifiants ne fonctionnent pas sur l'API plateformes.
La déclaration porte tout le jeu de clés : ajouter ou retirer une clé demande une nouvelle déclaration. Les codes à activer se demandent dans le même formulaire et s'ouvrent après la vérification du domaine, parfois avec un court report si beaucoup de marchands s'inscrivent le même jour. Gardez le fichier de vérification publié : Qevik le relit régulièrement, et les codes à activer se retirent s'il ne se lit plus.
Authentification de serveur à serveur par private_key_jwt (ES256) : vous déclarez vos clés publiques, Qevik ne stocke aucun secret.
Chaque appel de serveur à serveur est signé par une assertion JWT : algorithme ES256 seul, kid égal à l'empreinte d'une clé active de cet environnement, iss et sub égaux à votre client, aud égal à l'adresse exacte appelée, exp à 300 secondes au plus, jti unique.
// 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"
}Choisissez le parcours selon votre processus d'achat. Tous partagent la même authentification. Une demande porte 10 articles au plus.
Votre serveur dépose la demande, l'acheteur est redirigé vers qevik.com, se connecte et confirme, puis revient sur votre adresse de retour avec un code à échanger.
| POST | /api/v1/public/merchant/oauth/par | Déposer la demande (PKCE S256 obligatoire) |
| GET | /api/v1/public/merchant/oauth/authorize | Rediriger le navigateur de l'acheteur |
| POST | /api/v1/public/merchant/oauth/token | Échanger le code contre les articles |
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"]
}]'Réponse de l'échange, une entrée par article demandé. qrPayload n'est présent que si la forme QR a été choisie, systemId que si le texte a été choisi et accepté par l'acheteur.
{
"token_type": "qevik-merchant-items",
"items": [
{
"lineRef": "o-123/1",
"qrPayload": "HTTPS://QEVIK.COM/F/7K2M9X4P0Q.ABCDEFGHJKMNPQRSTVWXYZ0123",
"systemId": "4821-BK7M"
}
]
}L'acheteur saisit son System ID chez vous. Qevik lui envoie un code à six chiffres, qu'il saisit chez vous, et votre serveur reçoit les articles en le confirmant. La réponse à la demande est la même pour tout System ID.
| POST | /api/v1/public/merchant/codes | Demander l'envoi du code |
| POST | /api/v1/public/merchant/codes/confirm | Confirmer le code et recevoir les articles |
Vous commandez des lots de codes liés à personne, vous les imprimez sur vos supports, et l'acheteur active le sien depuis son compte après l'avoir scanné. Ce parcours ne transmet jamais de System ID. Plafonds de départ : 1 000 codes non activés, 10 000 codes émis au total. Au-delà, la commande répond outstanding_limit.
| POST | /api/v1/public/merchant/blank-codes/batches | Commander un lot |
| POST | /api/v1/public/merchant/blank-codes/batches/read | Relire un lot (5 fois au plus, pendant 7 jours) |
| POST | /api/v1/public/merchant/blank-codes/sold | Marquer des codes comme vendus |
| POST | /api/v1/public/merchant/blank-codes/revoke | Retirer un lot |
| POST | /api/v1/public/merchant/blank-codes/stats | Lire les chiffres d'un lot ou d'un mois |
Le client mrc_test_… utilise ses propres clés et n'atteint que les comptes marqués comme comptes de test par Qevik. Ses articles ne sont jamais décomptés et restent introuvables publiquement. Le System ID remis est un alias fictif commençant par UTST, jamais un identifiant réel.