Fatturazione elettronica - Germania

L'API Fatturazione Elettronica Germania permette di integrare nei propri software la gestione completa della fatturazione elettronica tedesca attraverso un'unica API REST. È possibile configurare le aziende, inviare e ricevere fatture elettroniche, monitorarne lo stato e automatizzare l'intero ciclo documentale, semplificando l'integrazione con i sistemi previsti dalla normativa tedesca.

Progettata per software house, ERP, piattaforme e-commerce e aziende che operano sul mercato tedesco, l'API consente di ridurre la complessità di sviluppo grazie a un modello di integrazione semplice, scalabile e facilmente integrabile con i processi aziendali esistenti.

La soluzione gestisce automaticamente il processo di trasmissione delle fatture, fornisce aggiornamenti sullo stato dei documenti tramite callback e consente di integrare la fatturazione elettronica direttamente all'interno di gestionali, applicazioni e piattaforme software.

Configurazione azienda e servizi

POST /DE-configurations

La configurazione dell'azienda rappresenta il primo passo per utilizzare l'API Fatturazione Elettronica Germania. Tramite questo endpoint puoi registrare l'azienda, abilitare il servizio di invio, di ricezione oppure entrambi, in base alle esigenze della tua integrazione, e configurare le callback che riceveranno automaticamente gli aggiornamenti sullo stato dei documenti.

Durante la fase di onboarding viene creata la Legal Entity e registrato l'identificativo DE:VAT sulla rete Peppol, permettendo all'azienda di scambiare fatture elettroniche secondo gli standard previsti dalla normativa tedesca.

Una volta completata la configurazione, l'azienda è pronta a utilizzare i servizi abilitati, sia per l'invio delle fatture elettroniche, sia per la ricezione, oppure per entrambe le funzionalità. Tutti gli aggiornamenti sul ciclo di vita dei documenti vengono notificati automaticamente tramite callback, mantenendo il gestionale sempre sincronizzato senza necessità di effettuare richieste periodiche alle API.

ESEMPIO RICHIESTA

Per configurare l'azienda è necessario effettuare una richiesta a POST /DE-configurations. Nell'esempio seguente vengono abilitati i servizi di invio e ricezione delle fatture elettroniche e configurata una callback per ricevere gli aggiornamenti sullo stato dei documenti.

{
  "fiscal_id": "DE123456789",
  "name": "Mustermann GmbH",
  "email": "[email protected]",
  "customer_invoice": true,
  "supplier_invoice": true,
  "address": {
    "street_address": "Hauptstraße 42",
    "zip_code": "10115",
    "city": "Berlin",
    "country": "DE"
  },
  "api_configurations": [
    {
      "event": "customer-invoice",
      "callback": {
        "url": "https://your-server.site/webhook/de/out"
      }
    },
    {
      "event": "supplier-invoice",
      "callback": {
        "url": "https://your-server.site/webhook/de/in"
      }
    }
  ]
}

Invio fattura elettronica

POST /DE-invoices

L'endpoint POST /DE-invoices permette di inviare una fattura elettronica tedesca B2B o B2G tramite un'unica richiesta API. Una volta ricevuto il documento, Openapi ne verifica la correttezza, genera automaticamente il formato richiesto dalla normativa tedesca e gestisce l'intero processo di trasmissione.

Per le fatture destinate ad aziende (B2B) l'API genera automaticamente documenti nel formato ZUGFeRD, mentre per le fatture verso la Pubblica Amministrazione tedesca (B2G) utilizza il formato XRechnung. L'applicazione non deve implementare logiche differenti: è sufficiente inviare i dati della fattura e sarà la piattaforma a produrre il formato corretto in base al destinatario.

La trasmissione avviene tramite la rete Peppol, seguendo le modalità previste dalla normativa tedesca. Tutto il processo di consegna, il monitoraggio dello stato del documento e le notifiche vengono gestiti automaticamente dall'API, semplificando l'integrazione con i sistemi aziendali.

ESEMPIO RICHIESTA

L'esempio seguente mostra una richiesta di invio di una fattura elettronica B2B tramite l'endpoint POST /DE-invoices.

{
  "document_number": "INV-2026-001",
  "issue_date": "2026-06-26",
  "currency": "EUR",
  "type": "380",
  "sender": {
    "name": "Mustermann GmbH",
    "fiscal_id": "DE123456789",
    "vat_id": "DE123456789",
    "address": {
      "street_address": "Unter den Linden 34-37",
      "city": "Berlin",
      "zip_code": "10115",
      "country": "DE"
    }
  },
  "recipient": {
    "name": "Customer GmbH",
    "vat_id": "DE987654321",
    "email": "[email protected]"
  },
  "invoice_lines": [
    {
      "description": "IT consulting services",
      "quantity": 50,
      "unit_price": 100.00,
      "total_net_amount": 5000.00,
      "tax_rate": 19,
      "unit_of_measure": "HUR"
    }
  ],
  "tax_subtotals": [
    {
      "taxable_amount": 5000.00,
      "tax_amount": 950.00,
      "tax_rate": 19,
      "tax_category": "standard"
    }
  ],
  "payment_means": [
    {
      "payment_mode": "credit_transfer",
      "financial_account": "DE89370400440532013000",
      "due_date": "2026-07-26",
      "amount": 5950.00
    }
  ]
}

Nota: l'esempio mostra l'invio di una fattura B2B. In questo caso è necessario allegare il PDF del documento, che l'API converte automaticamente in un file ZUGFeRD conforme allo standard PDF/A-3 incorporando il tracciato EN 16931. Per le fatture destinate alla Pubblica Amministrazione (B2G), invece, il PDF non è richiesto: è sufficiente valorizzare il Leitweg-ID e l'API genererà automaticamente una fattura nel formato XRechnung.

Instradamento intelligente delle fatture

La fatturazione elettronica tedesca prevede modalità di trasmissione differenti in base alla tipologia del destinatario. Con l'API Fatturazione Elettronica Germania non è necessario implementare logiche specifiche: il gestionale invia sempre la fattura allo stesso endpoint REST e sarà la piattaforma a individuare automaticamente il canale di consegna più appropriato.

Per le fatture B2B il destinatario viene identificato tramite il numero di partita IVA tedesco (DE:VAT) e il documento viene generato nel formato ZUGFeRD. Per le fatture destinate alla Pubblica Amministrazione (B2G), invece, viene utilizzato il Leitweg-ID (DE:LWID) e il documento viene prodotto nel formato XRechnung, come previsto dalla normativa tedesca.

Per le fatture destinate alla Pubblica Amministrazione è consigliabile valorizzare anche l'indirizzo email del destinatario, poiché non tutte le amministrazioni tedesche sono attualmente raggiungibili tramite la rete Peppol.

Grazie a questo approccio è sufficiente integrare un solo endpoint API, lasciando a Openapi tutta la complessità della selezione del canale di trasmissione e della consegna della fattura, garantendo la conformità ai requisiti previsti dalla normativa tedesca.

Monitoraggio dello stato delle fatture

Dopo l'invio di una fattura elettronica, l'API consente di monitorarne l'intero ciclo di vita. Ogni documento viene tracciato dalla fase di invio fino alla consegna finale, permettendo al gestionale di conoscere in tempo reale lo stato della trasmissione.

Gli aggiornamenti vengono notificati automaticamente tramite webhook, eliminando la necessità di interrogare continuamente le API. Ad ogni variazione di stato, il sistema riceve una notifica contenente tutte le informazioni necessarie per sincronizzare il gestionale con il processo di consegna.

Gli stati restituiti dall'API rappresentano le principali fasi del ciclo di vita della fattura (NEW, SENT, DONE ed ERROR) e vengono aggiornati automaticamente in base alle notifiche ricevute dalla rete di trasmissione. In questo modo è possibile verificare rapidamente se una fattura è stata presa in carico, consegnata oppure se richiede un intervento a causa di un errore.

Consultazione delle fatture

L'API Fatturazione Elettronica Germania consente di consultare in qualsiasi momento le fatture inviate e ricevute, recuperandone lo stato aggiornato e tutti i dati associati. Gli endpoint di consultazione permettono di integrare facilmente funzionalità di ricerca, monitoraggio e sincronizzazione all'interno del proprio gestionale.

È possibile ottenere sia l'elenco completo delle fatture elettroniche elaborate dal servizio sia il dettaglio di uno specifico documento, comprensivo di informazioni anagrafiche, righe della fattura, importi, allegati e stato corrente della trasmissione.

Elenco delle fatture

GET /DE-invoices

L'endpoint GET /DE-invoices restituisce l'elenco delle fatture elettroniche elaborate dal servizio. La risposta include i principali dati identificativi di ciascun documento e il relativo stato, consentendo di monitorare facilmente il ciclo di vita delle fatture direttamente dal proprio gestionale.

ESEMPIO RICHIESTA

L'esempio seguente mostra come recuperare l'elenco delle fatture elettroniche gestite dall'API.

{
  "data": [
    {
      "document_number": "DE-2026-001",
      "issue_date": "2026-06-26",
      "due_date": "2026-07-26",
      "currency": "EUR",
      "type": "380",
      "total_amount_including_tax": 1190,
      "total_amount_excluding_tax": 1000,
      "total_tax_amount": 190,
      "leitweg_id": null,
      "buyer_reference": null,
      "commitment_number": null,
      "sender": {
        "name": "Mustermann GmbH",
        "vat_number": "DE123456789",
        "vat_id": "DE123456789",
        "leitweg_id": null,
        "email": "[email protected]",
        "address": {
          "street_address": "Hauptstraße",
          "street_number": "42",
          "zip_code": "10115",
          "city": "Berlin",
          "country": "DE"
        }
      },
      "recipient": {
        "name": "Mustermann GmbH",
        "vat_number": "DE123456789",
        "vat_id": "DE123456789",
        "leitweg_id": null,
        "email": "[email protected]",
        "address": {
          "street_address": "Hauptstraße",
          "street_number": "42",
          "zip_code": "10115",
          "city": "Berlin",
          "country": "DE"
        }
      },
      "invoice_lines": [
        {
          "description": "Wireless Mouse",
          "quantity": 2,
          "unit_price": 25.5,
          "tax_rate": 20,
          "total_net_amount": 51,
          "unit_of_measure": "C62",
          "nature": "standard",
          "tax_category": "standard"
        }
      ],
      "payment_means": [
        {
          "payment_mode": "sepa_credit_transfer",
          "due_date": "2026-06-12",
          "amount": 61.2,
          "financial_account": "FR7630006000011234567890123"
        }
      ],
      "tax_subtotals": [
        {
          "taxable_amount": 51,
          "tax_amount": 10.2,
          "vat_rate": 20,
          "tax_category": "standard"
        }
      ],
      "attachments": [
        {
          "document": "JVBERi0xLjcKJeLjz9MK...",
          "mime_type": "application/pdf",
          "filename": "INV-2026-001.pdf",
          "description": "Invoice PDF",
          "document_id": "INV-2026-001"
        }
      ],
      "id": "645a3f2b1c0d9e8f7a6b5c4d",
      "state": "NEW",
      "details": {
        "external_status": "submitted",
        "invoice_type": "ZUGFeRD",
        "leitweg_id": null,
        "submission_date": "2026-06-26T10:00:00Z"
      },
      "create_at": "2026-06-26T10:00:00Z"
    }
  ],
  "success": true,
  "message": "",
  "error": null
}

Dettaglio di una fattura

GET /DE-invoices/{id}

Per ottenere il dettaglio di una specifica fattura è possibile utilizzare l'endpoint GET /DE-invoices/{id}, specificando l'identificativo del documento restituito durante la fase di invio o di ricezione.

La risposta include tutte le informazioni della fattura, lo stato corrente del documento e i dati relativi al processo di trasmissione.

Quando necessario è possibile utilizzare il parametro refresh=true, che forza la sincronizzazione con il sistema di trasmissione e restituisce lo stato più aggiornato disponibile.

ESEMPIO RICHIESTA

L'esempio seguente mostra come recuperare il dettaglio di una fattura forzando l'aggiornamento dello stato del documento.

GET /DE-invoices/645a3f2b1c0d9e8f7a6b5c4d?refresh=true

Nella maggior parte dei casi gli aggiornamenti vengono ricevuti automaticamente tramite callback. Gli endpoint di consultazione rappresentano uno strumento aggiuntivo per verificare lo stato di uno specifico documento, sincronizzare sistemi esterni oppure aggiornare manualmente le informazioni quando necessario.

{
  "data": {
    "document_number": "DE-2026-001",
    "issue_date": "2026-06-26",
    "due_date": "2026-07-26",
    "currency": "EUR",
    "type": "380",
    "total_amount_including_tax": 1190,
    "total_amount_excluding_tax": 1000,
    "total_tax_amount": 190,
    "leitweg_id": null,
    "buyer_reference": null,
    "commitment_number": null,
    "sender": {
      "name": "Mustermann GmbH",
      "vat_number": "DE123456789",
      "vat_id": "DE123456789",
      "leitweg_id": null,
      "email": "[email protected]",
      "address": {
        "street_address": "Hauptstraße",
        "street_number": "42",
        "zip_code": "10115",
        "city": "Berlin",
        "country": "DE"
      }
    },
    "recipient": {
      "name": "Mustermann GmbH",
      "vat_number": "DE123456789",
      "vat_id": "DE123456789",
      "leitweg_id": null,
      "email": "[email protected]",
      "address": {
        "street_address": "Hauptstraße",
        "street_number": "42",
        "zip_code": "10115",
        "city": "Berlin",
        "country": "DE"
      }
    },
    "invoice_lines": [
      {
        "description": "Wireless Mouse",
        "quantity": 2,
        "unit_price": 25.5,
        "tax_rate": 20,
        "total_net_amount": 51,
        "unit_of_measure": "C62",
        "nature": "standard",
        "tax_category": "standard"
      }
    ],
    "payment_means": [
      {
        "payment_mode": "sepa_credit_transfer",
        "due_date": "2026-06-12",
        "amount": 61.2,
        "financial_account": "FR7630006000011234567890123"
      }
    ],
    "tax_subtotals": [
      {
        "taxable_amount": 51,
        "tax_amount": 10.2,
        "vat_rate": 20,
        "tax_category": "standard"
      }
    ],
    "attachments": [
      {
        "document": "JVBERi0xLjcKJeLjz9MK...",
        "mime_type": "application/pdf",
        "filename": "INV-2026-001.pdf",
        "description": "Invoice PDF",
        "document_id": "INV-2026-001"
      }
    ],
    "id": "645a3f2b1c0d9e8f7a6b5c4d",
    "state": "NEW",
    "direction": "outgoing",
    "details": {
      "external_status": "submitted",
      "invoice_type": "ZUGFeRD",
      "leitweg_id": null,
      "submission_date": "2026-06-26T10:00:00Z"
    },
    "create_at": "2026-06-26T10:00:00Z",
    "updated_at": "2026-06-26T10:00:00Z"
  },
  "success": true,
  "message": "Invoice sent successfully",
  "error": null
}

Ricezione delle fatture elettroniche passive

L'API Fatturazione Elettronica Germania permette di ricevere automaticamente le fatture elettroniche emesse dai fornitori, centralizzando l'intero ciclo passivo direttamente all'interno del proprio gestionale.

Dopo aver abilitato il servizio di ricezione durante la configurazione dell'azienda, ogni fattura destinata all'organizzazione viene acquisita automaticamente e resa disponibile tramite le callback configurate, indipendentemente dal canale di trasmissione utilizzato.

Ogni evento supplier-invoice contiene tutte le informazioni necessarie per identificare il documento e avviare automaticamente i processi di registrazione, contabilizzazione o approvazione nel gestionale, eliminando la necessità di gestire manualmente l'acquisizione delle fatture.

CONFIGURAZIONE CALLBACK

Per ricevere automaticamente le fatture passive è sufficiente configurare una callback durante la fase di onboarding dell'azienda.

{
  "api_configurations": [
    {
      "event": "supplier-invoice",
      "callback": {
        "url": "https://your-server.site/webhook/de/in"
      }
    }
  ]
}

Ogni nuova fattura ricevuta genera automaticamente una callback verso l'endpoint configurato, consentendo al gestionale di acquisire il documento e avviare immediatamente i processi interni senza ulteriori chiamate alle API.

A chi si rivolge l'API Fatturazione Elettronica Germania

L'API Fatturazione Elettronica Germania è progettata per tutte le realtà che desiderano integrare e automatizzare la gestione delle fatture elettroniche tedesche direttamente nei propri software. È la soluzione ideale per software house, sviluppatori, ERP e Independent Software Vendor (ISV) che vogliono aggiungere rapidamente la conformità alla normativa tedesca attraverso un'unica integrazione API, senza dover gestire la complessità dei diversi formati e canali di trasmissione.

Si rivolge anche ad aziende italiane e internazionali con clienti, fornitori o sedi operative in Germania, piattaforme e-commerce, marketplace e software di contabilità che devono emettere e ricevere automaticamente fatture elettroniche, oltre a studi professionali e società di consulenza che gestiscono i processi amministrativi e fiscali dei propri clienti.

Grazie alla generazione automatica dei formati ZUGFeRD e XRechnung, all'instradamento intelligente delle fatture, alle callback in tempo reale e a un modello di integrazione condiviso con le API di Fatturazione Elettronica Italia e Francia, la soluzione si adatta sia a progetti con volumi contenuti sia a piattaforme enterprise che elaborano migliaia di documenti ogni giorno, riducendo tempi di sviluppo, costi di manutenzione e complessità operativa.