Stampare un DC

Come ottenere dal documento emesso il PDF da condividere e i byte ESC/POS per la stampante termica, compresa la copia di cortesia.

Cosa restituisce l'emissione

Come richiesto dalle specifiche AdE, vendita, annullo e reso hanno un unico output: il PDF firmato (PAdES) del documento commerciale. Anche il replay con la stessa idempotency_key restituisce lo stesso PDF. Gli errori restano JSON, quindi controlla Content-Type prima di leggere il corpo.

POST …/fiscale/invio/dc

curl -X POST \
  https://pem-staging.billyssw.it/api/pem/ASVS-241232/fiscale/invio/dc \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @vendita.json \
  -D headers.txt -o DC.pdf

200 OK

Content-Type: application/pdf
Content-Disposition: inline; filename="DC_0012-0007.pdf"
Content-Location: https://pem-staging.billyssw.it/pem/ASVS-241232/fiscale/consultazione/dc/YjQ0ZDJmMGE5YzFl...MmEzYjQ%3D/pdf

Dove	Cosa contiene
corpo	I byte del PDF firmato, largo 120 mm. È il documento da mostrare, salvare o inviare al cliente.
metadati XMP del PDF	billy:escPosBase64: i comandi ESC/POS per la stampante termica, in base64.
Content-Location	L'URL pubblico dello stesso PDF. Il segmento prima di /pdf è l'hash del documento (URL-encoded), che serve per il reso e per l'invio email.
Content-Disposition	Il nome del file, DC_<progressivo>.pdf.

Stampa termica (ESC/POS)

Il testo per la stampante viaggia dentro il PDF, nel pacchetto XMP del catalogo, nell'elemento billy:escPosBase64 (namespace https://billy.it/ns/thermal/1.0/). Leggi i metadati con una libreria PDF, decodifica il base64 e invia i byte alla stampante così come sono.

PDF pubblico

L'URL di Content-Location è pubblico, senza token, e non sta sotto /api: il percorso è /pem/{serial_number}/fiscale/consultazione/dc/{hash}/pdf, con l'hash URL-encoded. È limitato a 60 richieste al minuto per indirizzo IP. Restituisce lo stesso PDF firmato e accetta parametri di impaginazione per rigenerarlo a un'altra larghezza.

GET …/consultazione/dc/{hash}/pdf

curl -o DC_58mm.pdf \
  "https://pem-staging.billyssw.it/pem/ASVS-241232/fiscale/consultazione/dc/YjQ0ZDJmMGE5YzFl...MmEzYjQ%3D/pdf?width=58&font_size=8"

Parametro	Regola
width	Larghezza in mm, da 58 a 120 (default 120). Valori fuori intervallo vengono riportati al limite.
font_size	Corpo del testo, da 6 a 14 (default 10), con lo stesso limite.
regalo	1 per la copia di cortesia; vedi sotto.

L'altezza della pagina segue il contenuto. Ogni PDF, anche quello rigenerato, contiene i propri metadati ESC/POS, ma width e font_size cambiano solo il PDF: l'ESC/POS segue sempre le impostazioni di stampa dell'esercente (32 o 48 colonne).

Copia di cortesia

Per i DC di vendita puoi stampare anche una copia senza importi, da dare insieme a un regalo: stesse informazioni fiscali (data, progressivo, codice lotteria, QR, hash, DataMatrix, seriale, righe di cortesia, appendice), ma solo descrizioni e quantità. Si ottiene aggiungendo ?regalo=1 all'URL di Content-Location: il PDF restituito ha nei metadati l'ESC/POS della copia, sempre a 32 colonne.

GET …/pdf?regalo=1

curl -o DC_0012-0007_regalo.pdf \
  "https://pem-staging.billyssw.it/pem/ASVS-241232/fiscale/consultazione/dc/YjQ0ZDJmMGE5YzFl...MmEzYjQ%3D/pdf?regalo=1"

Annulli e resi

Su annullo e reso regalo viene ignorato e l'URL restituisce il documento completo. Il documento di annullo riporta le righe del DC annullato.

Invio al cliente

In alternativa alla stampa, consegna al cliente il PDF ricevuto all'emissione oppure il link di Content-Location, che si apre senza credenziali.