Integrazioni POS

La pagina di impostazioni Integrazioni collega un server HandyCafe idoneo a un terminale Ödeal D2D. La disponibilità viene verificata tramite HandyCafe Cloud. Il menu e la pagina restano completamente nascosti quando il cafe non è autorizzato a usare Ödeal.

Prima di Iniziare

Ti servono un abbonamento HandyCafe Cloud attivo, una chiave merchant Ödeal e una chiave segreta Ödeal. Devi inoltre creare il terminale nell'area Cihazlarım di Ödeal. Il nome esatto assegnato a quel terminale è il suo externalDeviceKey. Inizia con l'ambiente Stage. Passa a Production solo dopo che Ödeal ha approvato le credenziali di produzione e la configurazione del callback.

Configurare Ödeal

1. Apri Impostazioni e seleziona Integrazioni.
2. In Account Ödeal, inserisci la chiave merchant e la chiave segreta fornite da Ödeal. HandyCafe invia questi valori direttamente a HandyCafe Cloud. Vengono crittografati e non sono memorizzati nel database locale né mostrati di nuovo.
3. Seleziona Test di Connessione. Quando sono presenti chiavi nuove, HandyCafe le salva in modo sicuro prima di testare la connessione all'API Ödeal. Questo test verifica soltanto l'account Ödeal. Non dimostra che il terminale sia accoppiato o online.
4. Aggiungi il terminale. Inserisci un nome locale chiaro per il dispositivo. In Nome dispositivo Ödeal (externalDeviceKey) inserisci il nome esatto del dispositivo creato in Ödeal. Poi inserisci il PaxID facoltativo, l'ambiente, il tempo di attesa del pagamento, la città del cliente, il distretto del cliente, l'aliquota IVA della sessione e l'aliquota IVA dell'ordine.
5. Attiva Integrazione POS Attiva e seleziona Salva.
6. Completa in Stage uno scontrino in contanti e un pagamento con carta per verificare l'accoppiamento del terminale ed entrambi i percorsi di incasso.

In questa versione è supportato un solo terminale Ödeal attivo per server. Questo evita che un pagamento venga instradato verso un terminale non previsto prima che sia disponibile un selettore di terminale per il cassiere.

HandyCafe salva l'inventario dei terminali in locale prima che il Cloud verifichi una nuova coppia di credenziali. Il rifiuto di una credenziale Ödeal non cancella il nome del terminale né i campi di accoppiamento. Un terminale che richiede credenziali nuove viene memorizzato come inattivo finché quelle credenziali non sono verificate per l'ambiente selezionato.

La pagina Integrazioni legge l'inventario dei terminali direttamente dal database SQLite locale e lo mostra senza attendere il Cloud. Solo lo stato delle credenziali crittografate e il permesso remoto del fornitore richiedono una richiesta al Cloud.

Se Ödeal rifiuta la configurazione, HandyCafe mostra la spiegazione restituita da Ödeal. Una risposta che segnala profilo organizzazione non trovato significa che la coppia di chiavi merchant e segreta non appartiene a nessuna organizzazione nell'ambiente Stage o Production selezionato.

Comportamento dei Pagamenti

Quando il metodo di pagamento attivo è contanti o carta, la chiusura della sessione su PC, la chiusura della sessione su console e la chiusura di un ordine autonomo inviano a Ödeal un carrello idempotente. I contanti vengono inviati come opzione di pagamento CASH documentata da Ödeal. Il terminale registra il pagamento in contanti e stampa lo scontrino fiscale o la ricevuta e-Archive senza aprire la schermata di incasso con carta. La carta viene inviata come CREDITCARD; HandyCafe attende l'esito del callback mentre il cliente completa il pagamento sul terminale. Una chiusura che contiene sia contanti sia carta invia entrambe le opzioni di pagamento con i rispettivi importi.

Il cliente può scegliere la rateizzazione sul terminale quando la carta e il contratto dell'esercente la consentono. HandyCafe memorizza il numero di rate comunicato insieme alla vendita locale. La vendita locale viene registrata solo dopo che Ödeal ha confermato la transazione. Se la registrazione locale fallisce dopo la conferma, HandyCafe richiede un annullamento in giornata. Un annullamento non riuscito genera un errore di riconciliazione manuale e va controllato nel report delle transazioni Ödeal. I metodi di pagamento diversi da contanti e carta proseguono con il normale flusso di incasso di HandyCafe.

Test e Operazioni sul Terminale

Test di Connessione verifica soltanto le credenziali merchant Ödeal e l'accesso all'API. Non stampa uno scontrino, non addebita una carta e non dimostra che externalDeviceKey sia accoppiato con il terminale.

La documentazione dell'API D2D fornita non definisce endpoint separati per Stampa scontrino di prova o Addebito di prova. I test di accettazione usano carrelli normali nell'ambiente Stage: invia un carrello in contanti e verifica lo scontrino stampato, poi invia un carrello con carta e completa sul terminale una transazione in soluzione unica o rateale. Usa esclusivamente i dati delle carte di test Stage forniti da Ödeal.

I casi di accettazione Ödeal comprendono la chiusura giornaliera e la ristampa dell'ultimo scontrino. Si tratta però di operazioni del terminale. D2D non documenta chiamate API remote per svolgerle, quindi HandyCafe non le espone come pulsanti remoti.

Attivazione e Disattivazione da Remoto

Gli amministratori HandyCafe controllano Ödeal da Admin > Impostazioni Admin > Fornitori POS nella Dashboard. L'interruttore globale è il controllo principale. I valori predefiniti per paese usano i codici ISO di due lettere come TR. I controlli per singolo cafe possono aprire o chiudere esplicitamente Ödeal per una licenza. Una decisione specifica del cafe prevale sul valore predefinito del paese. Azzerando la decisione del cafe, quel cafe torna a seguire il proprio paese.

L'ordine di valutazione è interruttore globale, decisione specifica del cafe e infine valore predefinito del paese. Un interruttore globale disattivato chiude Ödeal per ogni cafe. Una chiusura esplicita del cafe nasconde la pagina anche quando il suo paese è aperto. Un'apertura esplicita del cafe consente la pagina anche quando il suo paese non è nell'elenco predefinito. La disattivazione dell'accesso blocca immediatamente la creazione di nuovi carrelli. Le transazioni in sospeso esistenti possono ancora essere verificate o annullate, così un pagamento in corso non resta bloccato.

Il server verifica la disponibilità tramite HandyCafe Cloud e mette in cache l'ultima decisione di paese o cafe verificata con successo. Il catalogo dei fornitori restituisce HTTP 200 con un error.code strutturato quando la sua credenziale non è valida. Il desktop gestisce quella risposta aggiornando la credenziale e riprovando. Un guasto temporaneo di autenticazione o di rete non fa interpretare come disattivata una decisione dell'amministratore che è invece attiva, quindi il menu Integrazioni resta stabile. Una risposta successiva andata a buon fine aggiorna subito la cache, compresa una decisione di disattivazione dell'amministratore. In assenza di una decisione verificata in precedenza, un paese del cafe sconosciuto, un abbonamento non attivo o un fornitore disattivato mantengono la pagina nascosta. Le nuove operazioni Ödeal vengono sempre autorizzate di nuovo dal Cloud anche quando si usa la visibilità in cache. Quando il profilo del cafe sincronizzato non ha un paese, viene usato il paese salvato sulla licenza.

Sicurezza e Ripristino

Le credenziali Ödeal sono crittografate in HandyCafe Cloud con la chiave del vault dell'installazione. Le richieste di callback sono autenticate dalla chiave di richiesta configurata oppure dagli header merchant e secret di Ödeal. I codici di riferimento del carrello sono stabili per ogni ordine o sessione. Ripetere la stessa chiusura non genera un secondo addebito.

L'annullamento Ödeal è disponibile solo secondo le regole Ödeal della stessa giornata, prima che il terminale chiuda il lotto. Un carrello in sospeso può essere rimosso separatamente prima che il pagamento si concluda. Ödeal D2D non offre un'operazione di rimborso generica. Usa il back office Ödeal e il report delle transazioni quando la finestra di annullamento è scaduta.

Ödeal D2D non offre un'operazione documentata di report Z remoto o di chiusura giornaliera. Completa la chiusura giornaliera sul terminale. HandyCafe può leggere i report delle transazioni per la riconciliazione e registra i callback di payback inviati da Ödeal.