FiscoJet

Integrazioni · API

Collegare FiscoJet dal tuo server

Per un checkout che costruisci tu e che raccoglie già i dati di fatturazione. Il tuo server li manda a FiscoJet con i prodotti e riceve un riferimento, il fj_ref, da mettere nei metadata del PaymentIntent Stripe. Qui trovi le chiamate e il codice da copiare.

Gli altri modi

Form hosted

Non vuoi costruire i campi di fatturazione?

Il form di FiscoJet li raccoglie e li controlla nella tua pagina, prima del pagamento.

WordPress e WooCommerce

Vendi con WooCommerce?

Il plugin fa tutto senza codice, con ogni metodo di pagamento.

Chiavi e indirizzo dell'API

Le generi nella pagina Sviluppatore della dashboard.

Le due chiavi di FiscoJet
ChiaveFormatoDove si usa
Segretafj_live_sk_…Solo sul tuo server, nell'header Authorization: Bearer. Serve per POST /checkout, POST /checkout/session e GET /checkout/:uuid. Non deve mai arrivare al browser.
Pubblicafj_pk_live_…Nella pagina, nell'opzione publishableKey del form hosted. Può stare nel codice che arriva al browser.
  • La chiave segreta la vedi una volta sola, quando la generi. Se ne generi un'altra, la precedente smette di funzionare.
  • Anche la chiave pubblica, se la rigeneri, sostituisce quella vecchia.
  • Se nella pagina Sviluppatore indichi il dominio del tuo sito, la chiave pubblica funziona solo da https://tuosito.it e https://www.tuosito.it. Senza dominio funziona da qualsiasi sito.
Indirizzo dell'API e header delle chiamate dal server
https://api.fiscojet.com

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

Dal tuo server

Per un checkout che costruisci tu e che raccoglie già i dati di fatturazione. I due passi sono entrambi sul server.

1. Crea il riferimento

Chiama POST /checkout con i prodotti dell'ordine e i dati di fatturazione del cliente. La risposta contiene il fj_ref.

Richiesta · 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": "Rossi S.r.l.",
      "piva": "12345678903",
      "sdi": "ABC1234",
      "indirizzo": "Via Roma 1",
      "citta": "Milano",
      "cap": "20121",
      "provincia": "MI"
    }
  }'
Risposta · 201
{
  "error": false,
  "success": true,
  "data": {
    "ref": "fj_ref_4a3b2c1d9e8f7a6b"
  }
}

I dati di fatturazione che servono:

  • privato: nome e cf (codice fiscale);
  • azienda: nome, piva e uno tra sdi (codice destinatario di 7 caratteri) e pec;
  • sempre: indirizzo, citta e cap. Sono facoltativi provincia, nazione (se manca vale IT) ed email.

FiscoJet capisce il tipo di cliente dai campi: con cf è un privato, con sdi o pec è un'azienda. Controlla anche formati e lunghezze del formato FatturaPA: per esempio l'indirizzo può avere al massimo 60 caratteri e la partita IVA deve avere la cifra di controllo giusta. L'elenco completo è nel riferimento API.

2. Metti il riferimento nel PaymentIntent

Crea il PaymentIntent sull'account Stripe collegato a FiscoJet e scrivi il riferimento nei metadata, con la chiave fj_ref esattamente così.

Il tuo server · Node.js
const paymentIntent = await stripe.paymentIntents.create({
  amount: 12200,
  currency: 'eur',
  metadata: { fj_ref: 'fj_ref_4a3b2c1d9e8f7a6b' }
});

Con Stripe Checkout i metadata della sessione non arrivano al PaymentIntent. Mettili in payment_intent_data:

Con Stripe Checkout · Node.js
const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [/* … */],
  payment_intent_data: {
    metadata: { fj_ref: 'fj_ref_4a3b2c1d9e8f7a6b' }
  },
  success_url: 'https://tuosito.it/grazie'
});

Prodotti al volo

Valgono per POST /checkout e per POST /checkout/session.

Ogni riga di products può indicare un prodotto del tuo catalogo FiscoJet con uuid e qty. Puoi anche descriverlo nella richiesta, senza crearlo prima nella dashboard.

Esempio di products
products: [
  // Dal tuo catalogo FiscoJet
  { uuid: 'prod_e0dd538f1d51', qty: 1 },

  // Al volo: prezzo IVA inclusa (oppure prezzo_netto)
  {
    nome: 'Corso base',
    prezzo_lordo: 122.00,
    aliquota_iva: 22,
    qty: 1,
    codice: 'CORSO-01'
  }
]
Campi di una riga al volo
CampoRegola
nomeObbligatorio, fino a 255 caratteri.
prezzo_lordo o prezzo_nettoUno dei due, maggiore di 0. Il lordo è IVA inclusa.
aliquota_ivaDa 0 a 100. Se manca vale 22.
qtyMaggiore di 0.
codiceFacoltativo, fino a 100 caratteri.
descrizioneFacoltativa, fino a 1000 caratteri.

Se nel catalogo c'è già un prodotto attivo con lo stesso nome, prezzo lordo, aliquota e codice, FiscoJet usa quello. Altrimenti ne crea uno nuovo. I prodotti che esistono già non vengono mai modificati. Con prodotti al volo puoi mandare al massimo 50 righe.

Dopo il pagamento

Uguale per le API e per il form hosted.

Ogni minuto FiscoJet cerca su Stripe i PaymentIntent riusciti che hanno nei metadata un fj_ref in attesa. Quando ne trova uno, la fattura segue le tue Regole: parte subito, parte dopo il ritardo che hai scelto, oppure resta in bozza finché non la approvi. Se il pagamento è stato rimborsato prima, la fattura non viene emessa.

La fattura ha una sola riga. La descrizione mette insieme i nomi dei prodotti, per esempio Corso base x2, Manuale. Se il cliente ha usato uno sconto Stripe, l'importo è quello incassato e la descrizione riporta lo sconto.

FiscoJet non manda webhook al tuo server. Per sapere a che punto è un ordine chiama GET /checkout/:uuid con il fj_ref. Il campo status vale:

Stati di un riferimento
statusSignificato
awaiting_billingSessione del form hosted creata. Il cliente non ha ancora inviato i dati di fatturazione.
pendingI dati di fatturazione ci sono. FiscoJet aspetta il pagamento riuscito su Stripe.
scheduledPagamento trovato. La fattura parte all'orario che deriva dalle tue Regole.
invoicedFattura creata.
cancelledIl pagamento è stato rimborsato prima della fattura. Nessuna fattura.
Stato di un riferimento · cURL
curl https://api.fiscojet.com/checkout/fj_ref_4a3b2c1d9e8f7a6b \
  -H "Authorization: Bearer $FISCOJET_SECRET_KEY"