FiscoJet

Per chi sviluppa il sito

Riferimento API

Endpoint, parametri, risposte ed errori dell'API di FiscoJet. Se cerchi i passi da seguire con il codice da copiare, parti dalla pagina Integrazioni.

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 con POST /checkout o con POST /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.

Indirizzo e header
https://api.fiscojet.com

Authorization: Bearer fj_live_sk_…
Content-Type: application/json

Se la chiave non va, la risposta è 401 con uno di questi messaggi:

Errori di autenticazione
Casomessage
Manca l'headerAPI key mancante (Authorization: Bearer <key>).
Chiave sconosciutaAPI key non valida.
Chiave sostituitaAPI 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.

Chiamata riuscita
{
  "error": false,
  "success": true,
  "data": { … }
}
Chiamata rifiutata · 400
{
  "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

Corpo di POST /checkout
CampoDescrizione
productsArray, 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.
billingOggetto, obbligatorio. I dati di fatturazione del cliente: vedi la tabella sotto.
customer_idFacoltativo. 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

Campi di billing
CampoQuando serve
nomeSempre. Nome e cognome, oppure ragione sociale.
cfPer un privato. Con il codice fiscale FiscoJet tratta il cliente come privato.
pivaPer un'azienda.
sdi o pecPer un'azienda, almeno uno dei due. Con uno di questi campi (e senza cf) FiscoJet tratta il cliente come azienda.
indirizzo, citta, capSempre.
provinciaFacoltativa.
nazioneFacoltativa. Se manca vale IT.
emailFacoltativa. 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.

Esempio con un cliente privato · cURL
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

Risposte di POST /checkout
CodiceSignificato
201data.ref contiene il riferimento fj_ref_….
400Richiesta 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.
401Chiave segreta mancante, non valida o revocata.
422Prodotti non trovati o non attivi: … seguito dagli uuid del catalogo che non esistono o sono disattivati.
Risposta · 201
{
  "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.

Esempio · cURL
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

Campi della risposta di POST /checkout/session
CampoDescrizione
sessionToken fj_cs_… da passare al form come checkoutSession.
refRiferimento fj_ref_… da mettere in metadata.fj_ref del PaymentIntent.
expires_atScadenza della sessione, 24 ore dopo la creazione (ISO 8601).
itemsRighe dell'ordine con nome, qty, prezzo_lordo e aliquota_iva.
totaleTotale IVA inclusa, in euro. Per l'importo del PaymentIntent moltiplicalo per 100.
Risposta · 201
{
  "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

Risposte di POST /checkout/session
CodiceSignificato
201La sessione è creata: i campi sono nella tabella sopra.
400products vuoto, più di 50 righe, oppure una riga non valida. Qui anche le righe del catalogo devono avere qty numerico maggiore di 0.
401Chiave segreta mancante, non valida o revocata.
422Uno 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.

Esempio · cURL
curl https://api.fiscojet.com/checkout/fj_ref_4a3b2c1d9e8f7a6b \
  -H "Authorization: Bearer $FISCOJET_SECRET_KEY"
Campi della risposta di GET /checkout/:uuid
CampoDescrizione
uuid_refIl riferimento.
statusLo stato: vedi Stati del riferimento.
stripe_payment_idL'id del PaymentIntent abbinato. Vale null finché FiscoJet non trova il pagamento.
billing_snapshotI dati di fatturazione salvati, con il tipo di cliente.
items_snapshotLe righe, con product_id, nome, prezzo_netto, aliquota_iva e quantita.
created_at, updated_atCreazione e ultimo aggiornamento.
Risposta · 200
{
  "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.

Parametri di GET /invoices
ParametroDescrizione
customer_idLe fatture dei riferimenti creati con questo customer_id. Maiuscole e minuscole contano.
refLa fattura dell'ordine con questo riferimento fj_ref_….
stripe_payment_idLa fattura del pagamento con questo PaymentIntent pi_….
emailLe 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_codeLe fatture del cliente con questo codice fiscale o questa partita IVA, con o senza IT davanti.
limitQuante fatture restituire, da 1 a 100. Se manca sono 20.
starting_afterL'id dell'ultima fattura ricevuta: la risposta riparte da quella successiva. Serve quando has_more è true.
Esempio · cURL
curl "https://api.fiscojet.com/invoices?customer_id=cliente_8412" \
  -H "Authorization: Bearer $FISCOJET_SECRET_KEY"

Campi di ogni fattura

Campi di una fattura
CampoDescrizione
idL'id della fattura in FiscoJet. Lo usi con GET /invoices/:id e per la paginazione.
numeroIl numero della fattura, con il tuo modello di numerazione.
tipo_documentoTD01 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_collegataSolo per le note di credito: numero e data_fattura della fattura stornata. Per le fatture vale null.
data_fatturaLa data della fattura (AAAA-MM-GG).
statoDove si trova la fattura: vedi gli stati qui sotto.
customer_idIl customer_id del riferimento. Vale null se non l'hai passato o se hai creato la fattura a mano.
ref, stripe_payment_idIl riferimento fj_ref_… e il PaymentIntent da cui nasce la fattura. Null per le fatture create a mano.
clienteI dati di fatturazione del cliente, con gli stessi nomi di billing e il tipo (privato o azienda).
descrizioneLa descrizione della riga in fattura.
importo_netto, aliquota_iva, importo_iva, importo_totaleGli importi in euro. valuta vale sempre EUR.
pdf_url, pdf_url_expires_atIl link al PDF della fattura e la sua scadenza, un'ora dopo la risposta. Vedi Link per scaricare il PDF.
Risposta · 200
{
  "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

Valori di stato
statoSignificato
in_elaborazioneLa fattura è partita verso lo SDI, che non ha ancora risposto.
inviataLo SDI ha ricevuto la fattura. Manca l'esito della consegna al cliente.
consegnataLa fattura è arrivata al cliente oppure è nella sua area riservata dell'Agenzia delle Entrate.

Risposte

Risposte di GET /invoices
CodiceSignificato
200Le fatture sono in data, dalla più recente. has_more dice se ce ne sono altre.
400Un parametro non è valido, oppure compare due volte. Il motivo è in message.
401Chiave 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.

Esempio · cURL
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.

Esempio · cURL
curl https://api.fiscojet.com/invoices/142/pdf \
  -H "Authorization: Bearer $FISCOJET_SECRET_KEY" \
  -o fattura.pdf

Per 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.

Esempio · Node.js
// 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.

Valori di status
statusSignificato
awaiting_billingCreato con POST /checkout/session. Il cliente non ha ancora inviato i dati dal form, quindi FiscoJet non lo considera.
pendingHa i dati di fatturazione. FiscoJet cerca ogni minuto su Stripe un PaymentIntent riuscito con questo fj_ref.
scheduledPagamento trovato. La fattura parte all'orario che deriva dal ritardo impostato nelle Regole.
invoicedFattura creata: inviata allo SDI oppure in bozza, se nelle Regole hai scelto di approvarla tu.
cancelledIl 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:

Valori di error.code
codeQuando succede
config_errorOpzioni di FiscoJet.mount sbagliate: per esempio manca la chiave o la sessione, il selettore non esiste, oppure hai passato products.
invalid_keyChiave pubblica mancante o non valida.
domain_not_allowedLa pagina non è sul dominio impostato per la chiave nella pagina Sviluppatore.
session_not_foundLa sessione non esiste o appartiene a un altro account.
session_expiredSono passate 24 ore: crea una nuova sessione.
already_completedI dati di fatturazione di questo ordine sono già stati acquisiti e l'ordine è andato avanti.
validation_errorIl server ha rifiutato i dati. error.messages elenca i problemi.
invalid_inputIl form ha trovato dati non validi prima di inviarli. error.messages elenca i problemi.
rate_limitedTroppe richieste dallo stesso indirizzo: riprova tra un minuto.
service_unavailableIl servizio non è disponibile in questo momento.
network_errorIl server non si raggiunge, oppure non ha risposto entro 20 secondi.
server_errorRisposta inattesa dal server.
session_changedLa sessione è cambiata con update() mentre il form inviava i dati.
unmountedIl form è stato smontato con unmount().

Limiti e controlli

  • POST /checkout/session accetta al massimo 50 righe. POST /checkout ha 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 /invoices restituisce al massimo 100 fatture per chiamata.
  • I link pdf_url valgono 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.

Controlli sui dati di fatturazione
CampoControllo
nomeObbligatorio, fino a 80 caratteri.
cf16 caratteri nel formato del codice fiscale di una persona, oppure 11 cifre.
pivaPartita IVA italiana: 11 cifre, con o senza IT davanti, e cifra di controllo corretta.
sdi7 caratteri, lettere o cifre. 0000000 è accettato.
pecIndirizzo email valido, fino a 256 caratteri.
indirizzoFino a 60 caratteri.
cittaFino a 60 caratteri.
capEsattamente 5 cifre se la nazione è IT. Per l'estero fino a 20 caratteri.
provinciaSigla di 2 lettere, per esempio MI.
nazioneCodice di 2 lettere (ISO 3166-1), per esempio IT o DE.
emailIndirizzo email valido, fino a 255 caratteri.