NewEra SDI API

1. Come funziona

MORLAPPO è un soggetto trasmittente collegato al Sistema di Interscambio (SDI) dell'Agenzia delle Entrate con un canale web service diretto. Il vostro software usa questo canale per conto delle aziende che gestite (per esempio le scuole): voi ci mandate le fatture, noi le controlliamo, le trasmettiamo, seguiamo gli esiti e vi avvisiamo. Le fatture dei fornitori indirizzate a quelle aziende arrivano a noi e le rendiamo disponibili a voi.

Il modo più semplice è mandare la fattura come dati JSON: imponibili, IVA, riepiloghi, totale, bollo, ritenuta e l'XML FatturaPA li calcoliamo noi, quindi il vostro software non deve conoscere il formato XML. Se lo genera già, potete mandare l'XML pronto.

Ogni fattura passa i nostri controlli prima di arrivare allo SDI (schema ufficiale, coerenza dei dati). Se non li passa vi rispondiamo subito con l'elenco degli errori e la fattura non parte: così si evitano la maggior parte degli scarti.

2. Prima di iniziare

Cosa vi consegniamo

• Chiave API di prova (nea_test_…): si vede una volta sola, conservatela in un archivio segreto lato server.
• Segreto degli avvisi: serve a verificare che gli avvisi automatici vengano davvero da noi.
• A collaudo superato, chiave di produzione (nea_live_…) con il suo segreto.
• Il codice destinatario del canale, che le aziende registrano per ricevere le fatture dei fornitori (vedi Fatture ricevute).

Cosa ci serve da voi

• L'indirizzo HTTPS a cui spedire gli avvisi automatici (uno per la prova e uno per la produzione). Se non lo avete, potete leggere gli esiti con GET /eventi.
• Un referente tecnico da contattare in caso di problemi.

3. Prova e produzione

L'indirizzo è unico:

https://api.neweraerp.it/api/v1

L'ambiente lo decide la chiave:

Le aziende, le fatture e gli eventi della prova sono separati da quelli di produzione: in produzione si riattivano le aziende da capo.

4. Autenticazione

Ogni richiesta porta la chiave nell'header Authorization:

curl https://api.neweraerp.it/api/v1/ping \
  -H "Authorization: Bearer nea_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{ "ok": true, "partner": "Scuole di Musica App", "ambiente": "TEST" }

• La chiave va usata solo dal vostro server, mai dentro un'app web o mobile installata sui dispositivi degli utenti.
• Se una chiave è stata esposta, avvisateci subito: la revochiamo e ve ne diamo una nuova (possono restare attive due chiavi insieme, per cambiarla senza interruzioni).
• Ogni partner vede soltanto le proprie aziende e i propri documenti.

5. Attivare un'azienda

Prima di emettere fatture per un'azienda (una scuola) la si attiva con i suoi dati anagrafici. Sono i dati del cedente che mettiamo in ogni fattura generata dal JSON.

POST/aziende

curl -X POST https://api.neweraerp.it/api/v1/aziende \
  -H "Authorization: Bearer $CHIAVE" -H "Content-Type: application/json" \
  -d '{
    "partitaIva": "01234567890",
    "ragioneSociale": "Scuola di Musica Armonia APS",
    "regimeFiscale": "RF01",
    "indirizzo": "Via Verdi 3",
    "cap": "64100",
    "comune": "Teramo",
    "provincia": "TE",
    "email": "segreteria@scuolaarmonia.it"
  }'

Risposta 201 (attivata) oppure 200 (era già attiva: dati aggiornati). Per modificare l'anagrafica basta ripetere la chiamata. GET /aziende restituisce l'elenco.

6. Inviare una fattura

POST/fatture

curl -X POST https://api.neweraerp.it/api/v1/fatture \
  -H "Authorization: Bearer $CHIAVE" -H "Content-Type: application/json" \
  -H "Idempotency-Key: retta-2026-0153" \
  -d '{
  "fattura": {
    "cedentePartitaIva": "01234567890",
    "numero": "2026/0153",
    "data": "2026-10-22",
    "causale": "Retta ottobre 2026",
    "cliente": {
      "nome": "Mario", "cognome": "Rossi", "codiceFiscale": "RSSMRA80A01L103X",
      "indirizzo": "Via Roma 1", "cap": "64100", "comune": "Teramo", "provincia": "TE"
    },
    "righe": [
      { "descrizione": "Corso di pianoforte - ottobre", "prezzoUnitario": 120,
        "aliquotaIva": 0, "natura": "N4", "riferimentoNormativo": "Esente art. 10 c.1 n.20 DPR 633/72" },
      { "descrizione": "Quota di iscrizione", "prezzoUnitario": 30, "aliquotaIva": 22 }
    ],
    "pagamento": { "modalita": "MP08" }
  }
}'

Risposta 201:

{
  "fattura": {
    "id": 1287, "direzione": "EMESSA", "ambiente": "TEST", "stato": "INVIATA",
    "identificativoSdi": "32730209", "nomeFile": "IT02174570677_T3K9Q.xml",
    "cedentePartitaIva": "01234567890", "formato": "FPR12", "tipoDocumento": "TD01",
    "numero": "2026/0153", "data": "2026-10-22", "codiceDestinatario": "0000000",
    "controparte": { "denominazione": "Mario Rossi", "partitaIva": null, "codiceFiscale": "RSSMRA80A01L103X" },
    "importoTotale": 156.6, "errori": null, "chiaveIdempotenza": "retta-2026-0153", ...
  },
  "totali": { "imponibile": 150, "imposta": 6.6, "totaleDocumento": 156.6,
              "bollo": 2, "ritenuta": 0, "nettoAPagare": 156.6 }
}

Salvate l'id: è il riferimento della fattura per tutte le chiamate successive e per gli avvisi. INVIATA vuol dire che lo SDI l'ha presa in carico; l'esito (consegna o scarto) arriva dopo, di solito entro pochi minuti e al massimo entro 5 giorni, con un avviso automatico.

I dati della fattura

Il cliente

Obbligatori sempre: indirizzo e comune; per i clienti italiani anche provincia.

Se la risposta si perde: Idempotency-Key

Mettete in ogni invio un header Idempotency-Key univoco per fattura (l'id interno del vostro gestionale, o un UUID salvato prima di chiamare). Se la connessione cade e non sapete se la fattura è partita, ripetete la stessa richiesta con la stessa chiave: se era già arrivata vi restituiamo quella (risposta 200 con un avviso) senza mandarla una seconda volta. Senza questa chiave, ripetere l'invio vuol dire trasmettere due volte la stessa fattura.

7. XML e .p7m pronti

Se il vostro software genera già l'XML FatturaPA, mandatelo in base64 al posto di fattura:

{ "fileXml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..." }

• Deve rispettare lo schema FatturaPA 1.2.2 e avere come cedente un'azienda attivata.
• IdTrasmittente e ProgressivoInvio li sostituiamo con quelli del nostro canale; il nome del file lo assegniamo noi.
• I totali sono quelli del vostro XML (non li ricalcoliamo); lo SDI li verifica.

Per una fattura già firmata digitalmente (CAdES):

{ "fileP7m": "MIAGCSqGSIb3DQEHAqCAMIACAQEx..." }

Il .p7m è trasmesso così com'è: la firma copre anche il trasmittente scritto nell'XML, quindi non possiamo modificarlo. Dimensione massima del file: 5 MB, allegati compresi.

8. Stati della fattura e cosa fare

Lo stato corrente e la cronologia: GET/fatture/{id}. L'elenco: GET/fatture?stato=SCARTATA&dal=2026-10-01. Il file trasmesso: GET/fatture/{id}/file.

9. Firma digitale (fatture alla PA)

Le fatture alla Pubblica amministrazione vanno firmate digitalmente. Non firmiamo noi: firma il cliente con la propria firma digitale (smart card, token o firma remota, con Dike, ArubaSign, GoSign…), come già fa chi fattura alla PA.

1. Inviate la fattura normalmente (JSON o XML): se è per la PA resta in stato DA_FIRMARE. Con "firma": true si può chiedere lo stesso percorso anche per una fattura non PA.
2. Scaricate gli XML da firmare: GET/fatture/da-firmare (tutte, con nome file e contenuto base64) oppure GET/fatture/{id}/file (una).
3. Il cliente li firma in formato CAdES (.p7m). Anche la firma multipla va bene. Il file non va modificato.
4. Ricaricate i firmati: POST/fatture/{id}/firmata con { "fileP7m": "…" }, oppure tutti insieme:

POST /fatture/firmate
{ "files": [
    { "nomeFile": "IT02174570677_Z00A7.xml.p7m", "fileP7m": "MIAG…" },
    { "id": 1291, "fileP7m": "MIAG…" }
] }

Per ogni file controlliamo che il contenuto firmato sia identico alla fattura preparata, che la firma sia integra e che il certificato non sia scaduto; poi lo trasmettiamo. Nel caricamento cumulativo ogni file ha il suo esito: risposta 201 se sono passati tutti, 207 se l'esito è misto (guardate risultati).

10. Avvisi automatici

A ogni novità mandiamo una richiesta POST con un JSON all'indirizzo avvisi che ci avete dato:

POST https://vostro-server.it/avvisi-sdi
Content-Type: application/json
X-NewEra-Evento: 5531
X-NewEra-Timestamp: 1792656000
X-NewEra-Firma: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

{
  "evento":  { "id": 5531, "documentoId": 1287, "tipo": "CONSEGNATA", "identificativoSdi": "32730209",
               "nomeFileNotifica": "IT02174570677_T3K9Q_RC_001.xml",
               "dettaglio": { "statoDocumento": "CONSEGNATA", "dataOraConsegna": "2026-10-22T10:41:07.000+02:00" },
               "creatoIl": "2026-10-22T08:41:12.311Z" },
  "fattura": { "id": 1287, "direzione": "EMESSA", "stato": "CONSEGNATA", "numero": "2026/0153", ... }
}

Regole per chi riceve

• Verificate sempre la firma e scartate gli avvisi con timestamp più vecchio di 5 minuti (esempi sotto).
• Rispondete con un codice 2xx entro 10 secondi: salvate l'avviso e lavoratelo dopo.
• Senza 2xx ritentiamo dopo 1, 5, 15 e 60 minuti, poi dopo 3, 6 e 12 ore e quindi ogni 12 ore, fino a 72 ore dall'evento.
• Lo stesso avviso può arrivare due volte: ignorate un evento.id già visto.
• Gli avvisi possono arrivare fuori ordine: lo stato giusto è sempre fattura.stato.
• Non seguiamo i redirect: l'indirizzo deve rispondere direttamente.

Verifica della firma — Node.js (Express)

import crypto from 'node:crypto';
import express from 'express';

const SEGRETO = process.env.NEWERA_SEGRETO_AVVISI;
const app = express();

// serve il corpo GREZZO: la firma è calcolata sui byte esatti ricevuti
app.post('/avvisi-sdi', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-NewEra-Timestamp') ?? '';
  const firma = req.get('X-NewEra-Firma') ?? '';
  const attesa = 'sha256=' + crypto.createHmac('sha256', SEGRETO).update(`${ts}.${req.body}`).digest('hex');
  const valida = firma.length === attesa.length && crypto.timingSafeEqual(Buffer.from(firma), Buffer.from(attesa));
  if (!valida || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);

  const { evento, fattura } = JSON.parse(req.body.toString('utf8'));
  // salva evento.id (deduplica) e fattura.stato, poi lavora in coda
  res.sendStatus(200);
});

Verifica della firma — PHP

<?php
$segreto = getenv('NEWERA_SEGRETO_AVVISI');
$corpo   = file_get_contents('php://input');            // corpo grezzo
$ts      = $_SERVER['HTTP_X_NEWERA_TIMESTAMP'] ?? '';
$firma   = $_SERVER['HTTP_X_NEWERA_FIRMA'] ?? '';
$attesa  = 'sha256=' . hash_hmac('sha256', $ts . '.' . $corpo, $segreto);

if (!hash_equals($attesa, $firma) || abs(time() - (int)$ts) > 300) {
    http_response_code(401);
    exit;
}
$avviso = json_decode($corpo, true);
// salva $avviso['evento']['id'] (deduplica) e $avviso['fattura']['stato']
http_response_code(200);

11. Eventi (recupero)

Tutto quello che succede ai vostri documenti è anche in un registro ordinato, leggibile in qualsiasi momento. Serve a chi non usa gli avvisi e, per chi li usa, come recupero periodico (per esempio ogni ora) nel caso il vostro server sia rimasto fermo più di 72 ore.

GET/eventi?dopo=5530&limite=100

{ "eventi": [ { "id": 5531, "documentoId": 1287, "tipo": "CONSEGNATA", ... } ],
  "ultimoId": 5531,
  "altri": false }

Salvate ultimoId e alla chiamata successiva passatelo come dopo. Se altri è true richiamate subito. Nel registro ci sono anche gli eventi che non mandiamo come avviso perché l'esito lo avete già nella risposta della chiamata: RIFIUTATA_DA_NOI, DA_FIRMARE, FIRMATA.

12. Fatture ricevute dai fornitori

Perché le fatture dei fornitori di un'azienda arrivino a voi, l'azienda registra il codice destinatario che vi comunichiamo nel portale Fatture e Corrispettivi dell'Agenzia delle Entrate (funzione "Registrazione dell'indirizzo telematico"). Da quel momento lo SDI consegna a noi tutte le sue fatture passive, qualunque codice abbia scritto il fornitore. Noi le riconosciamo dalla partita IVA e le rendiamo disponibili al partner di quell'azienda.

1. Arriva l'avviso RICEVUTA (o la leggete da GET/ricevute?nonScaricate=1).
2. Scaricate il file: GET/ricevute/{id}/file
   • ?tipo=xml (predefinito): la fattura leggibile, estratta dal .p7m se era firmata;
   • ?tipo=originale: il file esattamente come consegnato dallo SDI (da conservare);
   • ?tipo=metadati: il file metadati SDI della consegna.
3. Confermate: POST/ricevute/{id}/scaricata. La fattura esce da nonScaricate=1 ma resta consultabile.

Nell'oggetto restituito controparte è il fornitore e destinatarioPartitaIva è la vostra azienda. Filtri: dal=AAAA-MM-GG, partitaIva=…, limite.

13. Errori e limiti

Gli errori hanno sempre la stessa forma: un codice stabile (da usare nella logica del vostro software) e un messaggio in italiano, con eventuali dettagli campo per campo.

HTTP 422
{ "errore": {
    "codice": "FATTURA_NON_VALIDA",
    "messaggio": "La fattura non supera i controlli",
    "dettagli": [ "cliente.provincia: cliente italiano: provincia obbligatoria",
                  "righe.0.natura: riga con IVA 0: indicare la natura (es. N4 esente)" ] } }

Altri limiti: file fino a 5 MB; 100 file per caricamento cumulativo; elenchi fino a 200 righe (500 per gli eventi); Idempotency-Key fino a 100 caratteri.

14. Passaggio in produzione

Prima di chiedere la chiave nea_live_ verificate in prova:

• attivazione di un'azienda e aggiornamento dei suoi dati;
• invio JSON di fattura a privato, ad azienda (codice destinatario o PEC) e nota di credito;
• gestione di una risposta 422 (errori mostrati all'utente, correzione e reinvio);
• ripetizione di un invio con la stessa Idempotency-Key (nessun doppione);
• ricezione degli avvisi con verifica della firma e deduplica;
• recupero da GET /eventi con il cursore salvato;
• se fatturate alla PA: firma e ricaricamento di un .p7m;
• chiave e segreto conservati solo lato server.

In produzione ogni fattura è un documento fiscale reale: una fattura emessa per errore non si cancella, si storna con una nota di credito.

15. Riferimento completo

La specifica OpenAPI 3.1 descrive ogni percorso, parametro, campo e risposta: scarica openapi.json. Si importa in Postman, Insomnia o Swagger Editor, oppure si usa con i generatori di client (openapi-generator) per ottenere il codice di chiamata nel vostro linguaggio.