NoPos Protocol
NoPos 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 per registratori di cassa, NoPos Protocol parla JSON nativo, risponde con un envelope consistente e usa gli stessi modelli dell'ecosistema NoPos.
Quando usarlo
Usa NoPos Protocol 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
NoPos Protocol è il protocollo raccomandato per tutte le nuove integrazioni con l'ecosistema NoPos.
Come funziona
NoPos Protocol gira localmente sul dispositivo: il server viene avviato automaticamente dall'app NoPos sulla cassa. Non hai bisogno di installare nulla di separato — il tuo software deve solo fare chiamate HTTP verso l'indirizzo IP locale della cassa sulla stessa rete.
[Il tuo software] ──HTTP/JSON──> [NoPos Protocol : 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. Tutta la comunicazione avviene in rete locale: nessun dato transita su server esterni.
Porta e discovery
| Porta | Protocollo |
|---|---|
5200 | NoPos Protocol (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:
{
"success": true,
"data": { ... }
}
{
"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.
400 viene restituito se mancano campi obbligatori nel body. 404 se la route non esiste. 500 per errori interni non gestiti.
Endpoints
Stato
| Metodo | Path | Descrizione |
|---|---|---|
GET | /status | Stato del server e provider configurati |
Pagamenti
| Metodo | Path | Descrizione |
|---|---|---|
GET | /payments | Lista transazioni (con filtri opzionali) |
GET | /payments/:id | Dettaglio transazione |
POST | /payments | Avvia un pagamento sul terminale |
DELETE | /payments | Annulla il pagamento attivo sul terminale |
DELETE | /payments/:id | Rimborsa una transazione |
Scontrini fiscali
| Metodo | Path | Descrizione |
|---|---|---|
GET | /receipts | Lista scontrini |
GET | /receipts/:id | Dettaglio scontrino |
POST | /receipts | Emette uno scontrino fiscale |
Fatture elettroniche
| Metodo | Path | Descrizione |
|---|---|---|
GET | /invoices | Lista fatture |
GET | /invoices/:id | Dettaglio fattura |
POST | /invoices | Emette una fattura elettronica |
Configurazione nella cassa
Prima di usare il protocollo, configura il bridge nella cassa NoPos:
- Vai su Bridge nell'app NoPos
- Crea un nuovo bridge con protocollo NoPos
- Seleziona il provider di pagamento (es. SumUp, Viva)
- Seleziona il provider fiscale (es. Fiskaly, ADE)
- 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.