NoPos Local Protocol

NoPos Local Protocol è un protocollo HTTP proprietario che gira in locale sul dispositivo (cassa, tablet, server di punto vendita) e ti permette di gestire pagamenti e documenti fiscali attraverso endpoint REST/JSON puliti.

A differenza dei protocolli legacy (ECR17, FEPos, XON/XOFF), NoPos Local parla JSON nativo, risponde con un envelope consistente e usa gli stessi modelli dell'ecosistema NoPos.

Quando usarlo

Usa NoPos Local quando:

• Hai un software di cassa o un gestionale che gira sulla stessa rete locale della cassa NoPos
• Vuoi integrare pagamenti e scontrini senza implementare protocolli binari o SOAP/XML
• Preferisci una singola integrazione REST che copra sia i pagamenti che il fiscale

Protocolli alternativi

Se il tuo software già parla ECR17 (pagamenti) o FEPos / XON/XOFF (stampanti fiscali), puoi usare quelli. NoPos Local è il protocollo raccomandato per le nuove integrazioni.

Come funziona

Il server NoPos Local viene avviato automaticamente dall'app NoPos sul dispositivo. Non hai bisogno di installare nulla: il tuo software deve solo fare chiamate HTTP verso l'indirizzo IP locale della cassa.

[Il tuo software] ──HTTP/JSON──> [NoPos Local : 5200] ──> [Provider pagamento]
                                                       ──> [Provider fiscale]

Il bridge NoPos riceve la richiesta, la instrada verso il provider di pagamento o fiscale configurato nella cassa, e restituisce la risposta.

Porta e discovery

Porta	Protocollo
5200	NoPos Local (default)

L'IP del dispositivo è visibile nella sezione Bridge dell'app NoPos. Se hai più dispositivi in rete, ogni cassa espone il proprio server sulla stessa porta.

Envelope di risposta

Tutte le risposte usano lo stesso envelope:

Successo

{
  "success": true,
  "data": { ... }
}

Errore

{
  "success": false,
  "error": "Descrizione dell'errore"
}

Non ci sono codici di stato HTTP diversi da 200 per gli errori applicativi: lo stato HTTP è 200, la distinzione successo/errore è sempre nel campo success.

Eccezioni

400 viene restituito se mancano campi obbligatori nel body. 404 se la route non esiste. 500 per errori interni non gestiti.

Endpoints

Metodo	Path	Descrizione
GET	/status	Stato del server e provider configurati
POST	/payments	Avvia un pagamento
POST	/payments/refund	Rimborsa una transazione
POST	/receipts	Emette uno scontrino fiscale
POST	/invoices	Emette una fattura elettronica

Configurazione nella cassa

Prima di usare il protocollo, configura il bridge nella cassa NoPos:

1. Vai su Bridge nell'app NoPos
2. Crea un nuovo bridge con protocollo NoPos
3. Seleziona il provider di pagamento (es. SumUp, Viva)
4. Seleziona il provider fiscale (es. Fiskaly, ADE)
5. Annota l'indirizzo IP locale mostrato nella scheda del bridge

Il bridge gestisce automaticamente il routing verso i provider configurati: il tuo software non ha bisogno di sapere quale provider è in uso.