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

  • Supplier : The service supplier that delivers certified software to the merchant.
  • Merchant : The business owner or end-user who uses the software at their point of sale to record transactions.
  • Point of Sale : The physical or digital location where the merchant conducts sales and records transactions.
  • Cash Register : The device or software component located at a point of sale that is used to record transactions.
  • MF1 : The software module responsible for capturing transaction data at the point of sale 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 Revenue Agency.

Tutorial as a Supplier

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

1. Create an Account

Sign up for an account on the A-Cube platform.

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.

Copy
Copied
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 at their point of sale 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 user for the merchant using the following API endpoint:

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

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

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 point of sale

Create a new point of sale using the following API endpoint:

Copy
Copied
POST https://ereceipts-it-sandbox.acubeapi.com/mf2/point-of-sales
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 point of sale physical address is inherited from the merchant address created in step 3.

You will need them to activate the point of sale in the next step.

info

Serial number and registration key can be retrieved later using the API GET /mf1/point-of-sales/{serial_number}.

5. Authenticate as Merchant

Now the merchant created in step 3 can log in and obtain a Merchant JWT Token.

Copy
Copied
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 point of sale

The merchant can now activate the point of sale using the registration key obtained in step 4.

Please note that the serial number you received at step 4 is used in the URL of the API endpoint to identify the point of sale.

Copy
Copied
POST https://ereceipts-it-sandbox.acubeapi.com/mf1/point-of-sales/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

As a merchant now you can create a new cash register for the point of sale.

The cash register must authenticate to MF1 using a mTLS (mutual TLS) certificate.

Copy
Copied
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 -----...."
}

This API call will activate the license for the cash register and generate a new mTLS certificate.

This certificate is used to authenticate the cash register to the MF1 API and identify the cash register in the system.

Store the content of the mtls_certificate field in your cash register storage. For example: store it to /var/certs/pos/A2F4-000001/cashregister.pem and give it the right permissions so that only your cash register software can read it.

8. Send a receipt

The cash register can now connect using the mTLS certificate to emit a receipt.

You must configure your API client to use the mTLS certificate generated in the previous step.

info

All the communications to MF1 using the mTLS certificate must be done over port 444

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

See below some examples of how to send a receipt sending the mTLS certificate using different programming languages.

BashPHPPythonJavaScript
Copy
Copied
curl -X POST https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt  \
-H 'Content-Type: application/json' \
-d '{"electronic_payment_amount":"244","items":[{"good_or_service":"B","quantity":"1","description":"Test item","unit_price":"100","vat_rate_code":"22"},{"good_or_service":"S","quantity":"1","description":"Test item 2","unit_price":"100","vat_rate_code":"22"}]}' \
--cert /var/certs/pos/A2F4-000001/cashregister.pem \
--key /var/certs/pos/A2F4-000001/cashregister.pem
Copy
Copied
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode('{
    "electronic_payment_amount": "244",
    "items": [
      {
        "good_or_service": "B",
        "quantity": "1",
        "description": "Test item",
        "unit_price": "100",
        "vat_rate_code": "22"
      },
      {
        "good_or_service": "S",
        "quantity": "1",
        "description": "Test item 2",
        "unit_price": "100",
        "vat_rate_code": "22"
      }
    ]
}'));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json']);
curl_setopt($ch, CURLOPT_SSLCERT, '/var/certs/pos/A2F4-000001/cashregister.pem');
curl_setopt($ch, CURLOPT_SSLKEY, '/var/certs/pos/A2F4-000001/cashregister.pem');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);
Copy
Copied
import requests

CERT_PATH = '/var/certs/pos/A2F4-000001/cashregister.pem'
KEY_PATH = '/var/certs/pos/A2F4-000001/cashregister.pem'
response = requests.post(
    'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipt',
    cert=(CERT_PATH, KEY_PATH),
    json={
    "electronic_payment_amount": "244",
		"items": [
      {
        "good_or_service": "B",
        "quantity": "1",
        "description": "Test item",
        "unit_price": "100",
        "vat_rate_code": "22"
      },
      {
        "good_or_service": "S",
        "quantity": "1",
        "description": "Test item 2",
        "unit_price": "100",
        "vat_rate_code": "22"
      }
    ]
  }
)
Copy
Copied
const fs = require('fs');
const https = require('https');

const CERT = fs.readFileSync('/var/certs/pos/A2F4-000001/cashregister.pem')
const KEY = fs.readFileSync('/var/certs/pos/A2F4-000001/cashregister.pem')
const req = https.request(
  {
    hostname: 'ereceipts-it-sandbox.acubeapi.com',
    headers: {
      "Content-Type": "application/json"
    },
    port: 444,
    path: '/mf1/receipt',
    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": [
    {
      "good_or_service": "B",
      "quantity": "1",
      "description": "Test item",
      "unit_price": "100",
      "vat_rate_code": "22"
    },
    {
      "good_or_service": "S",
      "quantity": "1",
      "description": "Test item 2",
      "unit_price": "100",
      "vat_rate_code": "22"
    }
  ]
}));
req.end();

You will receive the following response:

Copy
Copied
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
}

9. Retrieve the receipt

Now you can query the API to get the receipt data:

Copy
Copied
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

}

The receipt details:

Copy
Copied
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",
    "fiscal_id": "12345678901",
    "total_taxable_amount": "200",
    "total_uncollected_amount": "0",
    "deductible_amount": "0",
    "total_vat_amount": "44",
    "total_discount": "0",
    "items":
    [
        {
            "good_or_service": "B",
            "quantity": "1",
            "description": "Test item",
            "unit_price": "100",
            "vat_rate_code": "22",
            "simplified_vat_allocation": false,
            "discount": "0",
            "is_down_payment_or_voucher_redemption": false,
            "complimentary": false
        },
        {
            "good_or_service": "S",
            "quantity": "1",
            "description": "Test item 2",
            "unit_price": "100",
            "vat_rate_code": "22",
            "simplified_vat_allocation": false,
            "discount": "0",
            "is_down_payment_or_voucher_redemption": false,
            "complimentary": false
        }
    ],
    "parent_receipt_uuid": null
}

Or you can get the PDF by sending the very same request with the Accept header set to application/pdf.:

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