Quick Start
Documentation is released in preview, is not final, and may be subject to changes. Sandbox and Production environments will be available soon.
This tutorial runs entirely in the SK sandbox. You will authenticate, create a sandbox Legal Entity that will automatically be set in status active if not already registered in the Peppol Test Network, send an invoice, and verify how an incoming invoice is received.
Sandbox API URL: https://sk-sandbox.api.acubeapi.com
No production credentials or real fiscal documents are used in this tutorial.
You will complete four steps:
- Get sandbox access and authenticate.
- Onboard a new Legal Entity.
- Send an invoice.
- Simulate the reception of an incoming invoice.
1. Get sandbox access and authenticate
Create a free sandbox account. To receive an access token, please follow the authentication guide
If the received token does not grant access to the SK API, contact A-Cube support.
2. Onboard a new legal entity
A legal entity represents the SK taxpayer that will send or receive documents.
In the production environment, the Legal Entity must initiate the onboarding process in A-Cube and complete the registration process in the Slovak Tax Authority portal to confirm the link between the Legal Entity and A-Cube. Only after doing that, the Legal Entity can be registered in the Peppol Network.
In the sandbox environment, the Legal Entity will automatically be set in status active if not already registered in the Peppol Test Network.
2.1. Create a new legal entity in A-Cube.
Use POST /legal-entities to create a legal entity in A-Cube.
The {{jwt}} should be replaced with the token received from authentication step.
The taxId field refers to the DIČ (Tax ID) of the Legal Entity, the icDph field refers to the IČ DPH (Company Identification Number for VAT), the ico field refers to IČO (Company Identification Number).
The {{validTaxId}}, {{validIco}}, {{validIcDph}} parameters should be replaced with valid values only. The format of the parameters will be validated before actually registering the Legal Entity: if the validation fails, an error message will be provided.
POST /legal-entities
Authorization: Bearer {{jwt}}
Content-Type: application/json
Accept: application/json
{
"taxId": "{validTaxId}",
"ico" : "{validIco}",
"icDph": "{validIcDph}",
"name": "A-Cube Test Company",
"email": "test@acme.test",
"phoneNumber": "+421900000000",
"country": "SK",
"address": "Staromestská 123",
"city": "Bratislava",
"zipCode": "811 06",
"config": {
"supplierInvoiceEnabled": true,
"customerInvoiceEnabled": true
}
}
{
"uuid": "01a047df-a310-75f9-8176-b9370c82a850",
"taxId": "{validTaxId}",
"ico": "{validIco}",
"icDph": "{validIcDph}",
"status": "pending",
"name": "A-Cube Test Company",
"email": "test@acme.test",
"phoneNumber": "+421900000000",
"country": "SK",
"address": "Staromestská 123",
"city": "Bratislava",
"zipCode": "811 06",
"finalizeOnboardingUrl": "/initiate-onboarding/01a047df-a310-75f9-8176-b9370c82a850",
"createdAt": "2026-08-28T10:17:13+00:00",
"updatedAt": "2026-08-28T10:17:13+00:00",
"config": {
"supplierInvoiceEnabled": true,
"customerInvoiceEnabled": true
}
}
Please note that ico and icDph are optional parameters. If they are not provided, the Legal Entity can only receive invoices from the Peppol network and the supplierInvoiceEnabled parameter must be set to false to complete the registration.
3. Simulate an incoming invoice
3.1 Create a Second Legal Entity
There is no public endpoint for directly injecting an incoming invoice. To test invoice reception, send an invoice from one sandbox legal entity to another.
Please repeat the steps of onboarding a new legal entity using different DIČ (taxId) to create a second legal entity. Save the newly generated legal entity DIČ as a {{customer_taxId}}.
4. Send an invoice
4.1 Send a Peppol BIS Billing 3.0 Invoice
Prepare a valid Peppol BIS Billing 3.0 XML invoice and send it as a request body to POST /invoices
Before sending the request, remember to replace {{supplier_taxId}} & {{customer_taxId}} accordingly with the Legal Entity DIČs you created in the previous steps.
POST /invoices
Authorization: Bearer {{jwt}}
<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
<cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
<cbc:ID>Invoice-ID1</cbc:ID>
<cbc:IssueDate>2017-11-17</cbc:IssueDate>
<cbc:DueDate>2017-12-01</cbc:DueDate>
<cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
<cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
<cbc:AccountingCost>4025:123:4343</cbc:AccountingCost>
<cbc:BuyerReference>0150abc</cbc:BuyerReference>
<cac:AccountingSupplierParty>
<cac:Party>
<cbc:EndpointID schemeID="0245">{{supplier_taxId}}</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID>{{supplier_taxId}}</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Sender Trading Name</cbc:Name>
</cac:PartyName>
<cac:PostalAddress>
<cbc:StreetName>Main street 1</cbc:StreetName>
<cbc:AdditionalStreetName>Postbox 123</cbc:AdditionalStreetName>
<cbc:CityName>Bratislava</cbc:CityName>
<cbc:PostalZone>12 345</cbc:PostalZone>
<cac:Country>
<cbc:IdentificationCode>SK</cbc:IdentificationCode>
</cac:Country>
</cac:PostalAddress>
<cac:PartyTaxScheme>
<cbc:CompanyID>SK1232434123</cbc:CompanyID>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:PartyTaxScheme>
<cac:PartyLegalEntity>
<cbc:RegistrationName>Sender Official Name</cbc:RegistrationName>
<cbc:CompanyID>SK1231231231</cbc:CompanyID>
</cac:PartyLegalEntity>
</cac:Party>
</cac:AccountingSupplierParty>
<cac:AccountingCustomerParty>
<cac:Party>
<cbc:EndpointID schemeID="0245">{{customer_taxId}}</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID>{{customer_taxId}}</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Recipient Trading Name</cbc:Name>
</cac:PartyName>
<cac:PostalAddress>
<cbc:StreetName>Other street 1</cbc:StreetName>
<cbc:AdditionalStreetName>Po box 878</cbc:AdditionalStreetName>
<cbc:CityName>Bratislava</cbc:CityName>
<cbc:PostalZone>456 34</cbc:PostalZone>
<cac:Country>
<cbc:IdentificationCode>SK</cbc:IdentificationCode>
</cac:Country>
</cac:PostalAddress>
<cac:PartyTaxScheme>
<cbc:CompanyID>SK3213213213</cbc:CompanyID>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:PartyTaxScheme>
<cac:PartyLegalEntity>
<cbc:RegistrationName>Recipient Official Name</cbc:RegistrationName>
<cbc:CompanyID schemeID="0183">39937423947</cbc:CompanyID>
</cac:PartyLegalEntity>
<cac:Contact>
<cbc:Name>Lisa Johnson</cbc:Name>
<cbc:Telephone>23434234</cbc:Telephone>
<cbc:ElectronicMail>lj@buyer.sk</cbc:ElectronicMail>
</cac:Contact>
</cac:Party>
</cac:AccountingCustomerParty>
<cac:Delivery>
<cbc:ActualDeliveryDate>2017-11-01</cbc:ActualDeliveryDate>
<cac:DeliveryLocation>
<cbc:ID schemeID="0088">9483759475923478</cbc:ID>
<cac:Address>
<cbc:StreetName>Delivery street 2</cbc:StreetName>
<cbc:AdditionalStreetName>Building 56</cbc:AdditionalStreetName>
<cbc:CityName>Bratislava</cbc:CityName>
<cbc:PostalZone>32122</cbc:PostalZone>
<cac:Country>
<cbc:IdentificationCode>SK</cbc:IdentificationCode>
</cac:Country>
</cac:Address>
</cac:DeliveryLocation>
<cac:DeliveryParty>
<cac:PartyName>
<cbc:Name>Delivery party Name</cbc:Name>
</cac:PartyName>
</cac:DeliveryParty>
</cac:Delivery>
<cac:PaymentMeans>
<cbc:PaymentMeansCode name="Credit transfer">30</cbc:PaymentMeansCode>
<cbc:PaymentID>Snippet1</cbc:PaymentID>
<cac:PayeeFinancialAccount>
<cbc:ID>IBAN32423940</cbc:ID>
<cbc:Name>AccountName</cbc:Name>
<cac:FinancialInstitutionBranch>
<cbc:ID>BIC324098</cbc:ID>
</cac:FinancialInstitutionBranch>
</cac:PayeeFinancialAccount>
</cac:PaymentMeans>
<cac:PaymentTerms>
<cbc:Note>Payment within 10 days, 2% discount</cbc:Note>
</cac:PaymentTerms>
<cac:AllowanceCharge>
<cbc:ChargeIndicator>true</cbc:ChargeIndicator>
<cbc:AllowanceChargeReason>Insurance</cbc:AllowanceChargeReason>
<cbc:Amount currencyID="EUR">25</cbc:Amount>
<cac:TaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>25.0</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:TaxCategory>
</cac:AllowanceCharge>
<cac:TaxTotal>
<cbc:TaxAmount currencyID="EUR">331.25</cbc:TaxAmount>
<cac:TaxSubtotal>
<cbc:TaxableAmount currencyID="EUR">1325</cbc:TaxableAmount>
<cbc:TaxAmount currencyID="EUR">331.25</cbc:TaxAmount>
<cac:TaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>25.0</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:TaxCategory>
</cac:TaxSubtotal>
</cac:TaxTotal>
<cac:LegalMonetaryTotal>
<cbc:LineExtensionAmount currencyID="EUR">1300</cbc:LineExtensionAmount>
<cbc:TaxExclusiveAmount currencyID="EUR">1325</cbc:TaxExclusiveAmount>
<cbc:TaxInclusiveAmount currencyID="EUR">1656.25</cbc:TaxInclusiveAmount>
<cbc:ChargeTotalAmount currencyID="EUR">25</cbc:ChargeTotalAmount>
<cbc:PayableAmount currencyID="EUR">1656.25</cbc:PayableAmount>
</cac:LegalMonetaryTotal>
<cac:InvoiceLine>
<cbc:ID>1</cbc:ID>
<cbc:InvoicedQuantity unitCode="DAY">7</cbc:InvoicedQuantity>
<cbc:LineExtensionAmount currencyID= "EUR">2800</cbc:LineExtensionAmount>
<cbc:AccountingCost>Konteringsstreng</cbc:AccountingCost>
<cac:OrderLineReference>
<cbc:LineID>123</cbc:LineID>
</cac:OrderLineReference>
<cac:Item>
<cbc:Description>Description of item</cbc:Description>
<cbc:Name>item name</cbc:Name>
<cac:StandardItemIdentification>
<cbc:ID schemeID="0088">21382183120983</cbc:ID>
</cac:StandardItemIdentification>
<cac:OriginCountry>
<cbc:IdentificationCode>NO</cbc:IdentificationCode>
</cac:OriginCountry>
<cac:CommodityClassification>
<cbc:ItemClassificationCode listID="SRV">09348023</cbc:ItemClassificationCode>
</cac:CommodityClassification>
<cac:ClassifiedTaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>25.0</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:ClassifiedTaxCategory>
</cac:Item>
<cac:Price>
<cbc:PriceAmount currencyID="EUR">400</cbc:PriceAmount>
</cac:Price>
</cac:InvoiceLine>
<cac:InvoiceLine>
<cbc:ID>2</cbc:ID>
<cbc:InvoicedQuantity unitCode="DAY">-3</cbc:InvoicedQuantity>
<cbc:LineExtensionAmount currencyID="EUR">-1500</cbc:LineExtensionAmount>
<cac:OrderLineReference>
<cbc:LineID>123</cbc:LineID>
</cac:OrderLineReference>
<cac:Item>
<cbc:Description>Description 2</cbc:Description>
<cbc:Name>item name 2</cbc:Name>
<cac:StandardItemIdentification>
<cbc:ID schemeID="0088">21382183120983</cbc:ID>
</cac:StandardItemIdentification>
<cac:OriginCountry>
<cbc:IdentificationCode>NO</cbc:IdentificationCode>
</cac:OriginCountry>
<cac:CommodityClassification>
<cbc:ItemClassificationCode listID="SRV">09348023</cbc:ItemClassificationCode>
</cac:CommodityClassification>
<cac:ClassifiedTaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>25.0</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:ClassifiedTaxCategory>
</cac:Item>
<cac:Price>
<cbc:PriceAmount currencyID="EUR">500</cbc:PriceAmount>
</cac:Price>
</cac:InvoiceLine>
</Invoice>
{
"uuid": "01a03e4a-ee3a-7e1f-b372-c8382bd4ec73",
"invoiceNumber": "Invoice-ID1",
"invoiceDate": "2017-11-17",
"dueDate": "2017-12-01",
"currency": "EUR",
"totalAmount": "1656.25",
"netAmount": "1325.00",
"direction": "outgoing",
"sender": {
"name": "Sender Official Name",
"address": "0245:{{supplier_taxId}}",
"country": "SK"
},
"recipient": {
"name": "Recipient Official Name",
"address": "0245:{{customer_taxId}}",
"country": "SK"
},
"status": "invoice.processing",
"downloaded": false,
"downloadedAt": null,
"createdAt": "2026-08-26T13:38:13+00:00",
"updatedAt": "2026-08-26T13:38:13+00:00"
}
3.2 Retrieve the received invoice
Reception is asynchronous. Retrieve the filtered invoice list using:
GET /invoices?ownerTaxId={newLegalEntityTaxId}&direction=incoming
GET /invoices?ownerTaxId={newLegalEntityId}&direction=incoming
Authorization: Bearer {{jwt}}
[
{
"uuid": "01a03e4a-ee3a-7e1f-b372-c8382bd4ec73",
"invoiceNumber": "Invoice-ID1",
"invoiceDate": "2017-11-17",
"dueDate": "2017-12-01",
"currency": "EUR",
"totalAmount": "1656.25",
"netAmount": "1325.00",
"direction": "incoming",
"sender": {
"name": "Sender Official Name",
"address": "0245:{{supplier_taxId}}",
"country": "SK"
},
"recipient": {
"name": "Recipient Official Name",
"address": "0245:{{customer_taxId}}",
"country": "SK"
},
"status": "invoice.received",
"downloaded": false,
"downloadedAt": null,
"createdAt": "2026-08-26T13:38:13+00:00",
"updatedAt": "2026-08-26T13:38:13+00:00"
},
{
"uuid": "01a03e4a-ee3a-7e1f-b372-c8382b1ba11a",
"invoiceNumber": "Invoice-ID123",
"invoiceDate": "2017-11-17",
"dueDate": "2017-12-01",
"currency": "EUR",
"totalAmount": "1656.25",
"netAmount": "1325.00",
"direction": "incoming",
"sender": {
"name": "Sender Official Name",
"address": "0245:{{supplier_taxId}}",
"country": "SK"
},
"recipient": {
"name": "Recipient Official Name",
"address": "0245:{{customer_taxId}}",
"country": "SK"
},
"status": "invoice.received",
"downloaded": false,
"downloadedAt": null,
"createdAt": "2026-08-26T13:38:13+00:00",
"updatedAt": "2026-08-26T13:38:13+00:00"
}
]
Then, retrieve the document details and original XML using its UUID.
You can now authenticate, onboard a sandbox entity, and exchange test documents.