visualizzafe

POST/renderX-Api-Key

Trasforma una fattura in HTML

Restituisce l'HTML della fattura, da mostrare in un campo Web Viewer o da salvare.

Input accettati. corpo grezzo (consigliato)  •  multipart file o xml  •  JSON {"xml_base64": "…"}

cURL

curl -X POST -H "X-Api-Key: LA_TUA_CHIAVE" \
  --data-binary @fattura.xml \
  "http://visualizzafe.cmisolutions.it:3001/render?style=assosoftware" -o fattura.html

FileMaker

Set Variable [ $xml ; value: Fatture::XML ]

Insert from URL [
    Select ; With dialog: Off ; Target: $html ;
    "http://visualizzafe.cmisolutions.it:3001/render?style=assosoftware" ;
    cURL options: "--data-binary @$xml -H \"X-Api-Key: " & $$API_KEY & "\""
]

Risposta

L'HTML della fattura.

Da sapere

• Accetta anche i .p7m: la busta viene aperta automaticamente.
• style è obbligatorio: senza, ricevi 400.

POST/uploadX-Api-Key

Crea un link temporaneo alla fattura

Come /render, ma invece dell'HTML restituisce un link da aprire nel browser con Open URL. Utile per mostrare la fattura senza gestire l'HTML dentro FileMaker.

cURL

curl -X POST -H "X-Api-Key: LA_TUA_CHIAVE" \
  --data-binary @fattura.xml \
  "http://visualizzafe.cmisolutions.it:3001/upload?style=assosoftware&ttl=3600" 

FileMaker

Set Variable [ $xml ; value: Fatture::XML ]

Insert from URL [
    Select ; With dialog: Off ; Target: $risposta ;
    "http://visualizzafe.cmisolutions.it:3001/upload?style=assosoftware&ttl=3600" ;
    cURL options: "--data-binary @$xml -H \"X-Api-Key: " & $$API_KEY & "\""
]
Set Variable [ $url ; value: JSONGetElement ( $risposta ; "absolute_url" ) ]
Open URL [ $url ]     # nessuna chiave: il token NELL'URL è l'autenticazione

Risposta

JSON: url, absolute_url, expires_in_seconds.

Da sapere

• Metti style e ttl nell'URL, non fra le opzioni cURL: -d e --data-binary scrivono entrambi nel corpo e curl li concatena con &, rovinando l'XML.
• Il link /v/<token> si apre senza chiave: chiunque lo abbia vede la fattura finché non scade.

POST/validateX-Api-Key

Valida una fattura contro l'XSD

Controlla la fattura rispetto allo schema ufficiale FatturaPA e restituisce gli errori in forma leggibile.

cURL

curl -X POST -H "X-Api-Key: LA_TUA_CHIAVE" \
  --data-binary @fattura.xml "http://visualizzafe.cmisolutions.it:3001/validate" 

Risposta

JSON: valid, errors, warnings, versione, xsd.

Da sapere

• Ottimo per capire perché lo SdI potrebbe scartare una fattura, prima di inviarla.

POST/upload-batchX-Api-Key

Riepilogo di più fatture

Carica più fatture insieme e ottiene un link a una pagina di riepilogo.

Input accettati. multipart con più campi file

cURL

curl -X POST -H "X-Api-Key: LA_TUA_CHIAVE" \
  -F file=@f1.xml -F file=@f2.xml \
  "http://visualizzafe.cmisolutions.it:3001/upload-batch?style=assosoftware" 

Risposta

JSON con url della pagina di riepilogo (/b/<token>).

GET/v/<token>senza chiave

Apri una fattura condivisa

Mostra la fattura creata da /upload. Non richiede chiave: il token nell'URL è l'autenticazione — un browser non può mandare header custom, quindi proteggerlo renderebbe i link inservibili.

cURL

# si apre semplicemente nel browser, o con Open URL da FileMaker
http://visualizzafe.cmisolutions.it:3001/v/dV7l8ErCGzGcVlJmQm1Trg?style=assosoftware

Risposta

L'HTML della fattura.

Da sapere

• Usa il link completo restituito da /upload: senza ?style= ricevi 400.

—Autenticazionesenza chiave

Come funzionano le chiavi

Una chiave = un soggetto (un database FileMaker, uno script, n8n). Ogni chiave porta l'elenco dei servizi su cui è abilitata, quindi la stessa chiave può valere su più servizi — ed è quello che vuoi: così le statistiche attribuiscono tutto il consumo a un'unica riga. Non condividere una chiave fra due soggetti: perderesti proprio l'informazione per cui l'hai creata. Le chiavi le gestisce l'amministratore: se te ne serve una, o la tua non funziona più, chiedila a lui.

cURL

# su ogni POST di lavoro
-H "X-Api-Key: cmi_xxxxxxxxxxxx"

# in FileMaker, tenendo la chiave in una variabile globale sola:
"-H \"X-Api-Key: " & $$API_KEY & "\"" 

Risposta

Se la chiave manca o è errata: 401 con un messaggio esplicito (mancante, non riconosciuta, revocata, non abilitata per questo servizio).

Da sapere

• Restano aperti senza chiave: /health e la pagina di test su /.
• Revoche e nuove chiavi hanno effetto immediato, senza riavviare i servizi.
• Oltre ai servizi, una chiave può essere ristretta ai singoli endpoint. Se è abilitata al servizio ma non a quella rotta la risposta è 403 (non 401: la chiave è valida, manca il permesso). Le restrizioni si impostano dal pannello di amministrazione e valgono subito.
• Ogni risposta porta X-Esito: ok|errore e X-Status. Servono da FileMaker: Insert from URL NON fallisce sugli errori HTTP — Get(LastError) resta 0 e il corpo dell'errore finisce nel contenitore, sovrascrivendo l'allegato buono. Con --dump-header $h si controlla l'esito prima di scrivere sul campo. Regola d'oro: mandare il risultato in una variabile, verificare, e solo allora fare Set Field.
• Nome del file restituito: gli endpoint che restituiscono un file accettano ?filename=. Senza, si usa il nome originale se l'invio è multipart (che lo porta con sé); con --data-binary il nome si perde, quindi lì il parametro serve. L'estensione è sempre quella d'uscita, sostituita e non appesa. Il nome è anche nell'header X-Filename.

GET/healthsenza chiave

Stato del servizio

Sonda di vita, aperta e non contabilizzata: un check ogni minuto non sporca le statistiche.

cURL

curl http://visualizzafe.cmisolutions.it:3001/health

Risposta

JSON con status, service, la versione della libreria e auth (se l'obbligo di chiave è attivo).