Vai al contenuto

🔄 Single Sign-On (SSO)

Endpoint Principale

POST https://ws.salabam.com/ws/v1/sso/{username}

Headers Richiesti

Content-Type: application/json

Request Body

{
  "message": "token request",
  "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Parametri JWT Data

employee (obbligatorio)

Campo Tipo Obbligatorio Validazione Esempio
id string âś… Alfanumerico, max 50 char "EMP123"
name string âś… Solo lettere, max 50 char "Mario"
surname string âś… Solo lettere, max 50 char "Rossi"
email string âś… Formato email valido "mario.rossi@company.com"
fiscalCode string âś… Codice fiscale italiano "RSSMRA85M01H501X"
availability number âś… Decimale positivo 750.50
company string ❌ Nome azienda "ACME Corp"

beneficiaries (opzionale)

⚠️ IMPORTANTE: La gestione dei beneficiari segue regole specifiche basate su come viene valorizzato il campo:

🔓 Scenario 1: Campo OMESSO (undefined)

{
  "employee": { ... }
  // beneficiaries non presente
}
Risultato: Il dipendente può inserire liberamente un beneficiario in fase di checkout. Il sistema mostra un campo di input libero.

đź”’ Scenario 2: Campo VUOTO

{
  "employee": { ... },
  "beneficiaries": {}  // oggetto vuoto
}
Risultato: Il checkout è vincolato - il dipendente può scegliere SOLO se stesso come beneficiario. Non può inserire altri beneficiari.

đź‘Ą Scenario 3: Campo con ARRAY di beneficiari

{
  "employee": { ... },
  "beneficiaries": [
    {
      "id": "BEN001",
      "name": "Laura",
      "surname": "Bianchi",
      "fiscalCode": "BNCLRA82D45H501Y",
      "email": "laura.bianchi@email.com",
      "relation": "coniuge"
    },
    {
      "id": "BEN002",
      "name": "Marco",
      "surname": "Rossi",
      "fiscalCode": "RSSMRC10A01H501Z",
      "relation": "figli"
    }
  ]
}
Risultato: Il dipendente può scegliere tra: - Se stesso (sempre incluso automaticamente) - I beneficiari specificati nell'array - L'ordine di visualizzazione segue l'ordine degli ID

Note Importanti sui Beneficiari

  • L'employee è SEMPRE disponibile come beneficiario, non va mai incluso nell'array
  • ID restituito = 0: Quando il dipendente inserisce un beneficiario "a piacere" (scenario 1), l'ID restituito nelle callback sarĂ  sempre 0 (zero)
  • Ordinamento: I beneficiari vengono mostrati nell'ordine in cui sono stati passati nell'array
  • Email fallback: Se non specificata per un beneficiario, viene usata quella dell'employee
  • Relazioni supportate: me, coniuge, figli, fratello, sorella, genero, nuora, genitore, suoceri, non specificato

customizations (opzionale)

Campo Tipo Descrizione Limiti
logo string URL logo personalizzato Max 300x200px, <100KB
logoUrl string Link click su logo HTTPS obbligatorio
use string Set customizzazioni predefinite Solo se autorizzato

billing (opzionale - solo casi eccezionali)

⚠️ ATTENZIONE: La fatturazione a soggetti terzi è disponibile solo per casi eccezionali previa autorizzazione Salabam.

{
  "billing": {
    "businessName": "ACME Corp SRL",
    "address": "Via Roma 123",
    "postalCode": "20100",
    "city": "Milano",
    "province": "MI",
    "vatNumber": "12345678901",
    "fiscalCode": "12345678901",
    "sdi": "M5UXCR1",
    "administrationEmail": "admin@company.com",
    "orderBccEmail": "orders@company.com"
  }
}

Callback URLs

orderAuthUrl (obbligatorio)

Endpoint per autorizzazione ordine. Deve rispondere entro 25 secondi.

POST https://yourdomain.com/api/authorize

Request da Salabam: 

{
  "message": "order authorization request",
  "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

JWT Decodificato contiene: 

{
  "data": {
    "id": "1",  // ID employee o beneficiario (0 se inserito a piacere)
    "relation": "me",  // Relazione del beneficiario
    "name": "Mario",
    "surname": "Rossi",
    "fiscalCode": "RSSMRA85M01H501X",
    "email": "mario.rossi@company.com",
    "salabamReferenceId": 159,
    "productName": "Salabam Italia Standard - 1 notte",
    "price": "100.00",
    "productType": "boxset-eu",
    "service": "shop"
  }
}

Response attesa (HTTP 200): 

{
  "status": "success",
  "message": "order authorized"
}

orderConfirmUrl (opzionale - modalitĂ  doppia conferma)

Conferma definitiva ordine.

POST https://yourdomain.com/api/confirm

orderRevokeUrl (opzionale - modalitĂ  doppia conferma)

Annullamento ordine non confermato.

POST https://yourdomain.com/api/revoke

Response SSO

Successo (200)

{
  "status": "success",
  "message": "ok",
  "jwt": "response_jwt_with_session_data",
  "data": {
    "redirectTo": "https://salabam.com/sso/token/abc123def456"
  }
}

Errore (400)

{
  "error": "missing or invalid body fields",
  "fieldsWithError": {
    "jwt": "invalid token format",
    "employee.email": "invalid email format"
  },
  "errno": 400,
  "hint": "check fieldsWithError for details"
}

ModalitĂ  Doppia Conferma

Per servizi che richiedono conferma in due fasi (Travel Welfare/Benefit):

  1. Autorizzazione → orderAuthUrl
  2. Conferma → orderConfirmUrl (entro 6 ore)
  3. Eventuale Revoca → orderRevokeUrl

Flusso Doppia Conferma

sequenceDiagram
    User->>Partner: Richiesta acquisto
    Partner->>Salabam: SSO con orderConfirmUrl
    Salabam->>User: Mostra prodotti
    User->>Salabam: Seleziona prodotto
    Salabam->>Partner: POST orderAuthUrl
    Partner->>Partner: Verifica credito
    Partner->>Salabam: 200 OK (congela credito)
    Salabam->>Partner: POST orderConfirmUrl
    Partner->>Partner: Addebita credito
    Partner->>Salabam: 200 OK
    Salabam->>User: Conferma acquisto