Skip to main content
Download OpenAPI

Tracking via API

Use the read-only tracking API to check uploads, documents, statuses, violations, and lineage. It covers SFTP and REST API uploads for every destination.

For worked examples from upload to the tax authority outcome, follow UBL JSON to KSeF or CSV to SdI. If your setup uses Transfer webhooks, keep this API as the source for processing status and error details.

Base URLs and token​

EnvironmentBase URL
Productionhttps://transfer.api.acubeapi.com
Sandboxhttps://transfer-sandbox.api.acubeapi.com

Use the same token as for REST uploads. Get it from POST https://common.api.acubeapi.com/login with your email, password, and environment. Send Authorization: Bearer <your-token> with each request. Tokens are valid for 24 hours.

You can read only your account's data. A 404 means the resource is not available in your account. If a request returns 403, ask A-Cube to enable tracking API access.

Resources​

RouteWhat it returns
GET /uploadsYour uploads: one entry per file you sent.
GET /uploads/{id}One upload. For a REST API upload, use the id of the upload receipt.
GET /uploads/{id}/transfer-documentsThe documents of one upload.
GET /transfer-documentsYour documents, all roles.
GET /transfer-documents/{id}One document, with its violations.
GET /transfer-documents/{id}/lineageThe chain that links the document to your file.
GET /transfer-documents/{id}/downloadThe file of one document. See Download a document file.
GET /target-documentsOnly the documents transmitted to the destination, with the transmission fields.

An upload represents one file. Source documents are files that require conversion; target documents are sent to the destination. See Statuses and where to see them.

curl -s "https://transfer.api.acubeapi.com/uploads?itemsPerPage=10&page=1" \
  -H "Authorization: Bearer <your-token>" \
  -H 'Accept: application/json'

Pagination and sorting​

ParameterDefaultMaximum
itemsPerPage30100
page1

Uploads are sorted by ingestion time, newest first. For documents, use sortBy[created_at]=desc to sort by creation time, newest first.

Use Accept: application/json for a JSON array. Use Accept: application/ld+json to include the total item count:

curl -s "https://transfer.api.acubeapi.com/uploads" \
  -H "Authorization: Bearer <your-token>" \
  -H 'Accept: application/ld+json'
{
  "hydra:member": [],
  "hydra:totalItems": 0
}

Filters​

FilterOnExample
statusuploads, documents?status=failed
destination_projectuploads?destination_project=it.api.acubeapi.com
e2e_iduploads?e2e_id=erp-2026-01-run-14
roledocuments?role=source
typedocuments?type=invoice
transmission_outcomedocuments?transmission_outcome=error
exists[violations]documents?exists[violations]=true
created_at[gt], created_at[gte], created_at[lt], created_at[lte], created_at[ne]uploads, documents?created_at[gte]=2026-05-01

Find an upload by End-to-end ID​

Attach an End-to-end ID when uploading through the REST API, then search with e2e_id. Transfer preserves the value exactly. Searches are case-sensitive exact matches within your account:

curl -s "https://transfer.api.acubeapi.com/uploads?e2e_id=erp-2026-01-run-14" \
  -H "Authorization: Bearer <your-token>" \
  -H 'Accept: application/json'

An upload is searchable as soon as the REST API returns its receipt, with status pending. An empty array means no upload has that End-to-end ID in your account: check the value and the environment.

List the failed documents​

Query all failed documents to include both file processing failures and destination rejections:

curl -s "https://transfer.api.acubeapi.com/transfer-documents?status=failed" \
  -H "Authorization: Bearer <your-token>" \
  -H 'Accept: application/json'

CSV reading and conversion failures appear on the source document. They are absent from GET /target-documents because the failed invoice has no target document. See Where violations land.

Lineage​

Lineage links a target document back to your uploaded file. Each entry includes id, role, file_name, file_format, status, and depth. Entries start with the requested document (depth 0) and follow its source, up to five steps.

CSV target documents link directly to the CSV source document. Individual rows are not tracked as documents.

curl -s "https://transfer.api.acubeapi.com/transfer-documents/<document-id>/lineage" \
  -H "Authorization: Bearer <your-token>" \
  -H 'Accept: application/json'
[
  {"id": "<target-id>", "role": "target", "file_name": "invoices_2026_01-row2.xml", "file_format": "xml", "status": "transmitted", "depth": 0},
  {"id": "<source-id>", "role": "source", "file_name": "invoices_2026_01.csv", "file_format": "csv", "status": "processed", "depth": 1}
]

Download a document file​

Download the file of a document by its id:

  • a source document returns the file you sent, such as your CSV;
  • a target document returns the document Transfer sent to the destination, in the destination format. For native XML, it is the file you sent.
curl -s -OJ "https://transfer.api.acubeapi.com/transfer-documents/<document-id>/download" \
  -H "Authorization: Bearer <your-token>"

The response is the file as application/octet-stream, with its name in the Content-Disposition header. -OJ saves it under that name. A 404 means the document is not in your account or its file is no longer available. See the API reference.

Transmission data​

Target documents include these transmission fields:

FieldMeaning
transmission_nodeThe destination service that accepted the document.
transmission_outcomeok or error. The API also defines pending, which Transfer does not use today: treat it as in progress.
transmission_uuidThe document's identifier in A-Cube's e-invoicing API for the destination, for example the invoice UUID. Use it to follow the document there: see From your ID to the destination API.
transmitted_atWhen the destination service answered.

See Outcome after Transfer for what happens after transmitted.

Last updated on