# BillySSW

> Documentazione per gli sviluppatori di gestionali e software di cassa che si integrano con l'API fiscale di BillySSW: emissione dei documenti commerciali tramite punti di emissione (PEM) in cloud, chiusura di cassa, modalità di emergenza, autenticazione OAuth 2.0 con il consenso dell'esercente e riferimento REST completo.

La documentazione è in italiano. Ogni pagina ha una versione Markdown completa, linkata qui sotto; la versione HTML è all'URL senza `.md`. Gli esempi usano l'host di staging `https://pem-staging.billyssw.it`.

## Panoramica
- [Panoramica](https://app.billyssw.it/documentazione/panoramica.md): Cos'è la Soluzione Software, come lavorano PEM e PEL e cosa resta al gestionale che si integra con le API.

## Inizia
- [Percorso di integrazione](https://app.billyssw.it/documentazione/checklist.md): I passi dall'affiliazione al go-live: ambiente di prova, consenso dell'esercente, primo documento, passaggio in produzione.
- [Autenticazione](https://app.billyssw.it/documentazione/auth.md): OAuth 2.0 Authorization Code con PKCE: registrazione del client, scope, scambio del codice, rinnovo del token, durata e revoca.
- [Guida rapida](https://app.billyssw.it/documentazione/quickstart.md): Dal token al primo documento commerciale: trovare il PEM, emettere una vendita e leggere il PDF firmato della risposta.

## Guide
- [Registrare un esercente](https://app.billyssw.it/documentazione/esercente.md): Richiesta di registrazione di un esercente via API o modulo web, campi richiesti e attivazione dopo l'approvazione.
- [Registrare un PEM](https://app.billyssw.it/documentazione/nuovopem.md): Creazione e censimento automatico del PEM, i suoi stati, il cambio di stato e la dismissione.
- [Emettere DC](https://app.billyssw.it/documentazione/receipts.md): Vendita, annullo, reso e chiusura di cassa: regole dei campi, importi e quantità, idempotenza.
- [Modalità di emergenza](https://app.billyssw.it/documentazione/emergenza.md): Cosa fare con il PEM fuori servizio: motivazioni, registro di emergenza e chiusura di emergenza con i riepiloghi IVA.
- [Stampare un DC](https://app.billyssw.it/documentazione/stampa.md): Il PDF firmato restituito dall'emissione, il testo ESC/POS nei metadati XMP, il PDF pubblico e la copia di cortesia.

## API
- [Base URL](https://app.billyssw.it/documentazione/ambienti.md): Gli ambienti di staging e di produzione e come comporre l'URL di ogni chiamata.
- [REST API](https://app.billyssw.it/documentazione/api.md): Tutte le operazioni REST con parametri, corpo della richiesta, risposte ed errori, generate dalla specifica OpenAPI.
- [Codici di errore](https://app.billyssw.it/documentazione/errors.md): Codici HTTP, formati del corpo degli errori e codici di dominio dell'API fiscale, con l'azione da intraprendere.

## Optional
- [Documentazione completa](https://app.billyssw.it/documentazione/full.md): tutte le pagine sopra in un unico file Markdown
- [Specifica OpenAPI](https://app.billyssw.it/documentazione/openapi.json): la specifica OpenAPI 3 in JSON, per generatori di client e Postman