Ambienti ed errori

Base URL, formato degli errori HTTP e limiti delle API.

Scegliere l’ambiente#

Ambiente	Indirizzo REST
Sandbox	`https://api.sandbox.fttel.com`
Produzione	`https://api.fttel.com`
Sviluppo locale	`http://localhost:3000` per impostazione predefinita; la porta può essere configurata.

Questi sono gli indirizzi previsti dalla configurazione del progetto: verifica con il gestore quale versione è distribuita e che le credenziali appartengano all’ambiente scelto. Il riferimento è disponibile in /docs, il JSON in /docs-json e questa guida in /docs/guida/.

Gestire gli errori HTTP#

json

{
  "statusCode": 400,
  "message": ["xmlBase64 must be base64 encoded"],
  "error": "Bad Request"
}

message può essere una stringa o un array. Non è previsto un campo applicativo stabile code: distingui prima il codice HTTP e il contesto dell’operazione, senza basarti su un confronto letterale del messaggio.

HTTP	Azione del client
`400`	Correggi campi e filtri. I campi JSON non previsti vengono rifiutati.
`401`	Controlla chiave, account attivo e ambiente. Sospendi le ripetizioni con la stessa credenziale.
`403`	Controlla titolarità fiscale, accesso al documento o tentativo di cancellare una fattura non importata.
`404`	Verifica id e account. Una fattura di un altro account non è accessibile con la tua chiave.
`409`	Verifica l’operazione: può essere un conflitto anagrafico o l’allocazione del nome SdI. Non equivale a una deduplica del POST.
`413`	Riduci la richiesta o suddividi l’archivio; considera anche i limiti del proxy.
`422`	Controlla parsing XML, data documento, estrazione CAdES e firma. Il record può già esistere: riconcilia prima di un nuovo invio.
`5xx` o timeout	Per le letture usa ritardi crescenti con jitter e un numero massimo di tentativi. Per l’invio verifica prima l’esito persistito.

Limiti e comportamento del servizio#

Liste macchina: 50 elementi predefiniti, massimo 500; payload Base64 inclusi nelle risposte.
Importazioni: un archivio ZIP fino a 50 MiB e 400 file fattura. Controlla gli esiti parziali.
Il parsing JSON usa attualmente il limite predefinito dell’adattatore Express, circa 100 KiB. Base64 aumenta il volume di circa un terzo: non estendere il limite ZIP ai POST JSON. Verifica i limiti effettivi dell’ambiente e del proxy con il gestore.
Non è definita una quota pubblica di richieste al minuto nelle API. Limita la concorrenza e, se l’infrastruttura restituisce 429, rispetta Retry-After quando presente.
Non sono disponibili idempotenza dell’invio, firma dei webhook, replay degli eventi o retry automatici di consegna.
Non è previsto un filtro per ultima modifica delle fatture. Le finestre di data non sostituiscono il recupero dello stato delle fatture note.
Una chiave appartiene a una sola azienda. Le operazioni trasversali del provider richiedono un’autenticazione separata e non fanno parte del normale flusso macchina.