Sage Integration with UAE FTA E-Invoicing via TrustBill

Overview

What is Sage?

Sage is a global business-management software vendor. The products used by UAE businesses for e-invoicing are:

• Sage Business Cloud Accounting — SaaS accounting for SMBs with a modern REST API
• Sage 300 — mid-market ERP with .NET SDK, SData and direct database access
• Sage 50 — desktop accounting for small business, integrates via COM, ODBC and SDK
• Sage 100 — SMB ERP with SData, Business Object Interface and Visual Integrator
• Sage X3 — enterprise ERP with Syracuse web services (SOAP/REST) and X3 REST API

Supported Versions

Prerequisites

• Sage system with UAE VAT, TRN and customer tax IDs configured
• Customer records include 15-digit UAE TRN for B2B invoices
• User / service account with permission to read sales invoices and customers
• Active TrustBill SME account with API credentials
• Network egress from the Sage host or middleware to TrustBill API endpoints
• For on-premise Sage: a Windows or Linux middleware machine with .NET Framework or .NET 6/8 runtime

Integration Architecture

Sage remains the system of record. A middleware agent, cloud connector or scheduled script reads invoices from Sage and pushes them to TrustBill.

1. Invoice created/posted in Sage.
2. Connector / agent polls Sage or listens for a trigger.
3. Payload normalised into TrustBill's PINT-AE JSON.
4. POST to TrustBill /api/v1/invoices with API key authentication.
5. TrustBill validates, renders PINT-AE XML and delivers over Peppol.
6. Acknowledgement written back to Sage custom fields or a linked status table.

Connection Methods

Authentication

TrustBill API uses Bearer tokens. The Sage-side authentication depends on the product.

POST https://trustbill.ae/api/v1/invoices
Authorization: Bearer tb_your_api_key_here
Content-Type: application/json

Sage product auth:

• Business Cloud: OAuth 2.0 authorization code or client credentials from Sage Developer portal
• Sage 300: Windows / database credentials plus SData API key, or Impersonation user for .NET SDK
• Sage 50 / 100: Windows user + company access rights; ODBC DSN or SDK session
• Sage X3: Syracuse user/password or OAuth token obtained through the X3 SSO service

Sage Business Cloud Accounting

The fastest cloud setup uses the Sage Accounting REST API. Register an app in the Sage Developer portal, request permission from the business, and poll for new invoices.

GET https://api.accounting.sage.com/v3.1/sales_invoices
Authorization: Bearer {sage_access_token}
Accept: application/json

Sample payload transformation:

POST https://trustbill.ae/api/v1/invoices
Authorization: Bearer tb_your_api_key
Content-Type: application/json

{
  "invoiceNumber": "SI-001",
  "issueDate": "2026-09-08",
  "dueDate": "2026-10-08",
  "currency": "AED",
  "seller": {
    "trn": "123456789100003",
    "legalName": "Your Company LLC",
    "address": "Dubai, UAE"
  },
  "buyer": {
    "trn": "123456789100004",
    "legalName": "ABC General Trading",
    "address": "Abu Dhabi, UAE"
  },
  "items": [
    {
      "name": "Consulting services",
      "quantity": 1,
      "unitPrice": 1000.00,
      "discount": 0,
      "taxPercent": 5,
      "lineTotal": 1000.00
    }
  ],
  "totals": {
    "netAmount": 1000.00,
    "taxAmount": 50.00,
    "grossAmount": 1050.00
  }
}

The Sage API returns sales_invoices with nestedline_items. Read the contact's tax_number from the linked contact record.

Sage 300

Sage 300 exposes data through SData or the .NET SDK. The standard objects are O/E Invoices and A/R Invoices. A middleware agent can poll the SData endpoint or read the database view and push to TrustBill.

GET https://sage300server/SDataServlet/sdata/ACC/ACCOUNTS/{company}/oeInvoices
  ?startIndex=1&count=50
  &where=STATUS%20eq%20'Posted'

After retrieving the invoice, map the customer tax number from the A/R Customer view and the line tax class from the O/E Invoice Detail view.

Sage 50 / 100 / X3

For desktop and on-premise ERPs, the recommended approach is a TrustBill Windows Desktop Agent or a .NET service installed alongside Sage.

Sage → TrustBill Field Mapping

UAE VAT / Tax Mapping

Map Sage tax codes or tax groups to FTA tax category codes.

Credit Notes

Sage credit notes are mapped to the TrustBill credit-note endpoint. Include the original invoice number.

POST https://trustbill.ae/api/v1/credit-notes
{
  "originalInvoiceNumber": "SI-001",
  "issueDate": "2026-09-08",
  "creditNoteNumber": "CN-001",
  "reason": "Product return",
  "totals": {
    "grossAmount": -1050.00
  }
}

Status Tracking

TrustBill posts status updates to a webhook URL you configure. The middleware then writes the values back to Sage custom fields, a Dataverse table or a CSV status file.

POST https://your-middleware.example.com/webhook/trustbill
Content-Type: application/json

{
  "invoiceNumber": "SI-001",
  "status": "Acknowledged",
  "ackRef": "FDA-ACK-123456789",
  "uuid": "a1b2c3d4-...",
  "reason": null
}

Bulk Migration

Export historical invoices from Sage via the Sales Invoice report, Visual Integrator or the REST API. Upload the CSV to TrustBill.

POST https://trustbill.ae/api/v1/invoices/bulk
Authorization: Bearer tb_your_api_key
Content-Type: multipart/form-data

file: sage_invoices.csv
options: {"mode":"sandbox","skipErrors":true}

Sandbox & Live Modes

Test the full flow without touching the FTA. Switch to live once FTA registration and ASP assignment are complete.

Multi-Company & Multi-Currency

Sage 300, Sage 200 and Sage X3 are commonly run with several company databases sharing one install — for example a UAE mainland trading company plus a related free-zone entity. Sage Business Cloud Accounting instead keeps each business as a fully separate subscription. Either way, TrustBill treats every company as an independent seller with its own TRN.

Error Handling & API Errors

Treat every non-2xx TrustBill response deterministically — distinguish retryable network/rate-limit errors from permanent validation errors that need a mapping fix.

Setup Checklist

Troubleshooting

• 422 validation error: Check that customer TRN is 15 digits and the seller TRN is configured.
• Business Cloud token expired: Refresh the OAuth token before it expires; tokens are usually valid for one hour.
• Sage 50 agent cannot read data: Verify the company file is open and the Windows user has read permission through the Sage 50 SDK.
• Sage 300 SData 404: Confirm the SData servlet is enabled and the endpoint name matches the installed version.
• Missing Arabic names: Use a custom field for the Arabic legal name and include it in the item / customer mapping.

Support

Need help with the Sage integration? Our team can review your Sage Business Cloud app, Sage 300 SData queries, Sage 50 SDK setup or X3 web service calls.