YUNIT SL
YUNIT SL
Senior Hands on Delivery
English Deutsch Català Русский

Merchant integration guide

Integració per a comerços

Vista tècnica d'integració per a comerços que fan servir YUNIT com a proveïdor d'identitat, gestor de consentiment i vault de PII per a cessions puntuals de dades del client.

Obrir el portal Visió del consumidor

Prerequisits d'onboarding del comerc

  • Cada comerc opera dins del seu propi tenant i rep un client OAuth per al seu backend o per al middleware del POS.
  • El comerç ha de registrar els redirect URIs, els endpoints de callback i els contactes operatius abans d'entrar en proves o produccio.
  • Els scopes disponibles es defineixen prèviament per política, de manera que el comerci no pugui demanar camps fora del catàleg autoritzat.

Cataleg de scopes i model de peticio

Una petició de consentiment inclou el comerci, el terminal o canal d'origen, el propòsit de negoci i la llista exacta de camps sollicitats. El model està pensat perquè el client vegi una petició comprensible i concreta.

Els camps es tracten com a scopes predefinits, per exemple `name`, `billing_address` i `tax_number`, i la resposta només conté els valors aprovats dins d'aquella petició.

Cicle de vida de la peticio de consentiment

  • El POS crea la petició, mostra o associa el context de l'operacio i espera que es resolgui l'estat de consentiment.
  • L'escaneig del QR de la Wallet resol el token del consumidor i YUNIT inicia el pas d'autenticacio OTP i d'aprovacio.
  • Després de l'acceptacio, el comerci rep un authorization code temporal que intercanvia per un access token per recuperar les dades aprovades.
  • Si el client denega, si el temps expira o si el token ja no és vàlid, la petició acaba sense dades i el POS ha de començar una nova petició.

Callback, polling i comportament de caducitat

Per fiabilitat del POS, la integracio pot combinar un callback del servidor amb polling d'estat mentre la caixa espera una resolucio. Això redueix la dependència d'un sol mecanisme de lliurament.

Les peticions tenen una caducitat curta, els codis d'autoritzacio també caduquen ràpidament i els tokens d'accés han de tenir una vida suficient per completar només la lectura immediata de dades.

Expectatives de seguretat i auditoria

  • El backend del comerci ha de registrar la petició, el resultat i el propòsit de negoci sense persistir més dades personals de les necessàries.
  • Els redirect URIs i les credencials OAuth s'han de gestionar per entorn, amb rotacio i controls de suport operatiu.
  • Qualsevol camp retornat per YUNIT s'ha de tractar com a dada acotada a aquella transaccio i no com un consentiment permanent per a futures consultes.
  • Els equips d'operacions han de poder demostrar per què es va demanar cada scope i com es van resoldre les peticions expirades o denegades.

Sequencia d'integracio del comerc

  1. Step 1 Provisionar el tenant del comerc, registrar els redirect URI i emetre credencials OAuth per al backend del POS o la middleware.
  2. Step 2 Crear una peticio de consentiment amb els scopes necessaris, la referencia de proposit i el context de la sessio del POS.
  3. Step 3 Escanejar el QR de la Wallet del consumidor perquè YUNIT resolgui el token i iniciï el flux d'aprovacio amb OTP.
  4. Step 4 Rebre el codi d'autoritzacio de vida curta després de l'aprovacio i intercanviar-lo per un access token.
  5. Step 5 Llegir només les dades aprovades, completar la transaccio del comerc i conservar la traça d'auditoria de la peticio.

Exemple de peticio de consentiment

curl -H "Authorization: Bearer POS_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST https://api.yunit.tech/oauth/consent-requests \
  -d '{
    "merchant_id": "restaurant-abc",
    "terminal_id": "pos-03",
    "purpose": "Invoice #12345",
    "scopes": ["name", "billing_address", "tax_number"],
    "callback_url": "https://merchant.example.com/yunit/callback"
  }'

Intercanvi del codi d'autoritzacio

curl -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -X POST https://api.yunit.tech/oauth/token \
  -d '{
    "grant_type": "authorization_code",
    "code": "auth_req_9f8d",
    "redirect_uri": "https://merchant.example.com/yunit/callback"
  }'

Exemple de lectura de dades aprovades

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  -X GET "https://api.yunit.tech/oauth/consent-requests/auth_req_9f8d/data"

Notes operatives

  • Combineu callback i polling perquè el POS continuï sent fiable si un dels camins de lliurament es retarda.
  • Cada aprovacio és un consentiment d'un sol ús. Una nova peticio futura necessita una nova aprovacio.
  • Els codis d'autoritzacio i els access tokens han de tenir una vida curta i quedar limitats a la peticio aprovada.
  • Els logs del comerc han de guardar request IDs, scopes, proposit i resultat sense persistir PII innecessària.