Run with Postman

SDI

URL: https://openapi.it/en/support License: Terms of Service

This service allows you to handle interactions with the Italian SDI (Sistema Di Interscambio)

You can configure your account to send invoices directly to the legal storage by setting the api_configuration to your needs

First time here? Generate a new access token

Before we begin

In order to operate, you should register our Recipient Code on the Italian Revenue Agency's website. Please follow this step-by-step guide and provide the following code when needed: JKKZDGR

Get started:

Interacting with the legal storage

Get started:

Create an BusinessRegistryConfiguration with POST /business_registry_configurations for your fiscal_id and your email
A mail will be sent to your address to activate the account on the legal storage platform, if required.
Create an ApiConfiguration for your BusinessRegistryConfiguration with POST /api_configurations. This endpoint can be configured to receive all the notifications with a callback.
Create an XML invoice on the endpoint relative to your configuration

To see an example of the callback objects, plese check the Callbacks tab in the /api_configurations request

Please note that in the English translation:

Customer invoices: Fatture attive

Supplier invoices: Fatture passive

Legal storage: Certificazione a norma

Interacting with the legal storage

Legal Storage is the service that enables the legal preservation for your documents. All the stored documents are available into the legal storage management software, a third party software.

When creating a BusinessRegistryConfiguration, you will be asked to provide an email address which will be registed on the platform. You will receive an email containing all the steps to complete the registration and access the platform.

Reactivating a BusinessRegistryConfiguration

If you receive a callback but you have no credit left on your wallet, your account will be temporarily suspended: when this happens, you will be sent a reminder email immediately. In order to re-activate it after a wallet recharge, you would need to submit a PATCH request to /business_registry_configurations/{fiscal_id}/activate

Interacting with the Public Administration (PA)

Invoices to the Public Administration are automatically detected and signed.

ApiConfigurations

Create an ApiConfiguration for a fiscal_id

Create the configurations of your callback endpoints.

All the notifications received by SDI will be dispatched to your configured endpoints.
The fiscal_id is the unique identifier of the business that you want to configure.

You can create separate endpoints for each event: the event code can be one of supplier-invoice, customer-invoice, customer-notification, legal-storage-missing-vat, legal-storage-receipt

Authorizations:

bearerAuth

Request Body schema: application/json

fiscal_id	string Default: "<string>"
	Array of objects 2 items [ items ]

Responses

Response Schema: application/json

	Array of objects (ApiConfiguration-read) <= 2 items [ items ] The list of ApiConfiguration created for this fiscal_id
message	string
success	boolean
error	string <nullable>

Callbacks

Request samples

Content type

application/json

{"fiscal_id": "000133445566",
"callbacks": [{"event": "supplier-invoice",
"url": "https://example.com/callback",
"auth_header": "Bearer 123456789",
"field": "data"
}
]
}

Response samples

Content type

application/json

{"data": [{"id": "000133445566",
"callbacks": [{"event": "supplier-invoice",
"url": "https://example.com/callback",
"auth_header": "Bearer 123456789",
"field": "data"
}
]
}
],
"message": "string",
"success": true,
"error": "string"
}

Callback payload samples

Callback

POST: {your_url}

Content type

application/json

Example

{"event": "customer-invoice",
"data": {"invoice": {"uuid": "9b8dddbd-7900-48c6-b159-0f60cc9b413c",
"created_at": "2022-09-13T10:39:14+00:00",
"filename": "IT10442360961_06XA6.xml",
"file_id": 1084646898320,
"payload": {"fattura_elettronica_header": {"dati_trasmissione": {"id_trasmittente": {"id_paese": "IT",
"id_codice": "10442360961"
},
"progressivo_invio": "06V27",
"formato_trasmissione": "FPR12",
"codice_destinatario": "123123123",
"contatti_trasmittente": null,
"pec_destinatario": null
},
"cedente_prestatore": {"dati_anagrafici": {"id_fiscale_iva": {"id_paese": "IT",
"id_codice": "prova_1663065381275"
},
"codice_fiscale": null,
"anagrafica": {"denominazione": "John Doe",
"nome": null,
"cognome": null,
"titolo": null,
"cod_eori": null
},
"albo_professionale": null,
"provincia_albo": null,
"numero_iscrizione_albo": null,
"data_iscrizione_albo": null,
"regime_fiscale": "RF01"
},
"sede": {"indirizzo": "Via di Qua, 1",
"numero_civico": null,
"cap": "20145",
"comune": "Milano",
"provincia": "MI",
"nazione": "IT"
},
"stabile_organizzazione": null,
"iscrizione_rea": null,
"contatti": null,
"riferimento_amministrazione": null
},
"rappresentante_fiscale": null,
"cessionario_committente": {"dati_anagrafici": {"id_fiscale_iva": {"id_paese": "IT",
"id_codice": "09876543211"
},
"codice_fiscale": null,
"anagrafica": {"denominazione": "Jane Doe",
"nome": null,
"cognome": null,
"titolo": null,
"cod_eori": null
}
},
"sede": {"indirizzo": "Via di La, 2",
"numero_civico": null,
"cap": "20145",
"comune": "Milano",
"provincia": "MI",
"nazione": "IT"
},
"stabile_organizzazione": null,
"rappresentante_fiscale": null
},
"terzo_intermediario_o_soggetto_emittente": null,
"soggetto_emittente": null
},
"fattura_elettronica_body": [{"dati_generali": {"dati_generali_documento": {"tipo_documento": "TD01",
"divisa": "EUR",
"data": "2018-07-10",
"numero": "1",
"dati_ritenuta": null,
"dati_bollo": null,
"dati_cassa_previdenziale": null,
"sconto_maggiorazione": null,
"importo_totale_documento": null,
"arrotondamento": null,
"causale": null,
"art73": null
},
"dati_ordine_acquisto": null,
"dati_contratto": null,
"dati_convenzione": null,
"dati_ricezione": null,
"dati_fatture_collegate": null,
"dati_sal": null,
"dati_ddt": null,
"dati_trasporto": null,
"fattura_principale": null
},
"dati_beni_servizi": {"dettaglio_linee": [{"numero_linea": 1,
"tipo_cessione_prestazione": null,
"codice_articolo": null,
"descrizione": "Descrizione articolo",
"q