Per i clienti esterni
Questa guida offre una panoramica dei passaggi necessari per presentare i dati richiesti alle autorità fiscali in conformità ai requisiti legali (§146a (4) AO - Codice fiscale tedesco). È destinata ai clienti che non hanno implementato l’API SIGN DE di fiskaly.
Questa API è stata creata in cooperazione con l’amministrazione fiscale del Land Assia.
La guida si compone di due parti: Configurazione di base e Parte principale — Endpoint SIGN DE x Submission.
Parte 1: Configurazione di base
Sezione intitolata “Parte 1: Configurazione di base”Creazione di un account
Sezione intitolata “Creazione di un account”Per utilizzare i servizi fiskaly, è necessario creare un account tramite il fiskaly HUB. Una volta creato l’account, viene richiesto di creare la prima organizzazione principale.
Creazione della prima organizzazione
Sezione intitolata “Creazione della prima organizzazione”La prima organizzazione (principale), che rappresenta il fornitore del registratore di cassa, deve essere creata tramite il fiskaly HUB. Una volta creata, è possibile procedere con l’aggiunta di organizzazioni gestite che rappresentano le singole sedi del contribuente. È possibile aggiungere un livello aggiuntivo alla struttura; è possibile trovare una guida qui.
Guarda il nostro video per una spiegazione passo a passo su come configurare il proprio account e la prima organizzazione.
Un’organizzazione principale (organization) rappresenta un fornitore di registratori di cassa o un commerciante
con il proprio sistema di registratori di cassa, mentre un’organizzazione gestita (managed_ organization) rappresenta la sede di un commerciante o la sede di un negozio di un commerciante.
Esempi:
- Se l’organizzazione principale è un fornitore di registratori di cassa, le organizzazioni gestite rappresentano la sede di ciascun cliente (contribuente).
- Se l’organizzazione principale è un commerciante con il proprio sistema di registratori di cassa, le organizzazioni gestite rappresentano ogni negozio.
Creazione della prima chiave API
Sezione intitolata “Creazione della prima chiave API”Dopo aver creato un account e la prima organizzazione tramite HUB, è necessario generare una chiave API nell’HUB (Impostazioni -> Chiavi API -> CREA CHIAVE API).
La chiave API e il segreto sono necessari per generare un token di accesso tramite l’endpoint authenticate. Questo token viene utilizzato per tutte le chiamate API.
POST: Creare un’organizzazione
Sezione intitolata “POST: Creare un’organizzazione”Utilizzare questo endpoint per creare un’organizzazione gestita. Utilizzare l’ID dell’organizzazione
principale per il campo managed_by_organization_id nel corpo della richiesta. Si consiglia
vivamente di creare un’organizzazione gestita separata per ogni sede. In questo modo è possibile
creare una struttura in cui un’organizzazione gestita corrisponde a uno stabilimento.
Parte 2: Endpoint SIGN DE x Submission
Sezione intitolata “Parte 2: Endpoint SIGN DE x Submission”POST: Autenticare l’API
Sezione intitolata “POST: Autenticare l’API”Per accedere all’API SIGN DE x Submission è necessario un token JWT valido.
Questo endpoint crea il token con il proprio api_key e api_secret. Se non
si dispone di un api_key, è possibile crearne uno tramite l’endpoint della Management API
createApiKey o tramite il fiskaly HUB. L’api_secret verrà generato
dopo la creazione dell’api_key. Il token deve essere inviato con ogni richiesta successiva
nel campo dell’intestazione Authorization utilizzando lo schema di autenticazione Bearer.
PUT: Creare o aggiornare il contribuente
Sezione intitolata “PUT: Creare o aggiornare il contribuente”Il contribuente rappresenta una persona fisica o una persona giuridica come un’azienda. Le informazioni generali sul contribuente devono essere fornite qui. Viene creato una sola volta e può essere aggiornato senza attivare una nuova presentazione.
All’interno di ogni (managed_)organization, è possibile e deve essere creato un solo contribuente.
PUT: Creare o aggiornare lo stabilimento
Sezione intitolata “PUT: Creare o aggiornare lo stabilimento”Lo stabilimento rappresenta ogni sede fisica dell’attività commerciale (Betriebsstätte) e deve essere creato anche se i dati dello stabilimento coincidono con quelli del contribuente.
Per i clienti che hanno creato una managed_organization separata per ogni
sede, la managed_organization corrisponde sempre a uno stabilimento specifico.
Questo è l’approccio consigliato.
Nel caso in cui una managed_organization rappresenti più di una sede dello stesso
contribuente, deve essere creato uno stabilimento separato per ciascuna di queste sedi.
Ogni contribuente può avere più stabilimenti, ma ogni stabilimento può appartenere a un solo contribuente e avere un unico indirizzo.
La creazione e gli aggiornamenti di TSS e client assegnati a uno stabilimento richiedono sempre una nuova presentazione dello stabilimento interessato nella sua interezza. Gli altri stabilimenti non richiedono una nuova presentazione in quel caso.
PUT: Creare o aggiornare una TSS esterna (ovvero una TSS di un produttore diverso da fiskaly)
Sezione intitolata “PUT: Creare o aggiornare una TSS esterna (ovvero una TSS di un produttore diverso da fiskaly)”Una TSS è un Sistema di Sicurezza Tecnica. È un insieme di componenti utilizzati per proteggere, archiviare e gestire i dati fiscali.
Le TSS esterne devono essere aggiunte tramite questo endpoint.
Questo endpoint non è obbligatorio per i clienti che hanno implementato l’API fiskaly SIGN DE e non utilizzano TSS esterne.
PUT: Creare o aggiornare un client esterno (ovvero che utilizza una TSS di un produttore diverso da fiskaly)
Sezione intitolata “PUT: Creare o aggiornare un client esterno (ovvero che utilizza una TSS di un produttore diverso da fiskaly)”Un client rappresenta un dispositivo registratore di cassa in uso. I client collegati a istanze di TSS esterne vengono aggiunti tramite questo endpoint.
La messa fuori servizio di un client deve essere comunicata una sola volta, impostando i parametri corrispondenti e attivando una nuova presentazione per lo stabilimento interessato. Successivamente, il client può essere rimosso dallo stabilimento e/o riassegnato a un altro stabilimento come client messo in servizio, seguita da una nuova presentazione per lo stabilimento interessato.
Questo endpoint non è obbligatorio per i clienti che hanno implementato l’API fiskaly SIGN DE e non utilizzano TSS esterne.
PUT: Creare la presentazione
Sezione intitolata “PUT: Creare la presentazione”Una presentazione è l’insieme delle informazioni relative a uno stabilimento specifico con tutti i suoi client. Non viene inviata automaticamente alle autorità fiscali — è necessaria una richiesta aggiuntiva tramite l’endpoint TriggerTransmission.
Per trasmettere una presentazione, è necessario scaricare e visualizzare in anteprima il PDF tramite l’endpoint GetValidationSuccessfulFile.
Gli integratori API devono assicurarsi che i contribuenti effettivi abbiano verificato la correttezza dei dati di presentazione generati prima che vengano inviati alle autorità fiscali.
PUT: Attivare la trasmissione
Sezione intitolata “PUT: Attivare la trasmissione”La trasmissione è il processo in cui i dati dalla presentazione vengono trasferiti al server ELSTER (ELektronische STeuer ERklärung). È possibile attivare una sola trasmissione per presentazione.
Una volta attivata, una trasmissione può essere annullata, purché sia ancora in elaborazione nell’API SIGN DE x Submission e non sia ancora stata trasmessa a ELSTER. Poiché la trasmissione di solito avviene entro pochi secondi, la finestra per un annullamento riuscito è breve. Dopo un annullamento riuscito, è possibile attivare nuovamente una trasmissione per la presentazione specifica.
Utilizzare questo endpoint per attivare la trasmissione di una presentazione specifica alle
autorità fiscali. Si noti che ciò è possibile solo se la presentazione si trova nello
stato READY_FOR_TRANSMISSION, che indica che i dati contenuti nella presentazione
sono stati verificati per la validità sintattica e la completezza. Tuttavia,
questo non è una conferma dell’accuratezza fattuale.
Il contribuente è tenuto per legge a verificare la correttezza dei dati della presentazione prima di attivare la trasmissione. L’atto di attivare la presentazione indica il consenso del contribuente e l’assunzione di responsabilità per l’accuratezza dei dati trasmessi. Nel caso in cui nella presentazione trasmessa siano stati inclusi dati errati, ciò può essere rettificato semplicemente creando e trasmettendo una nuova presentazione con i dati corretti.
Was this page helpful?