Getting started

This document will guide you through the process of integrating the A-Cube "Corrispettivi" solution into your existing systems.

All API endpoints in this guide refer to the sandbox environment, a testing setup that closely replicates the production environment.

The sandbox servers used in this guide are:

Take a look at the introduction to learn more about the context and the A-Cube "Corrispettivi" solution.

Glossary

Term	Definition
Supplier	The service supplier that delivers certified software to the merchant.
Merchant	The business owner or end-user who uses the software to record transactions.
PEM	The physical or digital location where the merchant conducts sales and records transactions.
Cash Register	The device or software component associated to a PEM that is used to record transactions.
MF1	The software module responsible for capturing transaction data and creating a sealed acquisition package by applying a first electronic signature.
MF2	The software module that ensures secure, immutable storage of acquisition packages generated by MF1 and handles the final transmission of fiscal data to the Italian Tax Authority.

Tutorial as a Supplier

As a supplier, you can start using the A-Cube "Corrispettivi" solution by following these steps.

1. Create an Account

info

You can obtain a free sandbox account to test the solution here.

Write to A-Cube support to activate the "Corrispettivi" product.

2. Authenticate as Supplier

Once you have your username and password, you can get a Supplier JWT Token by following the instructions in the Authentication section.

POST https://common-sandbox.api.acubeapi.com/login
Content-Type: application/json
Accept: application/json

{
    "email": "your@email.com",
    "password": "your password"
}

Response 200

{
    "token": "<jwt content>"
}

3. Create a new merchant account

The merchant is the business owner or end-user who will use the software to record transactions, generate receipts for customers, and fulfill their legal obligation to memorize and transmit fiscal data to the authorities.

You can create a new merchant user calling the Create Merchant endpoint:

POST https://ereceipts-it-sandbox.acubeapi.com/mf2/merchants
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Supplier JWT Token>

{
  "vat_number": "12345678901",
  "address": {
    "street_address": "street name",
    "street_number": "xx",
    "zip_code": "00000",
    "city": "City",
    "province": "XX"
  },
  "business_name": "business name",
  "email": "merchant@example.com",
  "password": "MerchantP4$$w0rd"
}


Response 201

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "vat_number": "12345678901",
  "fiscal_code": "XXXXXX00A00X000X",
  "address": {
    "street_address": "street name",
    "street_number": "xx",
    "zip_code": "00000",
    "city": "City",
    "province": "XX"
  },
  "business_name": "foo bar",
  "first_name": "first name",
  "last_name": "last name",
  "email": "foobar@example.com"
}

4. Create a new PEM

Create a new PEM by calling the Create PEM endpoint:

POST https://ereceipts-it-sandbox.acubeapi.com/mf2/pems
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Supplier JWT Token>

{
  "merchant_uuid": "836b70aa-239b-4c8d-b654-0f5a9a4d133a"
}

Response 201

{
  "serial_number": "A2F4-000001",
  "registration_key": "527462046048ce9bc72e64d77b975fdafd448825"
}

The PEM's physical address is inherited from the merchant address created in step 3.

The Merchant will be required to activate the PEM in the following step.

info

Serial number and registration key can be retrieved later using the endpoint GET /mf1/pems/{serial_number}.

5. Authenticate as Merchant

At this point, the merchant created in step 3 can sign in to receive a Merchant JWT Token.

POST https://common-sandbox.api.acubeapi.com/login
Content-Type: application/json
Accept: application/json

{
    "email": "merchant@example.com",
    "password": "merchant password"
}

Response 200

{
    "token": "Merchant JWT Token"
}

6. Activate the PEM

The merchant can now activate the PEM by using the serial number obtained in step 4 and making a request to the PEM Activation endpoint.

POST https://ereceipts-it-sandbox.acubeapi.com/mf1/pems/A2F4-000001/activation/
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Merchant JWT Token>

{
  "registration_key": "527462046048ce9bc72e64d77b975fdafd448825"
}

Response 202

info

The activation process may take a few seconds in production while it is instantaneous in the sandbox environment.

7. Create a new Cash Register

At this stage, the merchant can register a new cash register and associate it with the previously activated PEM.

This endpoint also returns the mTLS (mutual TLS) certificate and private key for the cash register.

POST https://ereceipts-it-sandbox.acubeapi.com/mf1/cash-register
Content-Type: application/json
Accept: application/json
Authorization: Bearer <Merchant JWT Token>

{
  "pem_serial_number": "A2F4-000001",
  "name": "Cash register first floor"
}

Response 201

{
  "uuid": "f69023bf-ee89-4d66-a7e7-9a65e4f365da",
  "pem_serial_number": "A2F4-000001",
  "name": "Cash register first floor",
  "mtls_certificate": "----- BEGIN CERTIFICATE -----....",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----..."
}

The returned certificate identifies the cash register and is used for all fiscal operation endpoints that require mTLS authentication.

Store the contents of the mtls_certificate and private_key fields in your cash register storage. For example: store the certificate in /var/certs/pems/A2F4-000001/cr-cert.pem and the private key in /var/certs/pems/A2F4-000001/cr-key.pem and give them the right permissions so that only your cash register software can read it.

info

When you receive mtls_certificate and private_key, newline characters are escaped as \n. Before writing these values to disk, replace each \n with an actual newline character.

8. Send a receipt

The cash register can now issue receipts.

To call this endpoint, configure your API client with the mTLS certificate and private key generated in the previous step.

info

MF1 endpoints that use mTLS are exposed on port 444.

i.e. https://ereceipts-it-sandbox.acubeapi.com:444

The following examples show how to send a receipt with mTLS authentication in different programming languages. For complete request and response details, see Create Sale Receipt.

Python
JavaScript
Bash
PHP

import requests

CERT_PATH = '/var/certs/pems/A2F4-000001/cr-cert.pem'
KEY_PATH = '/var/certs/pems/A2F4-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": "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"
      }
    ]
  }
)

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();

curl -X POST https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts  \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Merchant JWT Token>' \
-d '{"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"}]}' \
--cert /var/certs/pems/A2F4-000001/cr-cert.pem \
--key /var/certs/pems/A2F4-000001/cr-key.pem

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode('{
    "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"
      }
    ]
}'));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json', 'Authorization:Bearer <Merchant JWT Token>']);
curl_setopt($ch, CURLOPT_SSLCERT, '/var/certs/pems/A2F4-000001/cr-cert.pem');
curl_setopt($ch, CURLOPT_SSLKEY, '/var/certs/pems/A2F4-000001/cr-key.pem');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

Example response:

Response 201

{
    "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"
}

9. Retrieve the receipt

After the receipt is created, you can retrieve it by receipt_uuid.

Use Get Receipt to fetch the main receipt data:

GET https://ereceipts-it-sandbox.acubeapi.com/mf1/receipts/39f65b28-b1fa-401b-ad58-0addcaef7162
Accept: application/json
Authorization: Bearer <Merchant JWT Token>

Response 200
{
    "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"
}

Use Get Receipt Details to fetch the complete fiscal breakdown, including totals and line items:

GET https://ereceipts-it-sandbox.acubeapi.com/mf1/receipts/39f65b28-b1fa-401b-ad58-0addcaef7162/details
Accept: application/json
Authorization: Bearer <Merchant JWT Token>

Response 200
{
    "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
}

Glossary​

Tutorial as a Supplier​

1. Create an Account​

2. Authenticate as Supplier​

3. Create a new merchant account​

4. Create a new PEM​

5. Authenticate as Merchant​

6. Activate the PEM​

7. Create a new Cash Register​

8. Send a receipt​

9. Retrieve the receipt​

Glossary

Tutorial as a Supplier

1. Create an Account

2. Authenticate as Supplier

3. Create a new merchant account

4. Create a new PEM

5. Authenticate as Merchant

6. Activate the PEM

7. Create a new Cash Register

8. Send a receipt

9. Retrieve the receipt