Piing SFTP Upload

Overview

The Piing SFTP Upload service allows you to upload transaction and analytics data to the Piing platform using the standard SFTP protocol. This is ideal for automated file drops from POS systems, ERP exports, or scheduled batch uploads where integrating with a REST API is not practical.

The SFTP server uses the same credentials and processing pipeline as the Data Upload API, so files uploaded via SFTP are processed identically to files uploaded via the HTTP API.

SFTP Host: sftp.piing.ai (production) | sftp-staging.piing.ai (staging)

Port: 2222

Supported File Formats: CSV (.csv) and JSON (.json)

Maximum File Size: 100 MB

Quick Start

1. Get Your Credentials

Contact your Piing administrator to obtain your API credentials:

client_id - Your unique client identifier (e.g., piing_abc123...)
client_secret - Your secret key (shown only once during creation)

These are the same credentials used for the Upload API. Your client_id is your SFTP username and your client_secret is your SFTP password.

2. Connect

sftp -P 2222 your_client_id@sftp.piing.ai
# Enter your client_secret when prompted for password

3. Browse Available Schemas

Once connected, the root directory contains folders for each data schema enabled for your organization:

sftp> ls
orgTransactions        orgTransactionDetail   orgShifts

4. Upload a File

Navigate to the schema folder that matches your data format and upload your file:

sftp> cd orgTransactions
sftp> put february-sales.csv
Uploading february-sales.csv to /orgTransactions/february-sales.csv
february-sales.csv                          100%  2.1MB  10.5MB/s   00:00

The file is automatically processed once the upload completes. No further action is required.

Authentication

The SFTP server uses password authentication with your existing Piing API credentials:

SFTP Field	Value
Host	`sftp.piing.ai`
Port	`2222`
Username	Your `client_id` (e.g., `piing_abc123...`)
Password	Your `client_secret`

Only password authentication is supported. SSH key authentication is not available.

If your credentials have been revoked, the connection will be rejected. Contact your Piing administrator to obtain new credentials.

Directory Structure

The SFTP server presents a virtual filesystem. The root directory contains one folder for each data schema that is enabled for your organization. You cannot create, rename, or delete directories.

/                              # Root (read-only listing)
  orgTransactions/             # Organization transaction data
  orgTransactionDetail/        # Organization transaction line items
  orgShifts/                   # Organization shift/roster data
  etc

The available folders depend on which schemas your Piing administrator has enabled for your organization. Use the ls command after connecting to see your available schemas.

Session-Based File Listings

The SFTP server does not store files on disk — it is a write-only gateway that forwards uploaded data to the Piing processing pipeline. Directory listings only show files uploaded during your current SFTP session. Files from previous sessions will not appear in ls output, but they were processed successfully. To verify the status of a previous upload, use the Upload API status endpoint.

Uploading Files

How It Works

Connect to the SFTP server with your credentials
Navigate to the schema folder that matches your data format
Upload your CSV or JSON file using put
Processing starts automatically when the upload completes

Behind the scenes, when you close the file after uploading:

The raw file is stored in cloud storage (for audit and retry purposes)
An upload record is created with PENDING status
The file is parsed, validated, and transformed using the schema's configured transformer
Transformed rows are inserted into the analytics database

File Naming

You can name your files anything you like. The schema is determined by which folder you upload to, not the filename. We recommend using descriptive names that include dates for easy identification:

february-2026-sales.csv
org-export-20260220.csv
daily-transactions.json

File Format Requirements

File format requirements are identical to the Upload API:

Encoding: UTF-8
CSV: Comma-delimited with a header row
JSON: Array of objects (or wrapped in data/records/items/rows)
Maximum file size: 100 MB

Refer to the Upload API documentation for detailed column requirements for each schema type.

Checking Upload Status

SFTP does not provide a mechanism to check processing status. To monitor the status of uploads made via SFTP, use the Upload API status endpoint:

# First, get an access token
TOKEN=$(curl -s -X POST https://api.piing.ai/api/external/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"your_client_id","client_secret":"your_client_secret"}' \
  | jq -r '.access_token')

# Then check the status of a specific upload
curl https://api.piing.ai/api/external/upload/UPLOAD_ID/status \
  -H "Authorization: Bearer $TOKEN"

Upload IDs are logged server-side. Contact your Piing administrator if you need to look up the status of an SFTP upload.

Code Examples

Bash (sftp command)

#!/bin/bash

HOST="sftp.piing.ai"
PORT="2222"
USERNAME="your_client_id"
FILE="./transactions.csv"
SCHEMA="orgTransactions"

# Upload using sftp with password from environment variable
# Requires sshpass: brew install sshpass (macOS) or apt install sshpass (Linux)
sshpass -p "$PIING_CLIENT_SECRET" sftp -P $PORT -oBatchMode=no -oStrictHostKeyChecking=no \
  $USERNAME@$HOST <<EOF
cd $SCHEMA
put $FILE
bye
EOF

echo "Upload complete"

Python (paramiko)

import paramiko

HOST = "sftp.piing.ai"
PORT = 2222
USERNAME = "your_client_id"
PASSWORD = "your_client_secret"

SCHEMA = "orgTransactions"
LOCAL_FILE = "./transactions.csv"
REMOTE_FILE = f"/{SCHEMA}/transactions.csv"

# Connect and upload
transport = paramiko.Transport((HOST, PORT))
transport.connect(username=USERNAME, password=PASSWORD)
sftp = paramiko.SFTPClient.from_transport(transport)

# List available schemas
print("Available schemas:", sftp.listdir("/"))

# Upload file
sftp.put(LOCAL_FILE, REMOTE_FILE)
print(f"Uploaded {LOCAL_FILE} to {REMOTE_FILE}")

sftp.close()
transport.close()

Node.js (ssh2-sftp-client)

const SftpClient = require('ssh2-sftp-client');

const config = {
  host: 'sftp.piing.ai',
  port: 2222,
  username: 'your_client_id',
  password: 'your_client_secret',
};

async function uploadFile(localPath, schemaName) {
  const sftp = new SftpClient();

  try {
    await sftp.connect(config);

    // List available schemas
    const schemas = await sftp.list('/');
    console.log('Available schemas:', schemas.map(s => s.name));

    // Upload file
    const remotePath = `/${schemaName}/${localPath.split('/').pop()}`;
    await sftp.put(localPath, remotePath);
    console.log(`Uploaded to ${remotePath}`);
  } finally {
    await sftp.end();
  }
}

uploadFile('./transactions.csv', 'orgTransactions')
  .then(() => console.log('Done'))
  .catch(err => console.error('Error:', err.message));

PowerShell (WinSCP)

# Requires WinSCP .NET assembly
# Download from https://winscp.net/eng/downloads.php

Add-Type -Path "C:\Program Files (x86)\WinSCP\WinSCPnet.dll"

$sessionOptions = New-Object WinSCP.SessionOptions -Property @{
    Protocol = [WinSCP.Protocol]::Sftp
    HostName = "sftp.piing.ai"
    PortNumber = 2222
    UserName = "your_client_id"
    Password = "your_client_secret"
    GiveUpSecurityAndAcceptAnySshHostKey = $true
}

$session = New-Object WinSCP.Session
$session.Open($sessionOptions)

# Upload file
$session.PutFileToDirectory("C:\exports\transactions.csv", "/orgTransactions/")

$session.Dispose()
Write-Host "Upload complete"

Automation

Scheduled Uploads (Linux/macOS cron)

Upload files automatically on a schedule using cron:

# Upload daily export at 3 AM
0 3 * * * sshpass -p "$PIING_CLIENT_SECRET" sftp -P 2222 -oBatchMode=no \
  your_client_id@sftp.piing.ai:/orgTransactions/ <<< "put /path/to/daily-export.csv"

Limitations

Limitation	Details
Write-only	You can upload files but cannot download or read files from the server
Session-based listings	Directory listings only show files uploaded during the current session. Previously uploaded files are not visible but were processed successfully
No directory creation	Directories are managed by Piing and map to enabled schemas
No file deletion	Files cannot be deleted or renamed after upload
Password auth only	SSH key authentication is not supported
Maximum file size	100 MB per file
No status feedback	Use the Upload API status endpoint to check processing status

Troubleshooting

Connection refused

Verify the host and port (sftp.piing.ai:2222)
Check that your credentials have not been revoked
Ensure your network allows outbound connections on port 2222

Authentication failed

Double-check your client_id (username) and client_secret (password)
Credentials are case-sensitive
If your credentials were recently created, allow a few moments for propagation

Previously uploaded files not visible

This is expected behavior. The SFTP server uses a virtual filesystem and does not store files on disk. Directory listings only show files uploaded during your current session. Once you disconnect and reconnect, the listing resets.
Your previous uploads were still processed successfully. To verify, use the Upload API status endpoint or contact your Piing administrator.

Empty directory listing

If you just connected and see no files in a schema folder, this is normal — see above.
If the root directory is empty (no schema folders), your organization may not have any schemas enabled. Contact your Piing administrator to enable the schemas you need.

Host key verification

On first connection, your SFTP client will prompt to accept the server's host key. Accept it to continue. If you're scripting, use -oStrictHostKeyChecking=no (for trusted networks) or pre-add the key to your known_hosts file.

SFTP vs Upload API

Both methods use the same credentials and processing pipeline. Choose based on your use case:

Feature	SFTP Upload	Upload API
Protocol	SFTP (SSH)	HTTPS
Authentication	Password (per connection)	JWT token (per session)
Best for	Automated file drops, POS/ERP exports, scheduled batches	Programmatic integration, real-time uploads
Schema selection	Directory-based (upload to folder)	Field-based (`schemaType` parameter)
Status checking	Via Upload API	Direct response
Idempotency	Not supported	Supported via `idempotencyKey`
File size limit	100 MB	100 MB

Support

For SFTP support, contact your Piing administrator or email support@piing.ai with:

Your organization ID
Your client ID (do not share your client secret)
Timestamp of the issue
Any error messages from your SFTP client

Overview​

Quick Start​

1. Get Your Credentials​

2. Connect​

3. Browse Available Schemas​

4. Upload a File​

Authentication​

Directory Structure​

Uploading Files​

How It Works​

File Naming​

File Format Requirements​

Checking Upload Status​

Code Examples​

Bash (sftp command)​

Python (paramiko)​

Node.js (ssh2-sftp-client)​

PowerShell (WinSCP)​

Automation​

Scheduled Uploads (Linux/macOS cron)​

Limitations​

Troubleshooting​

Connection refused​

Authentication failed​

Previously uploaded files not visible​

Empty directory listing​

Host key verification​

SFTP vs Upload API​

Support​