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.
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:
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:
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.
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.
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.
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
See below some examples of how to send a receipt sending the mTLS
certificate using different programming languages.
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
$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);
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"
}
]
}
)
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:
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:
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:
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
.:
GET https://ereceipts-it-sandbox.acubeapi.com/mf1/receipts/39f65b28-b1fa-401b-ad58-0addcaef7162/details
Accept: application/pdf
Authorization: Bearer <Merchant JWT Token>