A-Cube Transfer
A-Cube Transfer sends the files your ERP already exports. It converts them to KSeF FA(3) when needed and delivers them through A-Cube's e-invoicing service for Poland. Upload through SFTP without writing an invoicing integration, or use the file upload API from your application.
For onboarding, uploads, tracking and receiving, see the complete Transfer documentation. This page covers the formats, connection details and outcomes for Poland.
Before your first upload, A-Cube activates your account and agrees the file format with you. You can use the standard layout or have A-Cube build a conversion for your CSV, JSON or XML export.
In Poland, an electronic invoice is an XML file in KSeF FA(3), the structure defined by the Polish Ministry of Finance. It goes through KSeF (Krajowy System e-Faktur), the national e-invoicing system that checks each invoice and makes it available to your customer.
How it works
- Your ERP exports the documents as files, for example a CSV spreadsheet or KSeF FA(3) XML.
- You upload the files to the SFTP folder A-Cube provides. Your application can also upload a file with an HTTP call to the file upload API, after A-Cube confirms access for your destination.
- A-Cube reads each file and, if it is not KSeF FA(3) yet, converts it. A CSV file can contain several documents: each one becomes a separate electronic document.
- A-Cube delivers each document through its e-invoicing service for Poland.
- You check processing and delivery separately. The tracking API reports file processing and gives you each document's identifier. Use that identifier in the invoicing API to check the later delivery outcome.
When to use it
| Use | When |
|---|---|
| A-Cube Transfer | Your system can export invoice information, and you want to send it as it is, without writing code that builds each document. |
| Invoices API | Your application creates each document in KSeF FA(3) and sends it to A-Cube with an API call. |
Availability describes how A-Cube sets up each capability:
- Available: ask A-Cube and it is enabled for you, with no development.
- Custom: A-Cube builds it for you, for example the conversion of your own CSV layout.
Get started
- Contact A-Cube with your destination, a sample export with test data, and your preferred channel (SFTP or file upload API). Request sandbox access to try the integration.
- A-Cube confirms your format, credentials, connection details and where to read the delivery outcome. See Onboarding and access.
- Upload a first file with the Quickstart SFTP. Use the sample and sandbox username for your destination.
The shared guides cover SFTP uploads, file upload API requests, processing statuses and errors and corrections.
Formats for Poland
| File | What A-Cube does | Availability |
|---|---|---|
| CSV in the A-Cube standard layout: one row for each invoice line, with seller, buyer and totals | Converts it to KSeF FA(3). | Available |
| KSeF FA(3) XML: invoices already in the Polish format | Sends it as it is. The file can also be signed (.p7m) or several files can travel in one ZIP archive. | Available |
| UBL XML: the standard business document format, used for example on Peppol | Converts it to KSeF FA(3). | Available |
| Your own format: the export layout your ERP already produces | A-Cube configures the conversion of your layout to KSeF FA(3). | Custom |
What you get back
| What | Where | Availability |
|---|---|---|
| The KSeF status of every invoice, for example valid or invalid | Polish invoicing API | Available |
| Errors found in your files, such as a missing column, with the CSV row and field when applicable | A-Cube dashboard and API | Available |
| Invoices from your suppliers, as files | Your SFTP folder | Available |
| Invoices from your suppliers converted to your own format | Your SFTP folder | Custom |
Connect
During onboarding, A-Cube enables your account in sandbox, a test environment, in production, or in both.
| Item | Value |
|---|---|
| SFTP host | transfer.acubeapi.com, port 22, the same for sandbox and production |
| SFTP username | <your-email>--pl.api.acubeapi.com, where <your-email> is the email of your A-Cube account |
| SFTP username, sandbox | <your-email>--pl.api.acubeapi.com-sandbox |
| REST API base URL | https://transfer.api.acubeapi.com |
| REST API base URL, sandbox | https://transfer-sandbox.api.acubeapi.com |
| REST API | POST /upload. See Upload a file for the full request |
| Size limit | 1 MB per invoice |
| Duplicates | A file whose name was already sent is skipped, whatever its content. Give every file a new name. |
See SFTP and REST API for how to connect. To try it, follow the Quickstart SFTP with your Polish sandbox username and the Polish sample file.
Format details
Standard CSV format
Column names follow the KSeF FA(3) schema, for example Fa.P_2 for the invoice number. Start from the sample file and follow these rules:
| Rule | Value | Violation |
|---|---|---|
| Separator | ; | CSV_SEPARATOR_MISMATCH |
| Dates | Y-m-d, for example 2026-05-05. | INPUT_DATE_FORMAT |
| Numbers | Dot as decimal separator, no thousands separator: 1234.50. | None |
| Structure | Every row has the same number of columns. " around a value that contains the separator, \ as escape character. | CSV_PARSE_ERROR |
| Encoding | UTF-8. Windows-1252 is converted automatically. | CSV_ENCODING |
| Maximum size | 500 data rows per file. Blank rows do not count. The limit counts rows, not invoices. | CSV_SIZE_EXCEEDED |
| Cells | No line break inside a cell. A cell with only spaces or - is empty. | None |
Use the numeric KSeF payment method in Fa.Platnosc.FormaPlatnosci, for example 6 for bank transfer. The sample's seller and buyer identifiers are placeholders: replace them with the sandbox test data agreed with A-Cube.
How rows become invoices:
- Rows with the same
Fa.P_2form one invoice. - Within an invoice, rows with the same
Fa.FaWiersz.NrWierszaFaform one line. - Provide seller data, buyer data and totals in the file: A-Cube does not calculate totals. Repeat seller and buyer data on every row.
- Missing columns are accepted and empty values are omitted. KSeF validates the resulting invoice.
The format covers the basic VAT rate and the second reduced rate, not the first reduced rate. Draft invoices and PDF attachments are not available for Poland.
For every column, the CSV to KSeF FA(3) mapping reference shows the FA(3) field it fills and how A-Cube converts it.
KSeF FA(3) XML
A-Cube sends your KSeF FA(3) XML as it is, up to 1 MB, after transliterating non-ASCII characters.
UBL invoices
A-Cube configures this during onboarding. To request it, contact A-Cube.
A-Cube converts UBL invoices to KSeF FA(3): type codes 380 and 389 become VAT, 384 becomes KOR. Other type codes fail with a violation. See the UBL to KSeF FA(3) mapping reference for each field.
You can also request conversion of the supported UBL JSON layout. See the UBL JSON to KSeF FA(3) mapping reference and the UBL JSON to KSeF tutorial for an example from upload to the KSeF outcome and UPO.
KSeF outcome
Every invoice you send goes through two stages, and each stage has its own status:
- A-Cube reads your file, converts it to KSeF FA(3) when needed, and hands each invoice to A-Cube's Polish invoicing service. You follow this stage with the processing status.
- The Polish invoicing service submits the invoice to KSeF and records KSeF's answer as the status of the invoice. This is the KSeF outcome, the result that counts for tax purposes.
transmitted during file processing means that the Polish invoicing service accepted the invoice. KSeF can still reject it later, and the processing status does not change when it does: always check the KSeF status.
Read the KSeF status in the Polish invoicing API: the document's transmission_uuid is the invoice UUID, and GET /invoices/{uuid}/status returns its KSeF status, for example valid or invalid. See Invoice status for every value. The Invoice transfers page of the dashboard shows the invoice UUID but not the KSeF status.
Use your sandbox token and replace <transmission-uuid> with the value from the tracking API:
curl --fail-with-body -sS 'https://pl-sandbox.api.acubeapi.com/invoices/<transmission-uuid>/status' \
-H 'Authorization: Bearer <your-sandbox-token>' \
-H 'Accept: application/json'
If KSeF returns invalid, read the invoice's KSeF error, correct the original file and upload only the rejected invoice with a new file name. Do not resend invoices already accepted by KSeF.
Contact A-Cube to activate it for your account, in sandbox, in production or in both.