Skip to main content
Download OpenAPI

Quickstart SFTP

Upload your first sample file through SFTP in sandbox and check its processing result.

Before you start​

  1. A-Cube has enabled sandbox access for your destination and confirmed the sample format.
  2. You have your A-Cube account password and the sandbox SFTP username supplied during onboarding.
  3. Your network allows outbound connections to transfer.acubeapi.com on port 22.
  4. To check results through the API, you have tracking API access, curl, and Python 3. Ask A-Cube to enable tracking access if needed.

Sandbox and production use the same SFTP host. The username selects the environment.

Step 1: Prepare a sample file​

Use a sample for the destination enabled on your account:

DestinationFileWhat to prepare
ItalyStandard CSV sample, with two invoices: one with two lines and one draftReplace the buyer identifiers and invoice dates with the test values agreed with A-Cube. Keep the Italian CSV layout.
PolandStandard CSV sample, with two invoices, one with two linesReplace seller and buyer identifiers and invoice dates with your sandbox test data. Keep the Polish CSV layout and recalculate totals if you change amounts.
Another destination or your own formatRequest a sample during onboarding, or use an export A-Cube has confirmedUse that destination's layout. For Peppol, you can also use a Peppol UBL XML document for your registered test participants.

Save the prepared file as invoice.csv (or invoice.xml for XML). The samples illustrate the layout; their placeholder identifiers need to be replaced before a meaningful sandbox test. Open CSV files in a text editor to avoid changing separators or dates.

Step 2: Connect and upload​

Your username contains @, so pass it with -o User=:

SFTP_USERNAME='<your-sandbox-username>'
sftp -o "User=$SFTP_USERNAME" transfer.acubeapi.com

Enter your A-Cube account password. After signing in, you are in your home directory, shown as /. If login fails, see Login rejected. In the SFTP session:

mkdir incoming
cd incoming
put invoice.csv
ls

For XML, use put invoice.xml. If incoming already exists, skip mkdir. If your home directory is read-only, use the writable directory supplied by A-Cube.

ls should show your file. This confirms the upload finished; processing happens next. Transfer copies the file for processing and leaves the uploaded file in your directory.

Step 3: Check the processing result​

Processing is asynchronous. Get a sandbox token and list your latest uploads:

TOKEN=$(curl --fail-with-body -sS https://common.api.acubeapi.com/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "<your-email>", "password": "<your-password>", "environment": "sandbox"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')

curl --fail-with-body -sS "https://transfer-sandbox.api.acubeapi.com/uploads?itemsPerPage=10" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/json'

Find your file by file_name and its upload time, then copy its id. SFTP uploads have no client End-to-end ID.

Read that upload and its documents, replacing <upload-id> with the ID you found:

curl --fail-with-body -sS "https://transfer-sandbox.api.acubeapi.com/uploads/<upload-id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/json'

curl --fail-with-body -sS "https://transfer-sandbox.api.acubeapi.com/uploads/<upload-id>/transfer-documents" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/json'

If the upload is ingested, wait and read it again. completed means at least one invoice was transmitted and none failed; partial means some succeeded and some failed; failed means nothing was transmitted. See Statuses for the full definitions.

Read the documents' violations if processing failed. This list also includes errors on the input CSV, before an invoice is created. See Violation codes and Troubleshooting for corrections.

Where available, you can also open Invoice transfers in the sandbox dashboard and filter by your file name. Use the API for failures that occur before an invoice is created.

Your first SFTP test is complete when you can find the upload and read its processing results. Keep each transmitted invoice's transmission_uuid to follow its later destination outcome. completed and transmitted confirm acceptance by A-Cube's invoicing service, not the tax authority outcome or delivery to the recipient. The Italian sample's draft stays in A-Cube until you send it.

Next steps​

Last updated on