Supplier Integration Guide

This guide provides complete instructions for suppliers to integrate with the RightBytes EDI platform. It covers supplier onboarding, available transport methods (HTTP upload, SFTP polling, and email ingestion), and the EDI/JSON/CSV document formats that the platform validates today.

Table of Contents

• Overview
• Supplier Onboarding
  • Web Form Onboarding
  • Onboarding API
• File Transport Options
  • File Upload API (HTTP)
  • SFTP Polling
  • Email Ingestion
• Payload Formats
  • EDI 810 Invoice Format
  • JSON Order Format
  • CSV Order Format
• Error Handling
• Support

Overview

The RightBytes EDI platform accepts data from suppliers via HTTP API, SFTP polling, or email ingestion. This guide focuses on EDI 810 (Invoice) validation plus the JSON/CSV order feeds that share the same ingestion pipeline. The integration process consists of two steps:

1. Onboarding - Register your supplier account and provide the configuration details for each transport you intend to use.
2. File Delivery - Send EDI/JSON/CSV files through one of the approved transport methods (HTTP API, SFTP, or Email).

All onboarding APIs use JSON for request/response bodies unless otherwise noted.

Quick Start

1. Get onboarded via the web form at https://edi.rightbytes.com/onboarding or by POST https://edi.rightbytes.com/api/onboard.
2. Choose a transport: HTTP API upload, SFTP polling, or Email ingestion.
3. Send one of the supported payloads:
   • EDI 810 invoice using the RightBytes 004010 profile
   • JSON order file
   • CSV order file
4. Review the upload response and resolve any reported errors.

Supplier Onboarding

Before you can submit files, you must be onboarded as a supplier in the system. This is typically done by a RightBytes administrator, but you may be asked to provide the information that populates the onboarding payload. RightBytes offers two entry points that both feed the same /api/onboard endpoint:

1. A guided web form for operations teams who prefer a UI workflow.
2. A JSON API for scripted or automated provisioning.

Web Form Onboarding

Visit https://edi.rightbytes.com/onboarding to walk through the onboarding wizard. The form builds the same payload described in the API section below and is useful when stakeholders want to copy/paste configuration details instead of composing JSON manually.

How it works

• Enter the RightBytes customer number plus supplier profile (code, name, qualifier, contacts).
• Add one or more integration configurations by selecting the integration type (EDI-810/CSV/JSON) and transport method (API/SFTP/Email). Transport-specific fields dynamically appear so you can capture SFTP hosts, API key needs, or email sender filters.
• Optional helper modals warn when a supplier code already exists and lock the shared fields so you do not accidentally fork the record.
• When you submit, the browser POSTs the compiled payload to /api/onboard via HTTPS.

What you receive

• On success the page shows alert banners plus modal dialogs that list generated API keys, SFTP metadata, and email recipient addresses. These values match the onboarding API response and are still shown only once, so copy them immediately before closing the modal.
• If the request fails, the error panel echoes the API error message along with each validation issue returned in the errors array.

Onboarding API

Use the API when you want to automate onboarding via scripts or CI/CD tooling.

Endpoint

POST /api/onboard
Content-Type: application/json

Request Format

{
  "supplier": {
    "supplier_code": "ACME001",
    "supplier_name": "ACME Foods Inc",
    "supplier_qualifier": "ZZ",
    "contact_name": "John Smith",
    "contact_email": "[email protected]",
    "contact_phone": "+1-555-123-4567",
    "is_active": true
  },
  "configurations": [
    {
      "customer_number": 145,
      "supplier_code": "ACME001",
      "integration_type": "EDI-810",
      "transport_method": "API",
      "is_active": true
    },
    {
      "customer_number": 145,
      "supplier_code": "ACME001",
      "integration_type": "CSV",
      "transport_method": "SFTP",
      "sftp_config": {
        "host": "sftp.acmefoods.com",
        "port": 22,
        "username": "rightbytes",
        "password": "<your-sftp-password>",
        "path": "/exports/invoices",
        "file_pattern": "invoice-*.csv"
      }
    },
    {
      "customer_number": 145,
      "supplier_code": "ACME001",
      "integration_type": "EDI-810",
      "transport_method": "Email",
      "email_config": {
        "email_sender_address": "[email protected]",
        "email_subject_pattern": "Invoice*",
        "email_attachment_pattern": "*.edi"
      }
    }
  ]
}

Request Fields

Supplier Object (Required)

Configuration Object (Required - at least one)

SFTP Configuration Object

Provide this block when transport_method is "SFTP".

Email Configuration Object

Provide this block when transport_method is "Email".

Notes:

• For API transport, a secure API key is auto-generated and returned once. You cannot supply your own key.
• For SFTP transport, RightBytes stores your credentials securely and only echoes non-sensitive metadata (host, path, pattern) back in the response.
• For Email transport, a unique recipient address is generated so you know where to send attachments.

Successful Response

{
  "success": true,
  "message": "Successfully onboarded supplier 'ACME001' with 3 configuration(s)",
  "supplier_id": 42,
  "config_ids": [156, 157, 158],
  "errors": [],
  "generated_api_keys": {
    "156": "rbedi_5ec9432e9b5304de3da2ba6acb9fd973"
  },
  "generated_email_addresses": {
    "158": "[email protected]"
  },
  "generated_sftp_configs": {
    "157": {
      "host": "sftp.acmefoods.com",
      "port": 22,
      "username": "rightbytes",
      "path": "/exports/invoices",
      "file_pattern": "invoice-*.csv"
    }
  }
}

Response field clarifications:

• supplier_id is the internal numeric ID in RightBytes
• supplier_code is your external identifier (e.g., "ACME001") and must be used in the ISA06 segment of your EDI files
• Dictionaries in generated_api_keys, generated_sftp_configs, and generated_email_addresses are keyed by config_id so you can match transport credentials to each configuration.
• generated_sftp_configs intentionally excludes passwords—RightBytes already stored them securely during onboarding.
• generated_email_addresses contains the unique recipient address for each Email transport configuration.

Important: API keys are only shown once at onboarding time. Store them securely; RightBytes support cannot retrieve the same key again.

Error Response

{
  "success": false,
  "message": "Failed to onboard supplier 'ACME001': 1 configuration error(s) occurred. No changes were made.",
  "supplier_id": null,
  "config_ids": [],
  "errors": [
    "Customer number 999 does not exist in the system. Please contact support to set up this customer first."
  ],
  "generated_api_keys": null,
  "generated_email_addresses": null,
  "generated_sftp_configs": null
}

File Transport Options

After onboarding you can enable one or more transport methods. All transports feed the same ingestion pipeline (file validation → blob storage → downstream processing) and support the same payload formats (EDI 810, CSV orders, JSON orders). The sections below describe how each method works today.

File Upload API (HTTP)

Use this endpoint to push files directly to RightBytes over HTTPS. It accepts EDI (.edi), CSV (.csv), and JSON (.json) payloads. File type detection happens automatically based on both the contents and the X-File-Name extension.

Endpoint

POST /api/upload

Headers

Request Body

Send the raw file content. EDI/CSV uploads should be transmitted as binary streams (--data-binary), while JSON uploads should be UTF-8 encoded text. Maximum supported file size is 100 MB across all formats.

Example Request (cURL)

curl -X POST "https://edi.rightbytes.com/api/upload" \
  -H "X-API-Key: rbedi_5ec9432e9b5304de3da2ba6acb9fd973" \
  -H "X-File-Name: invoice-2025-001.edi" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @invoice-2025-001.edi

Example Request (Python)

import json
import requests

url = "https://edi.rightbytes.com/api/upload"

order_payload = {
  "supplier_name": "ACME Foods",
  "orders": [{
    "order_id": "ORD-2025-001",
    "ship_to_location": "Store 145",
    "lines": [{
      "product_name": "Chocolate Chip Cookies",
      "supplier_product_code": "ACME-CC-001",
      "brand": "ACME",
      "category": "Bakery",
      "quantity": 24,
      "unit_of_measure": "CA",
      "cost": 12.99
    }]
  }]
}

response = requests.post(
  url,
  data=json.dumps(order_payload).encode("utf-8"),
  headers={
    "X-API-Key": "rbedi_5ec9432e9b5304de3da2ba6acb9fd973",
    "X-File-Name": "order-2025-001.json",
    "Content-Type": "application/json"
  }
)

print(response.json())

Successful Response

{
  "status": "success",
  "message": "File uploaded successfully",
  "file_id": "ACME001:invoice-2025-001.edi:ad2f1673f5b66a13",
  "file_type": "edi",
  "size": 1250
}

Error Responses

400 Bad Request - Invalid input

{
  "error": "No file content provided"
}

or

{
  "error": "Invalid filename: {details}"
}

or

{
  "error": "File exceeds maximum size of 100MB"
}

401 Unauthorized - Missing or invalid API key

{
  "error": "Missing X-API-Key header"
}

or

{
  "error": "Invalid API key"
}

403 Forbidden - Supplier or configuration is inactive

{
  "error": "Supplier is inactive"
}

or

{
  "error": "Supplier configuration is inactive"
}

500 Internal Server Error - Server-side error

{
  "error": "Database error"
}

or

{
  "error": "Internal server error"
}

SFTP Polling

Choose this transport when you already host files on your own SFTP server and prefer RightBytes to pick them up. During onboarding you provide the host, port, username, password, remote path, and file pattern. Credentials are stored securely; passwords are never written to the RightBytes response or logs.

• Polling cadence: Every 15 minutes (0 */15 * * * * Cron schedule).
• File formats: .edi, .csv, .json (the same parser/validator path as HTTP uploads).
• File readiness: Place files in the configured path and ensure the names match the file_pattern. Files that have already been processed are tracked to prevent duplicates.
• Size limit: 100 MB per file (the same limit applies across transports).
• Post-processing: Files remain on your SFTP server unless you choose to archive/move them; RightBytes only reads them.

The onboarding response returns a generated_sftp_configs entry for each SFTP configuration so you can confirm the non-secret values (host/port/path/pattern) that RightBytes is using.

Email Ingestion

This option lets you email attachments (EDI/CSV/JSON) to RightBytes. Supply the sending mailbox, subject filter, and attachment pattern during onboarding. RightBytes generates a unique plus-address—for example [email protected]—and returns it in generated_email_addresses.

• Delivery target: Send new emails (with one or multiple attachments) to the generated recipient address. Only attachments whose names match email_attachment_pattern are downloaded.
• Sender verification: Messages must originate from the configured email_sender_address; others are ignored.
• File formats and limits: Same parsing path as other transports and the same 100 MB per attachment limit. Unsupported file types are rejected with validation errors.

Payload Formats

All transport methods feed the same validation pipeline and accept the formats below. Use these specifications to ensure your files pass validation regardless of how they were delivered.

EDI 810 Invoice Format

The RightBytes platform accepts ANSI X12 810 Invoice transactions. This section describes the RightBytes 810 implementation requirements based on ANSI X12 004010. Requirements marked "Required" refer to what the RightBytes platform validates, not the full ANSI X12 standard.

RightBytes Validation Scope: RightBytes intentionally enforces a stricter subset of the ANSI X12 810 standard. When you see "Required" below, read it as "Required for RightBytes to accept and process the file," even if the official X12 spec marks that segment optional.

Requirements Summary

Segment Requirements (RightBytes validation rules)

Note: "Required" in this table means the segment is required by the RightBytes platform. Some of these segments are optional in the ANSI X12 810 standard but are mandatory for RightBytes processing.

Line Item Data Requirements (RightBytes validation rules)

Each IT1 line item must provide the following data (via IT1, PID, or REF segments):

Note: These fields are required by the RightBytes platform for inventory tracking and reporting. Some are optional in the ANSI X12 810 standard.

Document Structure

An EDI 810 document consists of:

1. Envelope segments (ISA/IEA, GS/GE) - Transport metadata
2. Header segments (ST, BIG, REF, N1) - Invoice header information
3. Detail segments (IT1, PID, REF) - Line item details
4. Summary segments (TDS, CTT, SE) - Totals

Format notes:

• Elements are separated by * (asterisk)
• Segments are terminated by ~ (tilde)
• Empty elements are represented by consecutive separators (e.g., **)

Minimal Example

ISA*00*          *00*          *ZZ*ACME001        *ZZ*RIGHTBYTES     *250127*1030*U*00401*000000001*0*P*>~
GS*IN*ACME001*RIGHTBYTES*20250127*1030*1*X*004010~
ST*810*0001~
BIG*20250127*INV-001*20250120*PO-100001~
N1*ST*Store Name*92*0000000145~
IT1*1*10*EA*5.99**VN*SKU-001~
PID*F****ACME Chips 12oz~
PID*S****ACME~
REF*DP*Snacks~
TDS*5990~
CTT*1~
SE*9*0001~
GE*1*1~
IEA*1*000000001~

Segment Reference

ISA - Interchange Control Header (Required)

Identifies the interchange sender and receiver.

GS - Functional Group Header (Required)

ST - Transaction Set Header (Required)

BIG - Beginning Segment for Invoice (Required)

REF - Reference Information (Optional)

Reference Qualifiers:

• CN - Tracking Number (carrier tracking)
• CO - Customer Order Reference
• DP - Department Number
• SO - Sales Order Number

Examples:

REF*CN*TRACK-12345~
REF*CO*CUST-ORD-789~
REF*DP*Grocery~
REF*SO*SO-2025-001~

DTM - Date/Time Reference at Header Level (Optional)

Date/time information for the invoice.

Date Qualifiers:

• 011 - Ship Date
• 002 - Delivery Date
• 035 - Delivered Date (alternate)

Examples:

DTM*011*20250125~
DTM*002*20250127*1430~

N1 - Name (Required for Ship-To)

Identifies trading partners. N1*ST (Ship-To) is required for all EDI 810 invoices submitted to RightBytes.

For Ship-To, the N104 should be the store number padded to 10 digits (e.g., "0000000145").

Example:

N1*ST*Main Street Store*92*0000000145~

N3 - Address Information (Optional)

N4 - Geographic Location (Optional)

IT1 - Baseline Item Data (Required - one per line item)

*At least one IT106/IT107 pair is required (UPC or Supplier SKU). Additional pairs can follow. Common qualifiers:

• VN or SK - Vendor/Supplier SKU
• UP - UPC (12-digit)

Example with UPC and SKU:

IT1*1*24*CA*12.99**UP*003680004122*VN*SKU-001~

LIN - Item Identification (Optional)

Additional product identifiers for the line item. Qualifier/value pairs can repeat.

Qualifiers:

• UP - UPC
• VN or SK - Vendor/Supplier SKU
• MG - Manufacturer Name
• MF - Manufacturer Product Code

Example:

LIN*MG*ACME-FOODS*MF*AF-CHIPS-001~

PID - Product/Item Description (Required)

Provides product description and brand information for the line item.

PID*F - Product Description (Required):

PID*F****ACME Potato Chips 12oz~

PID*S - Brand Name (Optional):

PID*S****ACME~

The RightBytes parser processes all PID segments for each line item:

• PID*F sets the product name (required)
• PID*S sets the brand name (optional)
• If no PIDS is provided, the RightBytes parser attempts to derive the brand by taking the first word of the PIDF description

Example with both:

PID*F****Potato Chips 12oz~
PID*S****ACME~

This sets Product Name = "Potato Chips 12oz" and Brand = "ACME"

REF at Line Item Level (Category Required)

Reference information specific to a line item. REF*DP (Category) is required for each line item.

Category (Required):

REF*DP*Beverages~

Lot Number (Optional):

REF*LS*LOT-20250127~

DTM - Date/Time Reference at Line Item Level (Optional)

Expiration Date:

DTM*361*20260127~

TDS - Total Monetary Value Summary (Optional but Recommended)

Example: For $59.90, use TDS*5990~

While not strictly required, including TDS helps verify invoice totals match line item calculations.

TXI - Tax Information (Optional)

Example:

TXI*ST*5.50*5.00~

SAC - Service, Allowance, or Charge (Optional)

Common Charge Codes:

• D240 - Freight
• D400 - Fuel Surcharge
• H850 - Handling

Example:

SAC*C*D240***125.00~

CTT - Transaction Totals (Optional but Recommended)

While not strictly required, including CTT helps verify the expected number of line items were received.

SE - Transaction Set Trailer (Required)

GE - Functional Group Trailer (Required)

IEA - Interchange Control Trailer (Required)

Complete Example

ISA*00*          *00*          *ZZ*ACME001        *ZZ*RIGHTBYTES     *250127*1030*U*00401*000000001*0*P*>~
GS*IN*ACME001*RIGHTBYTES*20250127*1030*1*X*004010~
ST*810*0001~
BIG*20250127*INV-2025-001*20250120*PO-500123~
REF*CN*TRACK-12345~
DTM*011*20250125~
N1*ST*Main Street Store*92*0000000145~
N3*123 Main Street~
N4*Springfield*IL*62701~
IT1*1*24*CA*12.99**UP*003680004122*VN*ACME-SKU-001~
LIN*MG*ACME-FOODS*MF*AF-CHIPS-001~
PID*F****Potato Chips 12oz~
PID*S****ACME~
REF*DP*Snacks~
REF*LS*LOT-20250127~
DTM*361*20260127~
IT1*2*48*EA*2.49**UP*012345678905*VN*ACME-SKU-002~
PID*F****Cola 12oz Can~
PID*S****ACME~
REF*DP*Beverages~
TDS*45784~
TXI*ST*21.56*5.00~
SAC*C*D240***5.00~
CTT*2~
SE*23*0001~
GE*1*1~
IEA*1*000000001~

Totals breakdown:

• Line 1: 24 x $12.99 = $311.76
• Line 2: 48 x $2.49 = $119.52
• Subtotal: $431.28
• Tax: $21.56
• Freight: $5.00
• Total: $457.84 (TDS amounts are always expressed in cents, no decimal points)

JSON Order Format

The RightBytes platform also accepts order data in JSON format. This section describes the RightBytes JSON order schema requirements. Requirements marked "Required" refer to what the RightBytes platform validates.

Document Structure

A JSON order file contains:

1. Root object - Supplier name and orders array
2. Orders array - One or more order objects
3. Lines array - Line items within each order

Requirements Summary

Root Level Requirements (RightBytes validation rules)

Order Level Requirements (RightBytes validation rules)

Processing behavior: Every order in the orders array is validated independently. Orders that pass validation continue through processing immediately, while orders with errors are reported without blocking the rest of the file.

Line Item Requirements (RightBytes validation rules)

Minimal Example

This example shows only the required fields:

{
  "supplier_name": "ACME Foods",
  "orders": [
    {
      "order_placed_at": "2025-01-27T08:00:00Z",
      "ship_to_location": "Store 145",
      "lines": [
        {
          "product_name": "Chocolate Chip Cookies",
          "supplier_product_code": "ACME-CC-001",
          "brand": "ACME",
          "category": "Bakery",
          "quantity": 24,
          "unit_of_measure": "CA",
          "cost": 12.99
        }
      ]
    }
  ]
}

Complete Example

This example shows all available fields:

{
  "supplier_name": "ACME Foods Inc",
  "orders": [
    {
      "order_id": "ORD-2025-001",
      "order_placed_at": "2025-01-27T08:00:00Z",
      "order_shipped_at": "2025-01-28T10:00:00Z",
      "order_delivered_at": "2025-01-29T14:30:00Z",
      "tracking_number": "TRACK-12345",
      "invoice_number": "INV-2025-001",
      "ship_to_location": "Main Distribution Center",
      "lines": [
        {
          "product_name": "Premium Chocolate Chip Cookies",
          "supplier_product_code": "ACME-CC-001",
          "upc": "012345678901",
          "manufacturer_name": "Cookie Co",
          "manufacturer_product_code": "CC-CHOC-001",
          "brand": "ACME Premium",
          "category": "Bakery",
          "quantity": 48,
          "unit_of_measure": "CA",
          "cost": 15.99,
          "product_expiration_date": "2025-06-15",
          "product_expiration_timeframe": {
            "frozen_days": 180,
            "thawed_days": 7
          }
        },
        {
          "product_name": "Organic Apple Juice",
          "supplier_product_code": "ACME-AJ-002",
          "upc": "012345678902",
          "brand": "ACME Organic",
          "category": "Beverages",
          "quantity": 100,
          "unit_of_measure": "EA",
          "cost": 3.49,
          "product_expiration_date": "2025-12-31"
        }
      ]
    }
  ]
}

Date/Time Formats

All date/time fields use ISO 8601 format:

Expiration Timeframe Object

The product_expiration_timeframe field provides shelf life information:

{
  "product_expiration_timeframe": {
    "frozen_days": 180,
    "thawed_days": 7
  }
}

Common Validation Errors

CSV Order Format

The RightBytes platform also accepts supplier orders as UTF-8 CSV files. Each row represents a line item, and the parser uses the first data row to populate order-level fields such as supplier name, ship-to, and timestamps. Column names are case-sensitive and must match the headers listed below.

Document Structure

1. Header Row – Defines the column names. Required columns must be present.
2. Line Rows – Each subsequent row is a line item. CSV format supports exactly one order per file. Multiple orders require multiple CSV files.

Requirements Summary

File-Level Columns (RightBytes validation rules)

Note: Populate these columns on every row when possible. The parser reads the first row for order-level values, so the first line must contain accurate data.

Line Item Columns (RightBytes validation rules)

*At least one of supplier_product_code or upc must be provided on every row.

Minimal Example

supplier_name,ship_to_location,order_placed_at,product_name,supplier_product_code,brand,category,quantity,unit_of_measure,cost
ACME Foods,Store 145,2025-01-27T08:00:00Z,Chocolate Chip Cookies,ACME-CC-001,ACME,Bakery,24,CA,12.99

Complete Example

supplier_name,ship_to_location,order_id,order_placed_at,order_shipped_at,order_delivered_at,tracking_number,invoice_number,product_name,supplier_product_code,upc,brand,category,quantity,unit_of_measure,cost,manufacturer_name,manufacturer_product_code,lot_number,product_expiration_date,product_expiration_timeframe
ACME Foods,Main Distribution Center,ORD-2025-001,2025-01-27T08:00:00Z,2025-01-28T10:00:00Z,2025-01-29T14:30:00Z,TRACK-12345,INV-2025-001,Premium Chocolate Chip Cookies,ACME-CC-001,012345678901,ACME Premium,Bakery,48,CA,15.99,Cookie Co,CC-CHOC-001,LOT-20250127,2025-06-15,"frozen_days:180,thawed_days:7"
ACME Foods,Main Distribution Center,ORD-2025-001,2025-01-27T08:00:00Z,2025-01-28T10:00:00Z,2025-01-29T14:30:00Z,TRACK-12345,INV-2025-001,Organic Apple Juice,ACME-AJ-002,012345678902,ACME Organic,Beverages,100,EA,3.49,,,,2025-12-31,

Additional Notes

• Files must be encoded in UTF-8 with Unix or Windows line endings.
• Numeric values may include decimals; they are parsed using Python's decimal.Decimal for accuracy.
• Date and datetime columns accept ISO 8601 strings; other unambiguous formats (such as YYYY-MM-DD) are parsed via dateutil, but ISO is recommended for consistency.
• CSV uploads follow the same validation logic as JSON uploads. Missing required fields, negative quantities, or unknown UOM codes will produce the same error codes described in the JSON section above.

Error Handling

Parsing Errors

These errors occur when the EDI file structure is invalid:

Data Validation Errors

These errors occur when required data is missing or invalid:

Warnings

These are non-fatal issues that will be logged but won't reject the file:

Best Practices

1. Validate Locally - Check your EDI file structure before uploading
2. Unique Invoice Numbers - Each invoice number should be unique
3. Consistent Supplier Code - Use your supplier code in ISA06 (matches your API key configuration)
4. Control Numbers - Increment control numbers (ISA13, GS06) with each transmission

Support

For technical support or questions about integration:

• Contact RightBytes support
• Email: [email protected]

For issues with specific file rejections, please provide:

• The file_id from the upload response
• The error message received
• The original file (if possible)