u

2026-09-29 11:31:35 +02:00
parent cf4af1480b
commit 0e64233418
5 changed files with 253 additions and 4 deletions
--- a/src/v1/routes/client.js
+++ b/src/v1/routes/client.js
@@ -56,7 +56,85 @@ export function buildClientStep2(authCode, config) {
 }

 /**
- * Handles GET /v1/client
+ * @openapi
+ * /v1/client:
+ *   get:
+ *     tags: [POS]
+ *     summary: POS discovery and pairing
+ *     description: |
+ *       Special API for POS bind and sync.
+ *       - Step 1 (Discovery): `authCode` length 1–4. Returns certificate fingerprints, serial number, and mandantId.
+ *       - Step 2 (Pairing): `authCode` length 6 (pairingpin from posterminal). Verifies the pairingpin, sets token, paired_at, and clientserial, revokes the pairingpin, and returns device credentials and company metadata.
+ *     security: []
+ *     x-markdown: pos/client.md
+ *     parameters:
+ *       - in: query
+ *         name: authCode
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Discovery code (1-4 digits) or pairing PIN (6 digits)
+ *         example: "678677"
+ *       - in: query
+ *         name: name
+ *         required: false
+ *         schema:
+ *           type: string
+ *         description: Client device name or serial identifier (default 'JTL-POS')
+ *         example: "Kasse 1"
+ *     responses:
+ *       200:
+ *         description: Discovery or pairing successful
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 authCode:
+ *                   type: string
+ *                   nullable: true
+ *                   example: "678677"
+ *                 authToken:
+ *                   type: string
+ *                   nullable: true
+ *                   example: "df40ad2067954646abb0499548a52241"
+ *                 certificateFingerprint:
+ *                   type: string
+ *                   example: "30DD111E8048B57E6A4FB75AD7E63F7E657F1262"
+ *                 certificateSerialNumber:
+ *                   type: string
+ *                   example: "1BB1BD7844451E3AC6"
+ *                 mandantId:
+ *                   type: string
+ *                   example: "1"
+ *                 mandantName:
+ *                   type: string
+ *                   nullable: true
+ *                   example: "eB-Standard"
+ *                 mandantDatabase:
+ *                   type: string
+ *                   nullable: true
+ *                   example: "eazybusiness"
+ *                 serverFingerprint:
+ *                   type: string
+ *                   nullable: true
+ *                   example: "30-DD-11-1E-80-48-B5-7E-6A-4F-B7-5A-D7-E6-3F-7E-65-7F-12-62"
+ *                 name:
+ *                   type: string
+ *                   nullable: true
+ *                 serverTimestamp:
+ *                   type: string
+ *                   example: "2026-09-29 11:00:00"
+ *       400:
+ *         description: Invalid or incorrect authentication code
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 Message:
+ *                   type: string
+ *                   example: "Der Authentifizierungscode ist falsch."
 * @param {import('express').Request} req
 * @param {import('express').Response} res
 */