### Example GET Request for Company Verification

Source: https://docs.acubeapi.com/documentation/italy/gov-it/verify/get-company

Use this endpoint to fetch detailed information about a company by providing its fiscal code or VAT number. The ID should not include the country prefix.

```bash
GET /verify/company/10442360961
```

--------------------------------

### Example Fiscal ID Verification Request

Source: https://docs.acubeapi.com/documentation/italy/gov-it/verify/check-fiscalId

This snippet shows an example of a GET request to the /verify/fiscal-id/{id} endpoint, where {id} is the fiscal code to be verified.

```http
GET /verify/fiscal-id/BNCMRA70A20H501B
```

--------------------------------

### Example Response for Return Receipt

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/return_receipt_tutorial

This is an example of a successful response body when returning items from a sale receipt issued by a different device. Note the 'document_number' may vary.

```json
{
  "uuid": "62f25bea-2818-3ae2-ac26-1e562288bee1",
  "type": "return",
  "total_amount": "122",
  "document_number": "0027-0120", 
  "document_datetime": "2025-09-01T11:00:00",
  "parent_receipt_uuid": null,
  "is_voidable": false,
  "is_returnable": false,
  "pdf_url": "https://ereceipts-it-sandbox.acubeapi.com/mf1/receipts/62f25bea-2818-3ae2-ac26-1e562288bee1/pdf"
}

```

--------------------------------

### Example NS Notification XML with Many Errors

Source: https://docs.acubeapi.com/documentation/italy/gov-it/sandbox/sim-customer-notification

This XML example demonstrates an NS notification with multiple errors reported by SDI. It includes details for each error, such as code, description, and suggestions for correction.

```xml
<?xml version="1.0" encoding="UTF-8"?>  

<ns3:RicevutaScarto xmlns:ns3="http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fattura/messaggi/v1.0" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#" versione="1.0">  

    <IdentificativoSdI>13540812472</IdentificativoSdI>  

    <NomeFile>IT10442360961ACB24_0Mpfn.xml</NomeFile>  

    <Hash>771a6f7f2c73c9b33f51318da6c768e7c19e6ce65405bf47c845a2cc206fde91</Hash>  

    <DataOraRicezione>2024-12-07T13:00:20.000+01:00</DataOraRicezione>  

    <ListaErrori>  

        <Errore>  

            <Codice>00200</Codice>  

            <Descrizione>File non conforme al formato : The value '1111111111' of element 'CodiceFiscale' is not valid.  

riga: 1 - colonna: 1254</Descrizione>  

            <Suggerimento>Verificare che i campi contenuti nel file inviato rispettino caratteristiche formali e ordine di rappresentazione previsti dal tracciato fattura</Suggerimento>  

        </Errore>  

        <Errore>  

            <Codice>00200</Codice>  

            <Descrizione>File non conforme al formato : The value '2254.1' of element 'PrezzoUnitario' is not valid.  

riga: 1 - colonna: 1860</Descrizione>  

            <Suggerimento>Verificare che i campi contenuti nel file inviato rispettino caratteristiche formali e ordine di rappresentazione previsti dal tracciato fattura</Suggerimento>  

        </Errore>  

        <Errore>  

            <Codice>00200</Codice>  

            <Descrizione>File non conforme al formato : The value '2254.1' of element 'PrezzoTotale' is not valid.  

riga: 1 - colonna: 1895</Descrizione>  

            <Suggerimento>Verificare che i campi contenuti nel file inviato rispettino caratteristiche formali e ordine di rappresentazione previsti dal tracciato fattura</Suggerimento>  

        </Errore>  

        <Errore>  

            <Codice>00200</Codice>  

            <Descrizione>File non conforme al formato : The value '2254.1' of element 'ImponibileImporto' is not valid.  

riga: 1 - colonna: 2036</Descrizione>  

            <Suggerimento>Verificare che i campi contenuti nel file inviato rispettino caratteristiche formali e ordine di rappresentazione previsti dal tracciato fattura</Suggerimento>  

        </Errore>  

        <Errore>  

            <Codice>00200</Codice>  

            <Descrizione>File non conforme al formato : The value '495.9' of element 'Imposta' is not valid.  

riga: 1 - colonna: 2060</Descrizione>  

            <Suggerimento>Verificare che i campi contenuti nel file inviato rispettino caratteristiche formali e ordine di rappresentazione previsti dal tracciato fattura</Suggerimento>  

        </Errore>  

    </ListaErrori>  

    <MessageId>32585329468</MessageId>  

</ns3:RicevutaScarto>  
```

--------------------------------

### Example Return Receipt Response

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/return_receipt_tutorial

This is an example of a successful response body when returning items from a sale receipt. It includes details like UUID, type, and total amount.

```json
{
  "uuid": "25a34bea-3418-17ba-ac31-2f704474abb3",
  "type": "return",
  "total_amount": "122",
  "document_number": "0001-0002",
  "document_datetime": "2025-09-01T11:00:00",
  "parent_receipt_uuid": "18a681da-a868-47ba-a931-2f702474c3d1",
  "is_voidable": false,
  "is_returnable": false,
  "pdf-url": "url/to/pdf"
}
```

--------------------------------

### Simplified Invoice JSON Example

Source: https://docs.acubeapi.com/documentation/italy/gov-it/invoices/simplified-invoices

This is an example of a simplified invoice structure that can be sent to the POST /invoices/simplified endpoint. It requires less customer information compared to the full FatturaPA format.

```json
{
  "fattura_elettronica_header": {
    "dati_trasmissione": {
      "codice_destinatario": "ABCDEFG"
    },
    "cedente_prestatore": {
      "id_fiscale_iva": {
        "id_paese": "IT",
        "id_codice": "12345678901"
      },
      "sede": {
        "indirizzo": "address string",
        "cap": "12345",
        "comune": "city string",
        "nazione": "IT"
      },
      "regime_fiscale": "RF01"
    },
    "cessionario_committente": {
      "identificativi_fiscali": {
        "codice_fiscale": "ABSDVFCNSHBGAFTS"
      }
    }
  },
  "fattura_elettronica_body": [
    {
      "dati_generali": {
        "dati_generali_documento": {
          "tipo_documento": "TD07",
          "divisa": "EUR",
          "data": "2020-07-01",
          "numero": "111"
        }
      },
      "dati_beni_servizi": [
        {
          "descrizione": "goods description",
          "importo": "100",
          "dati_iva": {
            "imposta": "22"
          }
        }
      ]
    }
  ]
}
```

--------------------------------

### Example Request for Simple Company Verification

Source: https://docs.acubeapi.com/documentation/italy/gov-it/verify/get-simple-company

Use this endpoint to request basic company details by providing the fiscal code or VAT number as the ID. The ID should not include the country prefix.

```http
GET /verify/company/simple/10442360961
```

--------------------------------

### Query Returnable Items (Python)

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/return_receipt_tutorial

Query the system to retrieve the returnable amount for each item of a sale receipt using a GET request. Requires certificate and key for authentication.

```python
import requests

CERT_PATH = '/var/certs/pems/E001-000001/cr-cert.pem'
KEY_PATH = '/var/certs/pems/E001-000001/cr-key.pem'
response = requests.get(
    'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts/18a681da-a868-47ba-a931-2f702474c3d1/returnable-items',
    cert=(CERT_PATH, KEY_PATH)
)

```

--------------------------------

### Example Request for Split Payment Verification

Source: https://docs.acubeapi.com/documentation/italy/gov-it/verify/get-splitpayment

Use this endpoint to request Split Payment status for a company by providing its fiscal code or VAT number.

```HTTP
GET /verify/split/10442360961
```

--------------------------------

### NumberingSequence JSON Body Example

Source: https://docs.acubeapi.com/documentation/italy/gov-it/invoices/autonumbering

Example JSON body for creating a NumberingSequence. The 'name' is a unique identifier, 'format' defines the invoice number template (using '%s' as a placeholder), and 'number' sets the last used number.

```json
{
  "name": "SequenceName",
  "format": "Sez1-%s",
  "number": 0
}
```

--------------------------------

### Create a Numbering Sequence

Source: https://docs.acubeapi.com/documentation/italy/gov-it/invoices/autonumbering

Send a POST request to create a new numbering sequence. Define the sequence name, number format, and the starting number.

```bash
POST /numbering-sequences  
```

--------------------------------

### Return items of a sale receipt

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/return_receipt_tutorial

This section demonstrates how to return items from a sale receipt. It includes examples for Node.js, cURL, and PHP.

```APIDOC
## POST /mf1/receipts/return

### Description
Allows returning items of a sale receipt issued by the same PEM.

### Method
POST

### Endpoint
/mf1/receipts/return

### Parameters
#### Request Body
- **document_number** (string) - Required - The document number of the receipt to return items from.
- **items** (array) - Required - A list of items to return.
  - **id** (integer) - Required - The ID of the item to return.
  - **quantity** (string) - Required - The quantity of the item to return.

### Request Example
```json
{
  "document_number": "0001-0001",
  "items": [
    {
      "id": 2,
      "quantity": "1"
    }
  ]
}
```

### Response
#### Success Response (201)
- **uuid** (string) - The unique identifier for the return transaction.
- **type** (string) - The type of transaction, 'return'.
- **total_amount** (string) - The total amount of the return.
- **document_number** (string) - The document number of the return.
- **document_datetime** (string) - The date and time of the return document.
- **parent_receipt_uuid** (string) - The UUID of the original receipt.
- **is_voidable** (boolean) - Indicates if the return is voidable.
- **is_returnable** (boolean) - Indicates if the return is returnable.
- **pdf-url** (string) - A URL to the PDF of the return receipt.

#### Response Example
```json
{
  "uuid": "25a34bea-3418-17ba-ac31-2f704474abb3",
  "type": "return",
  "total_amount": "122",
  "document_number": "0001-0002",
  "document_datetime": "2025-09-01T11:00:00",
  "parent_receipt_uuid": "18a681da-a868-47ba-a931-2f702474c3d1",
  "is_voidable": false,
  "is_returnable": false,
  "pdf-url": "url/to/pdf"
}
```
```

--------------------------------

### Assign Business Registry Configuration to Appointee

Source: https://docs.acubeapi.com/documentation/italy/gov-it/cassettofiscale

Use this API endpoint to assign a created Business Registry Configuration to a previously created Appointee. This is part of the Incaricato/Appointee setup.

```bash
Assign the BusinessRegistryConfiguration to the previously created Appointee
```

--------------------------------

### GET /verify/company/simple/{id}

Source: https://docs.acubeapi.com/documentation/italy/gov-it/verify/get-simple-company

Retrieves basic company information using a fiscal code or VAT number. The ID should not include the country prefix.

```APIDOC
## GET /verify/company/simple/{id}

### Description
This endpoint allows you to obtain basic data about a company based on its VAT number or its fiscal code. The `{id}` parameter should be the fiscal code or VAT number without the country prefix code.

### Method
GET

### Endpoint
/verify/company/simple/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The fiscal code or VAT number of the company.

### Response
#### Success Response (200)
- **id** (string) - The fiscal code or VAT number.
- **fiscal_code** (string) - The fiscal code of the company.
- **company_name** (string) - The name of the company.
- **registered_office** (object) - Details about the company's registered office.
  - **address** (string) - The full registered address.
  - **toponym** (string) - The toponym of the address.
  - **street** (string) - The street name.
  - **house_number** (string) - The house number.
  - **municipality** (string) - The municipality.
  - **hamlet** (string) - The hamlet.
  - **province** (string) - The province.
  - **postal_code** (string) - The postal code.
- **activity_status** (string) - The current activity status of the company (e.g., "ATTIVA").
- **recipient_code** (string) - The recipient code.
- **gps** (object) - Geographic coordinates.
  - **coordinates** (array) - An array containing latitude and longitude.
- **enrollment_date** (string) - The date the company was enrolled.
- **last_update_timestamp** (integer) - The timestamp of the last update.

#### Response Example
{
  "id": "10442360961",
  "fiscal_code": "10442360961",
  "company_name": "Company name",
  "registered_office": {
    "address": "VIA ROMA, 1",
    "toponym": "VIA",
    "street": "ROMA",
    "house_number": "1",
    "municipality": "MILANO",
    "hamlet": "MILANO",
    "province": "MI",
    "postal_code": "00000"
  },
  "activity_status": "ATTIVA",
  "recipient_code": "ABC1234",
  "gps": {
    "coordinates": [45.464211, 9.191383]
  },
  "enrollment_date": "2018-01-01",
  "last_update_timestamp": 1686319229
}
```

--------------------------------

### Example Returnable Items Response

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/return_receipt_tutorial

This JSON array shows the items that are available for return from a specific receipt. It details each item's ID, type, quantity, and price.

```json
[
  {
    "id": 1,
    "type": "goods",
    "quantity": "1",
    "returned_quantity": "0",
    "description": "Product A",
    "unit_price": "122",
    "vat_rate_code": "22"
  },
  {
    "id": 2,
    "type": "goods",
    "quantity": "0",
    "returned_quantity": "1",
    "description": "Product B",
    "unit_price": "122",
    "vat_rate_code": "22"
  }
]
```

--------------------------------

### Send Receipt with JavaScript (mTLS)

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/getting_started

This JavaScript example demonstrates sending a receipt using mTLS. It utilizes Node.js's built-in `https` module and requires the certificate and key files.

```javascript
const fs = require('fs');
const https = require('https');

const CERT = fs.readFileSync('/var/certs/pems/A2F4-000001/cr-cert.pem')
const KEY = fs.readFileSync('/var/certs/pems/A2F4-000001/cr-key.pem')
const req = https.request(
  {
    hostname: 'ereceipts-it-sandbox.acubeapi.com',
    headers: {
      "Authorization": "Bearer <Merchant JWT Token>",
      "Content-Type": "application/json"
    },
    port: 444,
    path: '/mf1/receipts',
    method: 'POST',
    cert: CERT,
    key: KEY
  },
  res => {
    let body = '';
    res.on('data', function(data) {
      body += data;
    });
    res.on('end', function() {
      console.log(body);
    })
  }
);
req.write(JSON.stringify({
  "electronic_payment_amount": "244",
  "items": [
    {
      "type": "goods",
      "quantity": "1",
      "description": "Test item",
      "unit_price": "100",
      "vat_rate_code": "22"
    },
    {
      "type": "service",
      "quantity": "1",
      "description": "Test item 2",
      "unit_price": "100",
      "vat_rate_code": "22"
    }
  ]
}));
req.end();

```

--------------------------------

### Void Receipt with POS Proof (JavaScript)

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/void_receipt_tutorial

This JavaScript example demonstrates how to void a receipt using POS proof. It utilizes Node.js's `https` module and requires valid certificate and key files.

```javascript
const fs = require('fs');
const https = require('https');
const CERT = fs.readFileSync('/var/certs/pems/E001-000001/cr-cert.pem')
const KEY = fs.readFileSync('/var/certs/pems/E001-000001/cr-key.pem')
const req = https.request(
  {
    hostname: 'ereceipts-it-sandbox.acubeapi.com',
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer <Merchant JWT Token>"
    },
    port: 444,
    path: '/mf1/receipts/void-with-proof',
    method: 'POST',
    cert: CERT,
    key: KEY
  },
  res => {
    let body = '';
    res.on('data', function(data) {
      body += data;
    });
    res.on('end', function() {
      console.log(body);
    })
  }
);
req.write(JSON.stringify( {
    "items": [
      {
        "type": "goods",
        "quantity": "1",
        "description": "Product",
        "unit_price": "122",
        "vat_rate_code": "22"
      }
    ],
    "proof": "POS",
    "document_datetime": "2025-09-01T10:00:00"
}));
req.end();

```

--------------------------------

### Example: Query Parameter Authentication for Webhooks

Source: https://docs.acubeapi.com/documentation/italy/gov-it/webhooks

When using query parameter authentication, A-CUBE API appends the secret token as a query parameter to the webhook URL. Your endpoint should be prepared to extract and validate this parameter.

```text
?token=mysecret
```

--------------------------------

### JavaScript: Return Items with POS Proof

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/return_receipt_tutorial

This JavaScript example demonstrates how to make a POST request using Node.js 'https' module to return items with POS proof. It includes reading certificate and key files.

```javascript
const fs = require('fs');
const https = require('https');

const CERT = fs.readFileSync('/var/certs/pems/E001-000001/cr-cert.pem')
const KEY = fs.readFileSync('/var/certs/pems/E001-000001/cr-key.pem')
const req = https.request(
  {
    hostname: 'ereceipts-it-sandbox.acubeapi.com',
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer <Merchant JWT Token>",
    },
    port: 444,
    path: '/mf1/receipts/return-with-proof',
    method: 'POST',
    cert: CERT,
    key: KEY
  },
  res => {
    let body = '';
    res.on('data', function(data) {
      body += data;
    });
    res.on('end', function() {
      console.log(body);
    })
  }
);
req.write(JSON.stringify( {
    "proof": "POS",
    "document_datetime": "2025-09-01T10:00:00",
    "items":
    [
        {
            "type": "goods",
            "quantity": "1",
            "description": "Product B",
            "unit_price": "100",
            "vat_rate_code": "22"
        }
    ]
}));
req.end();

```

--------------------------------

### Get Rejected Invoices Count API Example

Source: https://docs.acubeapi.com/documentation/italy/gov-it/invoices/rejected-invoices

Use this endpoint to retrieve the number of rejected invoices that are recoverable and those currently being processed for recovery within a specified date range. Requires the fiscal ID and date interval.

```json
{
  
    "count": <recoverable invoices>,
  
    "pending": <invoices being processed for recovery>
  
}
```

--------------------------------

### Python: Return Items with POS Proof

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/return_receipt_tutorial

Use this Python snippet to send a POST request to the return-with-proof endpoint with POS as the supporting evidence. Ensure your certificate and key paths are correct.

```python
import requests

CERT_PATH = '/var/certs/pems/E001-000001/cr-cert.pem'
KEY_PATH = '/var/certs/pems/E001-000001/cr-key.pem'
response = requests.post(
    'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts/return-with-proof',
    cert=(CERT_PATH, KEY_PATH),
    headers={
      "Authorization": "Bearer <Merchant JWT Token>",
      "Content-Type": "application/json"
    },
    json= {
    "proof": "POS",
    "document_datetime": "2025-09-01T10:00:00",
    "items":
    [
        {
            "type": "goods",
            "quantity": "1",
            "description": "Product B",
            "unit_price": "100",
            "vat_rate_code": "22"
        }
    ]
}
)

```

--------------------------------

### Return Items via Different Device (JavaScript)

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/return_receipt_tutorial

This JavaScript example shows how to make a POST request using Node.js to return items from a sale receipt issued by another device. It utilizes the 'https' module and requires certificate and key files.

```javascript
const fs = require('fs');
const https = require('https');

const CERT = fs.readFileSync('/var/certs/pems/E001-000002/cr-cert.pem')
const KEY = fs.readFileSync('/var/certs/pems/E001-000002/cr-key.pem')
const req = https.request(
  {
    hostname: 'ereceipts-it-sandbox.acubeapi.com',
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer <Merchant JWT Token>",
    },
    port: 444,
    path: '/mf1/receipts/return-via-different-device',
    method: 'POST',
    cert: CERT,
    key: KEY
  },
  res => {
    let body = '';
    res.on('data', function(data) {
      body += data;
    });
    res.on('end', function() {
      console.log(body);
    })
  }
);
req.write(JSON.stringify( {
            "device_id": "E001-000001",
            "items": [
              {
                "type": "goods",
                "quantity": "1",
                "description": "Product B",
                "unit_price": "122",
                "vat_rate_code": "22"
              }
            ],
            "document_number": "0001-0001",
            "document_datetime": "2025-09-01T10:00:00",
        }));
req.end();

```

--------------------------------

### Create Business Registry Configuration

Source: https://docs.acubeapi.com/documentation/italy/gov-it/cassettofiscale

Use this API endpoint to create a new business registry configuration. This is a prerequisite for enabling services for a client or for your own company.

```bash
POST /business-registry-configuration
```

--------------------------------

### Configure Webhooks

Source: https://docs.acubeapi.com/documentation/italy/gov-it/sistemaTS/webhooks

Set up one or more webhooks to receive event notifications from the A-Cube platform. Webhook signatures can be verified using the provided instructions.

```APIDOC
## POST /webhooks

### Description
Configure one or more webhooks to receive event notifications from the A-Cube platform. You can verify the webhook signature by following the instructions provided elsewhere.

### Method
POST

### Endpoint
/webhooks

### Request Body
This endpoint is used to configure webhooks. The specific request body schema is not detailed in this documentation, but it is used to set up the URLs that A-Cube will send POST requests to when events are triggered.

### Response
Information about the success or failure of the webhook configuration is not detailed in this documentation.
```

--------------------------------

### Example NS Notification XML with One Error

Source: https://docs.acubeapi.com/documentation/italy/gov-it/sandbox/sim-customer-notification

This XML example shows an NS notification with a single error, such as an expired signature certificate. It is a simplified structure compared to notifications with multiple validation issues.

```xml
<?xml version="1.0" encoding="UTF-8"?><?xml-stylesheet type="text/xsl" href="NS_v1.0.xsl"?>  

<types:NotificaScarto xmlns:types="http://www.fatturapa.gov.it/sdi/messaggi/v1.0" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" versione="1.0" xsi:schemaLocation="http://www.fatturapa.gov.it/sdi/messaggi/v1.0 MessaggiTypes_v1.0.xsd ">  

  <IdentificativoSdI>111</IdentificativoSdI>  

  <NomeFile>IT01234567890_11111.xml.p7m</NomeFile>  

  <DataOraRicezione>2024-06-12T12:00:00Z</DataOraRicezione>  

  <RiferimentoArchivio>  

    <IdentificativoSdI>100</IdentificativoSdI>  

    <NomeFile>IT01234567890_11111.zip</NomeFile>  

  </RiferimentoArchivio>  

  <ListaErrori>  

    <Errore>  

      <Codice>00100</Codice>  

      <Descrizione>Certificato di firma scaduto</Descrizione>  

    </Errore>  

  </ListaErrori>  

  <MessageId>123456</MessageId>  

  <Note>Note</Note></types:NotificaScarto>  
```

--------------------------------

### Get Receipt

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/getting_started

Retrieves the main data for a specific receipt using its UUID.

```APIDOC
## GET /mf1/receipts/{receipt_uuid}

### Description
Fetches the main data for a specific receipt.

### Method
GET

### Endpoint
/mf1/receipts/{receipt_uuid}

### Parameters
#### Path Parameters
- **receipt_uuid** (string) - Required - The unique identifier of the receipt.

### Response
#### Success Response (200)
- **uuid** (string) - The unique identifier of the receipt.
- **type** (string) - The type of the receipt (e.g., 'sale').
- **total_amount** (string) - The total amount of the receipt.
- **document_number** (string) - The document number of the receipt.
- **document_datetime** (string) - The date and time the document was created.
- **parent_receipt_uuid** (string) - The UUID of the parent receipt, if applicable.
- **is_voidable** (boolean) - Indicates if the receipt can be voided.
- **is_returnable** (boolean) - Indicates if the receipt can be returned.
- **pdf_url** (string) - A URL to the PDF version of the receipt.

### Response Example
```json
{
    "uuid": "39f65b28-b1fa-401b-ad58-0addcaef7162",
    "type": "sale",
    "total_amount": "244",
    "document_number": "0001-0001",
    "document_datetime": "2025-07-22T09:45:22",
    "parent_receipt_uuid": null,
    "is_voidable": true,
    "is_returnable": true,
    "pdf_url": "https://ereceipts-it-sandbox.acubeapi.com/mf1/receipts/39f65b28-b1fa-401b-ad58-0addcaef7162/pdf"
}
```
```

--------------------------------

### Get Expenses

Source: https://docs.acubeapi.com/documentation/italy/gov-it/sistemaTS/get-expenses

Retrieves a collection of expenses. Requires 'Accept: application/json' or 'Accept: application/ld+json' headers.

```APIDOC
## GET /sistema-ts/expenses

### Description
Retrieves a list of expenses. This endpoint requires specific `Accept` headers to be set.

### Method
GET

### Endpoint
/sistema-ts/expenses

### Headers
- **Accept**: application/json
- **Accept**: application/ld+json

### Response
#### Success Response (200)
Returns a JSON array of Expense objects. Each object contains details such as:
- **@id** (string) - Expense Resource Id
- **@type** (string) - Expense Type
- **id** (string) - Expense Uuid
- **requests** (array) - List of requests associated with the expense
- **codice_fiscale_proprietario** (string) - Owner's Fiscal Code
- **codice_fiscale_cittadino** (string) - Citizen's Fiscal Code
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Update timestamp
- **amount** (number) - Expense amount

### Response Example
```json
[
  {
    "@id": "<Expense Resource Id>",
    "@type": "Expense",
    "id": "<Expense Uuid>",
    "requests": [
      {
        "id": "<RequestId>",
        "protocol": <Protocol number>,
        "outcome": "<Operation outcome>",
        "operation_type": "<Operation type>",
        "date": "<Date>",
        "url": "<Recipt URL>",
        "protocol_id": "<Protocol Id>",
        "esito_chiamata": "<Operation outcome>",
        "request_type": "<Request Type>",
        "responses": [
          {
            "id": "<Response Id>",
            "code": <Response Code>,
            "description": "<Description>",
            "type": "<Operation type>",
            "received_at": "<Date>"
          }
        ],
        "requested_at": "<Date>"
      }
    ],
    "codice_fiscale_proprietario": "<Owner Fiscal Code>",
    "codice_fiscale_cittadino": "<Citizen Fiscal Code>",
    "created_at": "<Date>",
    "updated_at": "<Date>",
    "amount": <Amount>
  }
]
```
```

--------------------------------

### Get Receipts for an Expense

Source: https://docs.acubeapi.com/documentation/italy/gov-it/sistemaTS/get-receipts

Fetches a list of expense receipts associated with a specific expense and protocol.

```APIDOC
## GET /sistema-ts/expenses/{ExpenseId}/receipt/{ProtocolId}

### Description
To get a collection of Expense Receipts you have to send a request as described here.
If everything is fine you will get a list of Expense Receipts.

### Method
GET

### Endpoint
/sistema-ts/expenses/{ExpenseId}/receipt/{ProtocolId}

### Parameters
#### Path Parameters
- **ExpenseId** (string) - Required - The ID of the expense.
- **ProtocolId** (string) - Required - The protocol ID associated with the expense.

### Response
#### Success Response (200)
- **protocol** (string) - Protocol number.
- **outcome** (string) - Operation outcome.
- **operation_type** (string) - Operation type.
- **date** (string) - Date of the operation.
- **url** (string) - URL of the receipt.
```

--------------------------------

### Get Receipt Details

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/getting_started

Retrieves the complete fiscal breakdown of a receipt, including totals and line items.

```APIDOC
## GET /mf1/receipts/{receipt_uuid}/details

### Description
Fetches the complete fiscal breakdown for a specific receipt, including detailed totals and line items.

### Method
GET

### Endpoint
/mf1/receipts/{receipt_uuid}/details

### Parameters
#### Path Parameters
- **receipt_uuid** (string) - Required - The unique identifier of the receipt.

### Response
#### Success Response (200)
- **uuid** (string) - The unique identifier of the receipt.
- **type** (string) - The type of the receipt (e.g., 'sale').
- **total_amount** (string) - The total amount of the receipt.
- **document_number** (string) - The document number of the receipt.
- **document_datetime** (string) - The date and time the document was created.
- **parent_receipt_uuid** (string) - The UUID of the parent receipt, if applicable.
- **is_voidable** (boolean) - Indicates if the receipt can be voided.
- **is_returnable** (boolean) - Indicates if the receipt can be returned.
- **pdf_url** (string) - A URL to the PDF version of the receipt.
- **total_taxable_amount** (string) - The total taxable amount.
- **total_uncollected_amount** (string) - The total uncollected amount.
- **total_vat_amount** (string) - The total VAT amount.
- **total_discount** (string) - The total discount applied.
- **items** (array) - An array of item objects detailing the receipt items.
  - **type** (string) - The type of the item (e.g., 'goods', 'service').
  - **quantity** (string) - The quantity of the item.
  - **description** (string) - The description of the item.
  - **unit_price** (string) - The unit price of the item.
  - **vat_rate_code** (string) - The VAT rate code applied to the item.
  - **simplified_vat_allocation** (boolean) - Indicates if simplified VAT allocation is used.
  - **discount** (string) - The discount applied to the item.
  - **prepaid_or_voucher** (boolean) - Indicates if the item was prepaid or a voucher.
  - **complimentary** (boolean) - Indicates if the item was complimentary.
- **customer_lottery_code** (string) - The customer lottery code, if applicable.
- **cashier_uuid** (string) - The UUID of the cashier, if applicable.

### Response Example
```json
{
    "uuid": "39f65b28-b1fa-401b-ad58-0addcaef7162",
    "type": "sale",
    "total_amount": "244",
    "document_number": "0001-0001",
    "document_datetime": "2025-07-22T09:45:22",
    "parent_receipt_uuid": null,
    "is_voidable": true,
    "is_returnable": true,
    "pdf_url": "https://ereceipts-it-sandbox.acubeapi.com/mf1/receipts/39f65b28-b1fa-401b-ad58-0addcaef7162/pdf",
    "total_taxable_amount": "200",
    "total_uncollected_amount": "0",
    "total_vat_amount": "44",
    "total_discount": "0",
    "items": [
        {
            "type": "goods",
            "quantity": "1",
            "description": "Test item",
            "unit_price": "100",
            "vat_rate_code": "22",
            "simplified_vat_allocation": false,
            "discount": "0",
            "prepaid_or_voucher": false,
            "complimentary": false
        },
        {
            "type": "service",
            "quantity": "1",
            "description": "Test item 2",
            "unit_price": "100",
            "vat_rate_code": "22",
            "simplified_vat_allocation": false,
            "discount": "0",
            "prepaid_or_voucher": false,
            "complimentary": false
        }
    ],
    "customer_lottery_code": null,
    "cashier_uuid": null
}
```
```

--------------------------------

### Issue a Sale Receipt (Python)

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/void_receipt_tutorial

Use this Python snippet to issue a sale receipt. Ensure you have the correct certificate and key paths.

```python
import requests


CERT_PATH = '/var/certs/pems/E001-000001/cr-cert.pem'
KEY_PATH = '/var/certs/pems/E001-000001/cr-key.pem'
response = requests.post(
    'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts',
    cert=(CERT_PATH, KEY_PATH),
    headers={
      "Authorization": "Bearer <Merchant JWT Token>",
      "Content-Type": "application/json"
    },
    json={
    "electronic_payment_amount": "122",
		"items": [
      {
        "type": "goods",
        "quantity": "1",
        "description": "Product",
        "unit_price": "122",
        "vat_rate_code": "22"
      }
    ]
  }
)



```

--------------------------------

### Get returnable items for a receipt

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/return_receipt_tutorial

This section shows how to retrieve a list of items that can be returned for a given receipt.

```APIDOC
## GET /mf1/receipts/{receipt_uuid}/returnable-items

### Description
Retrieves a list of items that are eligible for return from a specific receipt.

### Method
GET

### Endpoint
/mf1/receipts/{receipt_uuid}/returnable-items

### Parameters
#### Path Parameters
- **receipt_uuid** (string) - Required - The UUID of the original receipt.

### Response
#### Success Response (200)
- **id** (integer) - The ID of the item.
- **type** (string) - The type of the item (e.g., 'goods').
- **quantity** (string) - The original quantity of the item.
- **returned_quantity** (string) - The quantity of the item already returned.
- **description** (string) - A description of the item.
- **unit_price** (string) - The unit price of the item.
- **vat_rate_code** (string) - The VAT rate code applicable to the item.

#### Response Example
```json
[
  {
    "id": 1,
    "type": "goods",
    "quantity": "1",
    "returned_quantity": "0",
    "description": "Product A",
    "unit_price": "122",
    "vat_rate_code": "22"
  },
  {
    "id": 2,
    "type": "goods",
    "quantity": "0",
    "returned_quantity": "1",
    "description": "Product B",
    "unit_price": "122",
    "vat_rate_code": "22"
  }
]
```
```

--------------------------------

### POST /invoice-extract API Request with Configuration

Source: https://docs.acubeapi.com/documentation/italy/gov-it/invoices/invoice-extract

This example demonstrates how to send a PDF file along with a conversion configuration JSON to the Invoice Extract API. The configuration allows customization of VAT rate and currency conversion.

```curl
curl --location 'https://api-sandbox.acubeapi.com/invoice-extract' \

--header 'Authorization: Bearer YOUR TOKEN HERE' \

--form 'file=@"/path/to/file.pdf"' \

--form 'conversion_configuration="{\"default_vat_rate\":0,\"convert_amounts\":false}"'
```

--------------------------------

### GET /invoice-extract/{uuid}/result

Source: https://docs.acubeapi.com/documentation/italy/gov-it/invoices/invoice-extract

Obtain the converted FatturaPA XML or JSON invoice once the job status is 'success'.

```APIDOC
## GET /invoice-extract/{uuid}/result

### Description
Retrieve the converted invoice in either XML or JSON format after the job status has successfully completed. The desired format is determined by the `Accept` header.

### Method
GET

### Endpoint
/invoice-extract/{uuid}/result

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the completed invoice conversion job.

#### Headers
- **Accept** (string) - Required - Specifies the desired response format. Use `application/xml` for XML or `application/json` for JSON.

### Response
#### Success Response (200)
- The response body will contain the converted invoice in either XML or JSON format, depending on the `Accept` header.

#### Response Example (XML)
```xml
<!-- Example XML response -->
<Invoice ...>
  ...
</Invoice>
```

#### Response Example (JSON)
```json
{
  "Invoice": {
    "@version": "1.0",
    "@xmlns": "http://www.fatturapa.gov.it/sdi/",
    "...": "..."
  }
}
```
```

--------------------------------

### GET /invoice-extract/{uuid}

Source: https://docs.acubeapi.com/documentation/italy/gov-it/invoices/invoice-extract

Retrieve the status of an ongoing invoice conversion job using its unique identifier (UUID).

```APIDOC
## GET /invoice-extract/{uuid}

### Description
Check the status of a previously submitted invoice conversion job using its UUID. This endpoint is used to monitor the progress until the `job_status` indicates completion (`success`).

### Method
GET

### Endpoint
/invoice-extract/{uuid}

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the invoice conversion job.

### Response
#### Success Response (200)
- **uuid** (string) - The unique identifier of the job.
- **acquisition_date** (string) - The date and time when the job was acquired.
- **filename** (string) - The name of the original PDF file.
- **job_status** (string) - The current status of the job (e.g., `waiting`, `success`, `error`).
- **pages** (null) - Currently unused.

#### Response Example
```json
{
    "uuid": "unique job identifier",
    "acquisition_date": "date time",
    "filename": "string",
    "job_status": "success",
    "pages": null
}
```
```

--------------------------------

### Schedule Daily Invoice Download

Source: https://docs.acubeapi.com/documentation/italy/gov-it/invoices/massive-download

Schedule a daily download of invoices issued or received in the past 3 days. The download runs once per day at 03:00 UTC.

```bash
POST /schedule/invoice-download/{fiscal_id}

{
  "download_archive": false
}
```

--------------------------------

### Get Invoice Receipt

Source: https://docs.acubeapi.com/documentation/italy/gov-it/legal-storage/invoices

Retrieves the signed XML receipt that certifies an invoice has been processed by the legal storage system.

```APIDOC
## GET /preserved-documents/{uuid}/receipt

### Description
Retrieves the signed XML receipt for a legally stored invoice, confirming its processing.

### Method
GET

### Endpoint
/preserved-documents/{uuid}/receipt

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the preserved document (invoice).

### Response
#### Success Response (200)
- **receipt** (string) - The signed XML document certifying the invoice has been processed.
```

--------------------------------

### Configure Webhook

Source: https://docs.acubeapi.com/documentation/italy/gov-it/smart-receipts/webhooks

Use this API endpoint to set up a new webhook subscription. Smart Receipts will send POST requests to your configured URL when events occur.

```APIDOC
## POST /webhooks

### Description
Configures a webhook subscription to receive event notifications.

### Method
POST

### Endpoint
/webhooks

### Parameters
#### Request Body
- **url** (string) - Required - The URL to which webhook events will be sent.
- **events** (array of strings) - Optional - A list of event types to subscribe to. If not provided, all events will be sent.

### Request Example
{
  "url": "https://your-webhook-url.com/callback",
  "events": ["receipt", "receipt-error"]
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created webhook subscription.
- **url** (string) - The configured webhook URL.
- **events** (array of strings) - The list of subscribed event types.

#### Response Example
{
  "id": "wh_abc123xyz",
  "url": "https://your-webhook-url.com/callback",
  "events": ["receipt", "receipt-error"]
}
```

--------------------------------

### Query Returnable Items (Bash)

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/return_receipt_tutorial

Query the system to retrieve the returnable amount for each item of a sale receipt using curl. Requires certificate and key for authentication.

```bash
curl -X GET https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts/18a681da-a868-47ba-a931-2f702474c3d1/returnable-items \
-H 'Content-Type: application/json' \
--cert /var/certs/pems/E001-000001/cr-cert.pem \
--key /var/certs/pems/E001-000001/cr-key.pem

```

--------------------------------

### Get PDF Receipt Details

Source: https://docs.acubeapi.com/documentation/italy/gov-it/smart-receipts/print

Retrieves the PDF version of a receipt. The layout is the default one provided by the Tax Authority.

```APIDOC
## GET /receipts/{id}/details

### Description
Retrieves the PDF version of a receipt.

### Method
GET

### Endpoint
/receipts/{id}/details

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the receipt.

### Response
#### Success Response (200)
- The response will be a PDF file of the receipt.
```

--------------------------------

### Return Items via Different Device (cURL)

Source: https://docs.acubeapi.com/documentation/italy/ereceipts/return_receipt_tutorial

This cURL command demonstrates how to perform a POST request to return items from a sale receipt issued by a different device. It includes necessary headers, data payload, and certificate/key paths.

```bash
curl -X POST https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts/return-via-different-device \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Merchant JWT Token>' \
-d '{"device_id":"E001-000001","items":[{"type": "goods", "quantity":"1", "description": "Product B", "unit_price": "122", "vat_rate_code": "22"}], "document_number": "0001-0001", "document_datetime": "2025-09-01T10:00:00"}' \
--cert /var/certs/pems/E001-000002/cr-cert.pem \
--key /var/certs/pems/E001-000002/cr-key.pem

```