API Generazione Fattura AI

Genera fatture elettroniche FatturaPA v1.2.3 conformi a partire da una descrizione in linguaggio naturale. L'AI analizza il testo, identifica i dati e produce XML valido per il Sistema di Interscambio.

Panoramica

L'API di Generazione Fattura AI accetta una descrizione testuale del lavoro svolto, i dati del cedente (chi emette la fattura) e, opzionalmente, i dati del cessionario (cliente). L'intelligenza artificiale analizza il testo e genera un file XML FatturaPA v1.2.3 completo e validato.

Base URLhttps://api.fattureai.it/v1
Sandbox URLhttps://sandbox.api.fattureai.it/v1
FormatoJSON (request e response)
EncodingUTF-8
Versionev1 (stabile)

Autenticazione

Tutte le richieste devono includere la tua API key nell'header X-API-Key.

X-API-Key: fa_live_xxxxxxxxxxxxxxxx

Le API key si generano dalla dashboard. Esistono due tipi:

  • fa_live_* — Produzione, genera fatture valide fiscalmente
  • fa_test_* — Sandbox, genera fatture di esempio (non consuma crediti)

Importante: non condividere mai la tua API key. Non includerla nel codice frontend o in repository pubblici. Usa variabili d'ambiente lato server.

POST /v1/genera

Genera una fattura elettronica XML a partire da testo in linguaggio naturale.

Request body

CampoTipoObbligatorioDescrizione
testostringSiDescrizione del lavoro svolto, importi, dati del cliente. In italiano.
cedenteobjectSi Dati di chi emette la fattura.
cedente.denominazionestringSiNome o ragione sociale del cedente.
cedente.partita_ivastringSiPartita IVA (11 cifre).
cedente.codice_fiscalestringNoCodice fiscale se diverso dalla P.IVA.
cedente.regime_fiscalestringSiCodice regime: RF01 (ordinario), RF19 (forfettario), ecc.
cedente.indirizzostringNoIndirizzo completo (via, civico, CAP, citta, provincia).
cessionarioobjectNo Dati del cliente. Se omesso, l'AI li estrae dal testo.
cessionario.denominazionestringNoNome o ragione sociale del cliente.
cessionario.partita_ivastringNoPartita IVA del cliente.
cessionario.codice_fiscalestringNoCodice fiscale del cliente.
cessionario.codice_destinatariostringNoCodice SdI a 7 caratteri. Default: 0000000.
cessionario.pecstringNoPEC del cliente (alternativa al codice destinatario).
opzioniobjectNoOpzioni avanzate di generazione.
opzioni.tipo_documentostringNoForza il tipo documento (TD01, TD04, ecc.). Default: auto.
opzioni.divisastringNoCodice valuta ISO 4217. Default: EUR.
opzioni.progressivostringNoNumero progressivo fattura. Default: auto.
opzioni.datastringNoData fattura (YYYY-MM-DD). Default: oggi.
opzioni.validazionebooleanNoValida XML contro schema XSD. Default: true.

Esempio richiesta

POST /v1/genera HTTP/1.1
Host: api.fattureai.it
X-API-Key: fa_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "testo": "Ho svolto consulenza informatica per 10 ore a 50 euro l'ora per la ditta Rossi Srl, P.IVA 01234567890, codice destinatario ABCDEFG, via Verdi 5, 20100 Milano MI",
  "cedente": {
    "denominazione": "Mario Bianchi",
    "partita_iva": "09876543210",
    "codice_fiscale": "BNCMRA85A01F205Z",
    "regime_fiscale": "RF19",
    "indirizzo": "Via Garibaldi 10, 00100 Roma RM"
  },
  "opzioni": {
    "validazione": true
  }
}

Esempio risposta (200 OK)

{
  "success": true,
  "fattura": {
    "id": "fat_abc123def456",
    "tipo_documento": "TD01",
    "numero": "1",
    "data": "2026-03-09",
    "importo_totale": 500.00,
    "imponibile": 500.00,
    "iva": 0.00,
    "natura_iva": "N2.1",
    "bollo_virtuale": true,
    "regime_fiscale": "RF19"
  },
  "xml": "PD94bWwgdmVyc2lvbj0i...base64...encoded==",
  "validazione": {
    "valido": true,
    "errori": [],
    "warning": []
  },
  "crediti_residui": 42
}

Campi della risposta

CampoTipoDescrizione
successbooleanEsito della richiesta.
fatturaobjectRiepilogo della fattura generata.
fattura.idstringID univoco fattura nel sistema FattureAI.
fattura.tipo_documentostringTipo documento rilevato (TD01, TD04, ecc.).
fattura.importo_totalenumberImporto totale della fattura in EUR.
xmlstringXML FatturaPA completo, codificato in Base64.
validazioneobjectRisultato della validazione XSD.
crediti_residuiintegerCrediti rimanenti nel tuo piano.

Codici di Errore

L'API restituisce errori in formato JSON con il codice HTTP appropriato.

{
  "success": false,
  "error": {
    "code": "INVALID_PARTITA_IVA",
    "message": "La partita IVA del cedente non e' valida: deve essere di 11 cifre.",
    "field": "cedente.partita_iva"
  }
}
HTTPCodiceDescrizione
400INVALID_REQUESTRichiesta malformata o campi mancanti.
400INVALID_PARTITA_IVAPartita IVA non valida (check digit errato).
400INVALID_CODICE_FISCALECodice fiscale non valido.
400TESTO_TROPPO_CORTOLa descrizione deve avere almeno 20 caratteri.
400TESTO_TROPPO_LUNGOLa descrizione non può superare 5.000 caratteri.
401UNAUTHORIZEDAPI key mancante o non valida.
403FORBIDDENAPI key non ha i permessi per questa operazione.
422AI_PARSE_ERRORL'AI non è riuscita a interpretare il testo. Fornisci più dettagli.
422VALIDATION_FAILEDL'XML generato non ha superato la validazione XSD.
429RATE_LIMITHai superato il limite di richieste al minuto.
429CREDITI_ESAURITICrediti esauriti. Acquista crediti o fai upgrade.
500INTERNAL_ERRORErrore interno del server. Riprova tra qualche secondo.
503SERVICE_UNAVAILABLEServizio temporaneamente non disponibile (manutenzione).

Rate Limits

I rate limit sono applicati per API key e variano in base al piano:

PianoRichieste / minutoRichieste / giorno
Free1050
Starter605.000
Pro12020.000
EnterprisePersonalizzatoPersonalizzato

Gli header della risposta includono informazioni sul rate limit:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709913600

Esempi di Codice

cURL

curl -X POST https://api.fattureai.it/v1/genera \
  -H "X-API-Key: fa_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "testo": "Sviluppo sito web per Bianchi Srl, P.IVA 12345678901, via Dante 3, Firenze. Importo 1500 euro + IVA 22%",
    "cedente": {
      "denominazione": "Studio Rossi",
      "partita_iva": "09876543210",
      "regime_fiscale": "RF01"
    }
  }'

PHP

<?php
$apiKey = getenv('FATTURAAI_API_KEY');

$payload = [
    'testo' => 'Sviluppo sito web per Bianchi Srl, P.IVA 12345678901, via Dante 3, Firenze. Importo 1500 euro + IVA 22%',
    'cedente' => [
        'denominazione'  => 'Studio Rossi',
        'partita_iva'    => '09876543210',
        'regime_fiscale' => 'RF01',
    ],
];

$ch = curl_init('https://api.fattureai.it/v1/genera');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    file_put_contents('fattura.xml', base64_decode($data['xml']));
    echo "Fattura generata: " . $data['fattura']['id'] . "\n";
} else {
    $error = json_decode($response, true);
    echo "Errore: " . $error['error']['message'] . "\n";
}

Python

import os
import requests
import base64

api_key = os.environ["FATTURAAI_API_KEY"]

response = requests.post(
    "https://api.fattureai.it/v1/genera",
    headers={
        "X-API-Key": api_key,
        "Content-Type": "application/json",
    },
    json={
        "testo": "Sviluppo sito web per Bianchi Srl, P.IVA 12345678901, via Dante 3, Firenze. Importo 1500 euro + IVA 22%",
        "cedente": {
            "denominazione": "Studio Rossi",
            "partita_iva": "09876543210",
            "regime_fiscale": "RF01",
        },
    },
)

if response.status_code == 200:
    data = response.json()
    xml = base64.b64decode(data["xml"])
    with open("fattura.xml", "wb") as f:
        f.write(xml)
    print(f"Fattura generata: {data['fattura']['id']}")
else:
    error = response.json()
    print(f"Errore: {error['error']['message']}")

Node.js

import { writeFile } from "fs/promises";

const apiKey = process.env.FATTURAAI_API_KEY;

const response = await fetch("https://api.fattureai.it/v1/genera", {
  method: "POST",
  headers: {
    "X-API-Key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    testo: "Sviluppo sito web per Bianchi Srl, P.IVA 12345678901, via Dante 3, Firenze. Importo 1500 euro + IVA 22%",
    cedente: {
      denominazione: "Studio Rossi",
      partita_iva: "09876543210",
      regime_fiscale: "RF01",
    },
  }),
});

const data = await response.json();

if (response.ok) {
  const xml = Buffer.from(data.xml, "base64");
  await writeFile("fattura.xml", xml);
  console.log(`Fattura generata: ${data.fattura.id}`);
} else {
  console.error(`Errore: ${data.error.message}`);
}

Best Practices

  • Fornisci più dettagli possibile nel campo testo: importo, IVA, dati del cliente, descrizione del servizio. Più il testo è dettagliato, più la fattura sarà precisa.
  • Usa l'oggetto cessionario per fornire i dati strutturati del cliente quando li hai già, in modo che l'AI non debba estrarli dal testo.
  • Valida sempre la risposta: controlla il campo validazione.valido e i warning.
  • Gestisci i retry: in caso di errore 500 o 503, attendi 2-5 secondi e riprova (max 3 tentativi).
  • Usa l'ambiente sandbox (fa_test_*) durante lo sviluppo per non consumare crediti.
  • Conserva la API key lato server: usa variabili d'ambiente, mai nel codice frontend.

Pronto a Generare Fatture via API?

Registrati gratis e ricevi subito i tuoi crediti per iniziare.

Ottieni la API Key API Template PDF