API del sistema POSUn unico punto di ingresso dal tuo POS a fiskaltrust.Middleware.
Crea ricevute, esegui pagamenti, emetti ricevute digitali ed esporta diari attraverso un'unica API HTTP orientata ai processi.
L’API ti permette di concentrarti sul tuo sistema mentre fiskaltrust si occupa dell’infrastruttura delle ricevute. Invece di trattare le ricevute come una funzione secondaria o un componente aggiuntivo per i consumatori, Receipt-API gestisce le ricevute come un componente del sistema regolamentato di prima classe. Si integra una sola volta e si fa affidamento su un’API unificata e open-source che viene mantenuta in base all’evoluzione delle normative e dei requisiti operativi.
L’API del sistema POS fiskaltrust funge da interfaccia centrale tra i sistemi POS e il middleware fiskaltrust. Offre una serie completa di funzionalità, tra cui la fiscalizzazione (o firma) degli scontrini, l’esecuzione di pagamenti tramite vari fornitori, la stampa di scontrini digitali e l’esportazione di dati dal Middleware.
Attraverso endpoint semplici e coerenti, l’API supporta funzioni chiave: /echo per i test di connettività, /order per registrare i dati dell’ordine, /pay per l’assegnazione del pagamento, /sign per sigillare le transazioni, /issue per generare ricevute digitali o stampabili e /journal per le esportazioni pronte per la revisione.
Endpoint API di facile lettura
PosSystem-API internazionale
- /echo,controllo dello stato di salute e ripristino.
- /order,registra le informazioni sull'ordine e lo stato o il risultato della query.
- /pay,esegue i pagamenti, attende il completamento con timeout, recupera i risultati.
- /sign,finalizzare le ricevute con le regole nazionali e la concatenazione dell'hashish.
- /issuecreare e aggiornare la ricevuta emessa, compreso lo stato di consegna.
- /journal,recuperare singole voci o intervalli per le verifiche e le chiusure.
API per rivenditori POS. Costruito per integrazioni stabili, trasparenti e a prova di audit.
Progettata per l’uso multipiattaforma, l’API supporta implementazioni locali e istanze ospitate nel cloud nei data center europei. Fornisce un’archiviazione sicura delle revisioni e si integra con il Middleware fiskaltrust per gli aggiornamenti automatici della conformità.
Alcune parti dell’API e del Middleware sono open source e offrono trasparenza e stabilità a lungo termine. Grazie alla documentazione aperta e a un modello di dati uniforme, questo riduce il lavoro di manutenzione e mantiene le soluzioni POS a prova di audit.
Un'unica API, un comportamento coerente, indipendentemente dai requisiti specifici del paese.
Concetti fondamentali
L’API tratta una transazione come un viaggio. Ogni tappa modifica lo stato del server. Ad ogni chiamata si passa un identificatore di operazione unico. Se la rete cade, si ripete la stessa chiamata con lo stesso identificatore.
Il backend deduplica e restituisce il primo risultato completato. Questo design offre tentativi sicuri e risultati prevedibili per le fasi fiscali critiche.
- Punto di ingresso centrale al middleware per la fiscalizzazione, i pagamenti, l’emissione e l’esportazione.
- Modelli di chiamata processuale e statica che si comportano come una macchina a stati.
- Idempotenza attraverso l’intestazione x-operation-id con risposte deterministiche al tentativo.
- Ganci di callback per osservare le transizioni di stato durante le operazioni lunghe.
Una richiesta con x-operation-id entra nel Middleware
Middleware elaborazione
Riprova con lo stesso x-operation-id
Risultato completato
Endpoint di callback x-operation-callback-state
Autenticazione e versioning
L’accesso è limitato dalla CashBox. Utilizzi CashBoxId e AccessToken dal portale. L’API segue il versioning semantico. Le modifiche sono limitate alle versioni principali e possono essere inserite nell’URL quando necessario.
- Credenziali: CashBoxId e AccessToken.
- Versione semantica, ultima per impostazione predefinita, con supporto del pinning esplicito.
Sviluppatore POS
Autenticazione CashBoxId + AccessToken
V1
V2
V3
Modelli diAPI asincrone
L’API ti permette di concentrarti sul tuo sistema mentre fiskaltrust si occupa dell’infrastruttura delle ricevute. Invece di trattare le ricevute come una funzione secondaria o un componente aggiuntivo per i consumatori, Receipt-API gestisce le ricevute come un componente del sistema regolamentato di prima classe. Si integra una sola volta e si fa affidamento su un’API unificata e open-source che viene mantenuta in base all’evoluzione delle normative e dei requisiti operativi.
Intestazioni e idempotenza
Ogni chiamata critica accetta intestazioni di controllo. x-operation-id è la chiave di idempotenza. x-operation-lifetime definisce la durata di validità dell’operazione. Puoi impostare un URL di callback per ogni chiamata per ricevere i messaggi di stato senza effettuare il polling.
- x-operation-id, unico per operazione per deduplicare i tentativi.
- x-operation-lifetime, finestra di accettazione in millisecondi.
- x-operation-callback-state, notifica ad ogni cambio di stato.
- x-terminal-id e x-possystem-id opzionali per l’attribuzione.
Stato di consegna e ricezione
Dopo l’emissione, puoi recuperare il contenuto emesso, aggiornarlo o interrogare lo stato di consegna. Esistono endpoint bloccanti che attendono fino a un timeout massimo e segnalano la consegna o la mancata consegna. Questo semplifica i flussi degli utenti al momento del checkout ed evita il polling.
Ambienti
L’API fornisce ambienti sandbox e di produzione per ogni endpoint. Usa la sandbox per l’integrazione e i test automatici. Promuovi le stesse chiamate alla produzione quando sei pronto. L’AynchronousAPI, le intestazioni e i callback si comportano allo stesso modo in entrambi.
Gestione degli errori
Le chiamate restituiscono codici di stato HTTP standard. Le richieste malformate o le intestazioni mancanti producono errori del client. I fallimenti dell’autenticazione restituiscono la dicitura “non autorizzato”. Il server riporta gli errori inattesi con i dettagli del problema, se disponibili. I tentativi con lo stesso identificatore di operazione restituiscono il primo risultato finito.
Utilizza un'interfaccia aperta e documentata che si adatta ai cambiamenti delle normative.
Come funziona in 3 passi
Configuri un CashBox nel portale e ottieni le credenziali. Il tuo POS chiama il carrello, l’ordine e il pagamento per costruire il viaggio. Completi con la firma e l’emissione, poi leggi le voci del giornale per la chiusura giornaliera o per le verifiche. Ripeti i passaggi falliti in modo sicuro riutilizzando l’identificativo dell’operazione.
1.
Iscriviti sul sito fiskaltrust.Portal.
2.
Crea una cassa e collegala al tuo POS o ERP.
3.
Guida il viaggio: carrello, ordine, pagamento, firma, emissione.
Elementi essenziali per lo sviluppatore
Inizia dalle specifiche OpenAPI e dalla documentazione aggiornata. Esamina i diagrammi di SynchronousAPI e il contratto di intestazione. Costruisci i tentativi con idempotenza e callback. Usa la sandbox per convalidare le transizioni di stato e il comportamento di consegna delle ricevute prima della produzione.
- Pagina dei documenti dell’API del sistema POS e file OpenAPI.
- Diagrammi di temporizzazione e di stato di SynchronousAPI.
- Sandbox endpoint per echo, carrello, ordine, pagamento, firma, emissione, giornale.
Domande sull'integrazione? Il nostro team tecnico è a portata di messaggio.
Contattaci