YUNIT SL
YUNIT SL
Senior Hands on Delivery
English Deutsch Català

Merchant integration guide

Integració GDPR per a comerços

Vista tècnica d'integració GDPR 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.

Tambe admet fluxos LQPD andorrans.

Obrir el portal Visió del consumidor

Prerequisits d'onboarding del comerç

  • Cada comerç 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 producció.
  • Els scopes disponibles es defineixen prèviament per política, de manera que el comerç no pugui demanar camps fora del catàleg autoritzat.

Catàleg de scopes i model de petició

Una petició de consentiment inclou el comerç, el terminal o canal d'origen, el propòsit de negoci i la llista exacta de camps sol·licitats. 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 petició de consentiment

  • El POS crea la petició, mostra o associa el context de l'operació 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'autenticació OTP i d'aprovació.
  • Després de l'acceptació, el comerç 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 integració pot combinar un callback del servidor amb polling d'estat mentre la caixa espera una resolució. Això redueix la dependència d'un sol mecanisme de lliurament.

Les peticions tenen una caducitat curta, els codis d'autorització 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 comerç 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 rotació i controls de suport operatiu.
  • Qualsevol camp retornat per YUNIT s'ha de tractar com a dada acotada a aquella transacció 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.

Seqüència d'integració del comerç

  1. Step 1 Provisionar el tenant del comerç, registrar els redirect URI i emetre credencials OAuth per al backend del POS o la middleware.
  2. Step 2 Crear una petició de consentiment amb els scopes necessaris, la referència de propòsit i el context de la sessió del POS.
  3. Step 3 Escanejar el QR de la Wallet del consumidor perquè YUNIT resolgui el token i iniciï el flux d'aprovació amb OTP per correu electrònic.
  4. Step 4 Rebre el codi d'autorització de vida curta després de l'aprovació i intercanviar-lo per un access token.
  5. Step 5 Llegir només les dades aprovades, completar la transacció del comerç i conservar la traça d'auditoria de la petició.

Exemple de petició 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'autorització

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 aprovació és un consentiment d'un sol ús. Una nova petició futura necessita una nova aprovació.
  • Els codis d'autorització i els access tokens han de tenir una vida curta i quedar limitats a la petició aprovada.
  • Els logs del comerç han de guardar request IDs, scopes, propòsit i resultat sense persistir PII innecessària.