How Transfer works
Transfer processes your uploaded files, converts them when needed, and sends the documents to the destination API. It records whether that API accepted or rejected each document.
Key terms
These terms appear throughout the Transfer docs and in the tracking API.
| Term | Meaning |
|---|---|
| Upload | One file you send to Transfer, through SFTP or the REST API. |
| Document | Each invoice Transfer sends to the destination, with its own status. A CSV with three invoices is one upload and three documents. |
| End-to-end ID | Your own identifier for one document sent to the destination (e2e_id), unique in your account, stored exactly as you send it and searchable. |
The tracking API also lists the CSV file itself, so it can report problems found while reading it.
The flow
- Upload a file to your home directory through SFTP or the REST API.
- Transfer checks the file extension. Unsupported extensions and files in
ignored/orsupplier/directories are skipped. See Troubleshooting. - Transfer prepares the documents:
- CSV: converted into one document per invoice.
- Native XML in the destination format: sent as it is.
- ZIP or P7M: Transfer opens the archive and processes the files inside. The archive is not tracked as a document.
- UBL invoice: converted to the destination format, where A-Cube configured it (on request).
- Transfer sends each document to A-Cube's service for the destination.
- Transfer records the result on each document. Failed documents include violations. The upload status summarizes these results.
Feedback on every document
Each document ends as transmitted, when the A-Cube e-invoicing API accepts it, or failed, with violations that tell you what to fix. An invoice in a CSV can also fail before it is sent, when a value cannot be converted: its violations are reported on the CSV file.
Processing is asynchronous. An upload stays ingested until its documents reach a final status, then becomes completed, partial, or failed. Read the results through the tracking API, the dashboard, or an email digest and daily report (on request).
On request, Transfer webhooks notify your application of processing success or failure, with coverage confirmed during onboarding. For complete API examples, follow UBL JSON to KSeF or CSV to SdI.
From your ID to the destination API
Give each invoice your own End-to-end ID. You can then find its document in Transfer and reach it in A-Cube's e-invoicing API for that country, without storing any Transfer ID.
- Upload the file with your End-to-end ID. See Where the End-to-end ID comes from.
GET /target-documents?e2e_id=<your-id>finds the document once Transfer has created it.GET /target-documents/download?e2e_id=<your-id>downloads its file. See Find a document by End-to-end ID.- On a document sent to the destination,
transmission_uuidis the document's identifier in the destination API. Use it there to read the document and its later outcome.
Each destination page names the API call.
Where the End-to-end ID comes from
| What you upload | Source of the End-to-end ID |
|---|---|
| A file with one invoice, through the REST API | The e2e_id field of POST /uploads. |
| A CSV, through SFTP or the REST API | A column of your CSV that A-Cube configures on request. For an invoice on several rows, the value of its first row counts. |
| A ZIP, through SFTP or the REST API | An index.csv file inside the ZIP, with the header file_name,e2e_id and one row for each file of the archive. A-Cube activates it on request. |
POST /uploads refuses e2e_id with 422 for a CSV or ZIP file, signed or not: one ID cannot name several invoices.
An End-to-end ID has up to 255 printable ASCII characters, with no leading or trailing space. When your CSV has an End-to-end ID column, every invoice needs a valid value, and a value can appear on only one invoice of the file. Otherwise Transfer rejects the whole CSV with CSV_E2E_ID_INVALID and sends none of its invoices.
When the index is active, index.csv is UTF-8 and lists every file of the ZIP exactly once, with a valid End-to-end ID, and a value can appear on only one file. Otherwise Transfer rejects the whole ZIP and sends none of its files: for example when index.csv is missing, a file has no row, or a row names a file that is not in the ZIP. index.csv itself is not sent.
One ID, one document
An End-to-end ID names one document in your account and is never reused. It is taken when Transfer creates the document, even if the destination rejects that document later. If the file fails before the document exists, the ID stays free.
POST /uploadsreturns409withtype/errors/e2e_id_already_usedwhen one of your documents already has the ID. Transfer does not store the file.- If two uploads carry the same ID before either document exists, for example the same CSV sent twice, Transfer sends only the first document. The second is not sent: it ends
failed, withtransmission_outcomeerror, the violationE2E_ID_ALREADY_USEDand noe2e_id. Its upload becomespartialorfailed. - The webhook for that refused document has
status: "failure"andcode: "E2E_ID_ALREADY_USED". It reports the refused send, not the document that owns the ID: do not mark that one as failed.
To send a corrected invoice after its document failed, give it a new End-to-end ID.
Where Transfer's job ends
transmitted means that A-Cube's service for the destination accepted the document. What happens next, such as a tax authority rejection, does not change the Transfer status.
See Statuses and where to see them for every status.
Environments
Use sandbox for testing and production for real documents. A-Cube grants access to each environment separately.
- SFTP uses one host for both environments. Add
-sandboxto your username to select sandbox. - The REST API has one base URL for each environment.
Start with Onboarding and access to activate Transfer for your account, then send your first file with the Quickstart SFTP. Connection details are in the SFTP and REST API guides.