Come funziona
FiscoJet abbina ogni pagamento Stripe ai dati di fatturazione del cliente. Il tuo server crea un riferimento con i prodotti dell'ordine e lo scrive nei metadata del PaymentIntent, nella chiave fj_ref. I dati di fatturazione li manda il tuo server insieme ai prodotti, oppure li raccoglie il form hosted nella tua pagina. Quando il pagamento riesce, FiscoJet prepara la fattura elettronica e la manda allo SDI.
- Riferimento
fj_ref_…. Collega un ordine al suo pagamento Stripe. Lo crei conPOST /checkouto conPOST /checkout/session.- Sessione
fj_cs_…. Serve al form hosted per allegare i dati di fatturazione a un riferimento. Scade dopo 24 ore.- FatturaPA
- Il formato XML della fattura elettronica italiana. FiscoJet compila l'XML con i tuoi dati, quelli del cliente e l'importo incassato.
- SDI
- Il Sistema di Interscambio dell'Agenzia delle Entrate. Riceve le fatture elettroniche e le recapita ai destinatari.
Indirizzo e autenticazione
Le chiamate partono dal tuo server verso questo indirizzo, con la chiave segreta fj_live_sk_… nell'header Authorization. I corpi delle richieste sono JSON. La chiave la generi nella pagina Sviluppatore della dashboard.
https://api.fiscojet.com
Authorization: Bearer fj_live_sk_…
Content-Type: application/jsonSe la chiave non va, la risposta è 401 con uno di questi messaggi:
| Caso | message |
|---|---|
| Manca l'header | API key mancante (Authorization: Bearer <key>). |
| Chiave sconosciuta | API key non valida. |
| Chiave sostituita | API key revocata. Succede quando generi una chiave nuova. |
La chiave pubblica fj_pk_live_… serve solo al form hosted, che la manda nell'header X-FiscoJet-Key. Con gli endpoint di questa pagina non funziona.
Formato delle risposte
Ogni risposta è un oggetto JSON con error e success. Se la chiamata riesce, il risultato è in data. Se non riesce, message spiega il motivo. Quando i dati di fatturazione non sono validi c'è anche errors, con un messaggio per ogni problema.
{
"error": false,
"success": true,
"data": { … }
}{
"error": true,
"success": false,
"message": "Dati di fatturazione non validi.",
"errors": [
"indirizzo supera i 60 caratteri (81)."
]
}POST/checkout
Crea un riferimento con i prodotti e i dati di fatturazione. Serve quando il tuo checkout raccoglie già i dati del cliente.
Corpo della richiesta
| Campo | Descrizione |
|---|---|
products | Array, obbligatorio, almeno una riga. Ogni riga è { uuid, qty } per un prodotto del catalogo oppure un prodotto al volo con nome, prezzo_lordo o prezzo_netto, aliquota_iva, qty, codice, descrizione. |
billing | Oggetto, obbligatorio. I dati di fatturazione del cliente: vedi la tabella sotto. |
customer_id | Facoltativo. L'id che il cliente ha sul tuo sito, fino a 255 caratteri. Con GET /invoices?customer_id=… ritrovi poi tutte le sue fatture. Maiuscole e minuscole contano. |
Dati di fatturazione
| Campo | Quando serve |
|---|---|
nome | Sempre. Nome e cognome, oppure ragione sociale. |
cf | Per un privato. Con il codice fiscale FiscoJet tratta il cliente come privato. |
piva | Per un'azienda. |
sdi o pec | Per un'azienda, almeno uno dei due. Con uno di questi campi (e senza cf) FiscoJet tratta il cliente come azienda. |
indirizzo, citta, cap | Sempre. |
provincia | Facoltativa. |
nazione | Facoltativa. Se manca vale IT. |
email | Facoltativa. Finisce nella fattura come email del cliente. |
I controlli sui singoli campi sono in Limiti e controlli. Le regole delle righe al volo sono nella pagina Integrazioni.
curl -X POST https://api.fiscojet.com/checkout \
-H "Authorization: Bearer $FISCOJET_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"products": [
{ "uuid": "prod_e0dd538f1d51", "qty": 1 }
],
"billing": {
"nome": "Giulia Bianchi",
"cf": "RSSMRA80A01H501U",
"indirizzo": "Via Garibaldi 18",
"citta": "Milano",
"cap": "20121",
"email": "giulia@esempio.it"
},
"customer_id": "cliente_8412"
}'Risposte
| Codice | Significato |
|---|---|
| 201 | data.ref contiene il riferimento fj_ref_…. |
| 400 | Richiesta non valida: products vuoto, dati di fatturazione mancanti o non validi, riga al volo sbagliata, più di 50 righe con prodotti al volo. Il motivo è in message e, per i dati di fatturazione, in errors. |
| 401 | Chiave segreta mancante, non valida o revocata. |
| 422 | Prodotti non trovati o non attivi: … seguito dagli uuid del catalogo che non esistono o sono disattivati. |
{
"error": false,
"success": true,
"data": { "ref": "fj_ref_4a3b2c1d9e8f7a6b" }
}POST/checkout/session
Crea un riferimento senza dati di fatturazione e la sessione per il form hosted. Il riferimento lo puoi mettere subito nei metadata del PaymentIntent: FiscoJet lo considera solo dopo che il cliente ha inviato il form.
Corpo della richiesta
products, con le stesse righe di POST /checkout: da 1 a 50. Puoi aggiungere customer_id, come in POST /checkout.
curl -X POST https://api.fiscojet.com/checkout/session \
-H "Authorization: Bearer $FISCOJET_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"products": [
{ "nome": "Corso base", "prezzo_lordo": 122.00, "aliquota_iva": 22, "qty": 1 }
]
}'Campi di data
| Campo | Descrizione |
|---|---|
session | Token fj_cs_… da passare al form come checkoutSession. |
ref | Riferimento fj_ref_… da mettere in metadata.fj_ref del PaymentIntent. |
expires_at | Scadenza della sessione, 24 ore dopo la creazione (ISO 8601). |
items | Righe dell'ordine con nome, qty, prezzo_lordo e aliquota_iva. |
totale | Totale IVA inclusa, in euro. Per l'importo del PaymentIntent moltiplicalo per 100. |
{
"error": false,
"success": true,
"data": {
"session": "fj_cs_…",
"ref": "fj_ref_…",
"expires_at": "2026-10-26T09:30:00.000Z",
"items": [
{ "nome": "Corso base", "qty": 1, "prezzo_lordo": 122, "aliquota_iva": 22 }
],
"totale": 122
}
}Risposte
| Codice | Significato |
|---|---|
| 201 | La sessione è creata: i campi sono nella tabella sopra. |
| 400 | products vuoto, più di 50 righe, oppure una riga non valida. Qui anche le righe del catalogo devono avere qty numerico maggiore di 0. |
| 401 | Chiave segreta mancante, non valida o revocata. |
| 422 | Uno o più prodotti del catalogo non esistono o sono disattivati. |
GET/checkout/:uuid
Restituisce un riferimento del tuo account. Al posto di :uuid metti il fj_ref_…. Se il riferimento non esiste la risposta è 404 con checkout_ref non trovato.
curl https://api.fiscojet.com/checkout/fj_ref_4a3b2c1d9e8f7a6b \
-H "Authorization: Bearer $FISCOJET_SECRET_KEY"| Campo | Descrizione |
|---|---|
uuid_ref | Il riferimento. |
status | Lo stato: vedi Stati del riferimento. |
stripe_payment_id | L'id del PaymentIntent abbinato. Vale null finché FiscoJet non trova il pagamento. |
billing_snapshot | I dati di fatturazione salvati, con il tipo di cliente. |
items_snapshot | Le righe, con product_id, nome, prezzo_netto, aliquota_iva e quantita. |
created_at, updated_at | Creazione e ultimo aggiornamento. |
{
"error": false,
"success": true,
"data": {
"uuid_ref": "fj_ref_4a3b2c1d9e8f7a6b",
"status": "invoiced",
"stripe_payment_id": "pi_…",
"billing_snapshot": { "tipo": "privato", "nome": "Giulia Bianchi", … },
"items_snapshot": [
{
"product_id": "prod_e0dd538f1d51",
"nome": "Corso base",
"prezzo_netto": 100,
"aliquota_iva": 22,
"quantita": 1
}
],
"created_at": "…",
"updated_at": "…"
}
}GET/invoices
Restituisce le fatture del tuo account, dalla più recente. Serve per mostrare a un cliente le sue fatture sul tuo sito: per esempio in una pagina "Le mie fatture" dell'area riservata.
Trovi solo le fatture già partite verso lo SDI. Bozze, fatture in errore e fatture rifiutate restano nella dashboard. Se lo SDI scarta una fattura, questa esce dall'elenco finché non la correggi e la reinvii.
Il cliente lo riconosci tu. FiscoJet restituisce le fatture che il tuo server chiede con la chiave segreta, e non sa chi è il cliente davanti allo schermo.
Prendi customer_id, email o il riferimento dell'ordine dalla sessione del cliente che ha fatto login, oppure dagli ordini che il tuo database associa a lui. Non usare un valore che arriva dal browser, come un parametro nell'indirizzo o un campo di un form: chiunque potrebbe cambiarlo e vedere le fatture di un altro.
Parametri
Tutti facoltativi. Se ne passi più di uno, la fattura deve rispettarli tutti.
| Parametro | Descrizione |
|---|---|
customer_id | Le fatture dei riferimenti creati con questo customer_id. Maiuscole e minuscole contano. |
ref | La fattura dell'ordine con questo riferimento fj_ref_…. |
stripe_payment_id | La fattura del pagamento con questo PaymentIntent pi_…. |
email | Le fatture con questa email del cliente nei dati di fatturazione. È l'email scritta nel modulo di fatturazione e può essere diversa da quella dell'account sul tuo sito. |
tax_code | Le fatture del cliente con questo codice fiscale o questa partita IVA, con o senza IT davanti. |
limit | Quante fatture restituire, da 1 a 100. Se manca sono 20. |
starting_after | L'id dell'ultima fattura ricevuta: la risposta riparte da quella successiva. Serve quando has_more è true. |
curl "https://api.fiscojet.com/invoices?customer_id=cliente_8412" \
-H "Authorization: Bearer $FISCOJET_SECRET_KEY"Campi di ogni fattura
| Campo | Descrizione |
|---|---|
id | L'id della fattura in FiscoJet. Lo usi con GET /invoices/:id e per la paginazione. |
numero | Il numero della fattura, con il tuo modello di numerazione. |
tipo_documento | TD01 per una fattura, TD04 per una nota di credito. Le note di credito hanno la stessa numerazione delle fatture e importi positivi: l'importo è quello stornato. |
fattura_collegata | Solo per le note di credito: numero e data_fattura della fattura stornata. Per le fatture vale null. |
data_fattura | La data della fattura (AAAA-MM-GG). |
stato | Dove si trova la fattura: vedi gli stati qui sotto. |
customer_id | Il customer_id del riferimento. Vale null se non l'hai passato o se hai creato la fattura a mano. |
ref, stripe_payment_id | Il riferimento fj_ref_… e il PaymentIntent da cui nasce la fattura. Null per le fatture create a mano. |
cliente | I dati di fatturazione del cliente, con gli stessi nomi di billing e il tipo (privato o azienda). |
descrizione | La descrizione della riga in fattura. |
importo_netto, aliquota_iva, importo_iva, importo_totale | Gli importi in euro. valuta vale sempre EUR. |
pdf_url, pdf_url_expires_at | Il link al PDF della fattura e la sua scadenza, un'ora dopo la risposta. Vedi Link per scaricare il PDF. |
{
"error": false,
"success": true,
"data": [
{
"id": 142,
"numero": "FJ-2026-0142",
"tipo_documento": "TD01",
"fattura_collegata": null,
"data_fattura": "2026-10-20",
"stato": "consegnata",
"customer_id": "cliente_8412",
"ref": "fj_ref_4a3b2c1d9e8f7a6b",
"stripe_payment_id": "pi_…",
"cliente": {
"tipo": "privato",
"nome": "Giulia Bianchi",
"piva": null,
"cf": "RSSMRA80A01H501U",
"email": "giulia@esempio.it",
"indirizzo": "Via Garibaldi 18",
"citta": "Milano",
"cap": "20121",
"provincia": null,
"nazione": "IT"
},
"descrizione": "Corso base",
"importo_netto": 100,
"aliquota_iva": 22,
"importo_iva": 22,
"importo_totale": 122,
"valuta": "EUR",
"pdf_url": "https://api.fiscojet.com/public/invoices/142/pdf?expires=…&signature=…",
"pdf_url_expires_at": "2026-10-26T10:30:00.000Z"
}
],
"has_more": false
}Stati della fattura
| stato | Significato |
|---|---|
in_elaborazione | La fattura è partita verso lo SDI, che non ha ancora risposto. |
inviata | Lo SDI ha ricevuto la fattura. Manca l'esito della consegna al cliente. |
consegnata | La fattura è arrivata al cliente oppure è nella sua area riservata dell'Agenzia delle Entrate. |
Risposte
| Codice | Significato |
|---|---|
| 200 | Le fatture sono in data, dalla più recente. has_more dice se ce ne sono altre. |
| 400 | Un parametro non è valido, oppure compare due volte. Il motivo è in message. |
| 401 | Chiave segreta mancante, non valida o revocata. |
GET/invoices/:id
Restituisce una fattura con gli stessi campi di GET /invoices. Se la fattura non esiste, è di un altro account o non è ancora partita verso lo SDI, la risposta è 404 con Fattura non trovata.
curl https://api.fiscojet.com/invoices/142 \
-H "Authorization: Bearer $FISCOJET_SECRET_KEY"GET/invoices/:id/pdf
Restituisce il PDF della fattura, da salvare o da inoltrare dal tuo server. È una copia di cortesia, senza valore fiscale: riporta gli stessi dati della fattura elettronica inviata allo SDI.
curl https://api.fiscojet.com/invoices/142/pdf \
-H "Authorization: Bearer $FISCOJET_SECRET_KEY" \
-o fattura.pdfPer far scaricare il PDF al cliente dal browser non ti serve questo endpoint: usa pdf_url.
Link per scaricare il PDF
Ogni fattura di GET /invoices e GET /invoices/:id ha un pdf_url. Il link si apre senza chiave, quindi puoi metterlo così com'è nel pulsante "Scarica" della tua pagina. La chiave segreta resta sul tuo server.
Il link vale un'ora. Dopo risponde 410 e chiede al cliente di tornare sul tuo sito: a ogni apertura della pagina chiedi di nuovo le fatture e avrai link nuovi. Un link con la firma modificata risponde 404.
Finché non scade, chi ha il link apre il PDF anche senza login sul tuo sito, per esempio se il cliente lo inoltra. Se vuoi che il download resti dietro il login, crea sul tuo sito una rotta che controlla la sessione e restituisce il PDF di GET /invoices/:id/pdf.
// Pagina "Le mie fatture" del tuo sito (Node.js, lato server).
// utente è il cliente della sessione, dopo il login: mai un valore che arriva dal browser.
const res = await fetch(
"https://api.fiscojet.com/invoices?customer_id=" + encodeURIComponent(utente.id),
{ headers: { Authorization: "Bearer " + process.env.FISCOJET_SECRET_KEY } }
);
const { data } = await res.json();
// Nella pagina: un link per fattura, con pdf_url così com'è
// <a href={fattura.pdf_url}>Scarica la fattura {fattura.numero}</a>Stati del riferimento
Il campo status di GET /checkout/:uuid. Un riferimento creato con POST /checkout parte da pending.
| status | Significato |
|---|---|
awaiting_billing | Creato con POST /checkout/session. Il cliente non ha ancora inviato i dati dal form, quindi FiscoJet non lo considera. |
pending | Ha i dati di fatturazione. FiscoJet cerca ogni minuto su Stripe un PaymentIntent riuscito con questo fj_ref. |
scheduled | Pagamento trovato. La fattura parte all'orario che deriva dal ritardo impostato nelle Regole. |
invoiced | Fattura creata: inviata allo SDI oppure in bozza, se nelle Regole hai scelto di approvarla tu. |
cancelled | Il pagamento è stato rimborsato prima della fattura. FiscoJet non la emette. |
Lo stato della fattura dopo l'invio allo SDI lo vedi nella dashboard e nel campo stato di GET /invoices.
Errori del form hosted
Il form passa a onError un oggetto con code, message e, per gli errori di validazione, messages. Con lo stesso oggetto rifiuta la Promise di submit(). I valori di code:
| code | Quando succede |
|---|---|
config_error | Opzioni di FiscoJet.mount sbagliate: per esempio manca la chiave o la sessione, il selettore non esiste, oppure hai passato products. |
invalid_key | Chiave pubblica mancante o non valida. |
domain_not_allowed | La pagina non è sul dominio impostato per la chiave nella pagina Sviluppatore. |
session_not_found | La sessione non esiste o appartiene a un altro account. |
session_expired | Sono passate 24 ore: crea una nuova sessione. |
already_completed | I dati di fatturazione di questo ordine sono già stati acquisiti e l'ordine è andato avanti. |
validation_error | Il server ha rifiutato i dati. error.messages elenca i problemi. |
invalid_input | Il form ha trovato dati non validi prima di inviarli. error.messages elenca i problemi. |
rate_limited | Troppe richieste dallo stesso indirizzo: riprova tra un minuto. |
service_unavailable | Il servizio non è disponibile in questo momento. |
network_error | Il server non si raggiunge, oppure non ha risposto entro 20 secondi. |
server_error | Risposta inattesa dal server. |
session_changed | La sessione è cambiata con update() mentre il form inviava i dati. |
unmounted | Il form è stato smontato con unmount(). |
Limiti e controlli
POST /checkout/sessionaccetta al massimo 50 righe.POST /checkoutha lo stesso limite quando la richiesta contiene prodotti al volo.- Una sessione del form hosted scade 24 ore dopo la creazione.
- Dal form arrivano al massimo 30 invii al minuto per indirizzo IP.
GET /invoicesrestituisce al massimo 100 fatture per chiamata.- I link
pdf_urlvalgono un'ora e si aprono al massimo 60 volte al minuto per indirizzo IP.
Prima di salvare i dati di fatturazione FiscoJet li controlla con le regole del formato FatturaPA. Gli stessi controlli li fa il form hosted nel browser.
| Campo | Controllo |
|---|---|
nome | Obbligatorio, fino a 80 caratteri. |
cf | 16 caratteri nel formato del codice fiscale di una persona, oppure 11 cifre. |
piva | Partita IVA italiana: 11 cifre, con o senza IT davanti, e cifra di controllo corretta. |
sdi | 7 caratteri, lettere o cifre. 0000000 è accettato. |
pec | Indirizzo email valido, fino a 256 caratteri. |
indirizzo | Fino a 60 caratteri. |
citta | Fino a 60 caratteri. |
cap | Esattamente 5 cifre se la nazione è IT. Per l'estero fino a 20 caratteri. |
provincia | Sigla di 2 lettere, per esempio MI. |
nazione | Codice di 2 lettere (ISO 3166-1), per esempio IT o DE. |
email | Indirizzo email valido, fino a 255 caratteri. |