SAP Integration with UAE FTA E-Invoicing via TrustBill

Overview

What is SAP?

SAP is the market-leading enterprise resource planning (ERP) suite. The four SAP editions most used by UAE businesses for e-invoicing are:

• SAP Business One — SME ERP, on-premise or on HANA, with a built-in Service Layer REST API
• SAP S/4HANA — next-generation enterprise suite, exposes OData and SOAP services for finance and sales
• SAP ERP Central Component (ECC 6.0) — classic enterprise ERP, integrates via RFC/BAPI or SAP Gateway OData
• SAP Business ByDesign — cloud ERP for mid-market, with OData APIs for customer, supplier and invoice objects

Supported Versions

Prerequisites

• SAP system running a supported version with valid UAE VAT and TRN setup
• Customer master records include 15-digit TRN for B2B transactions
• User account or service user with read access to A/R Invoice and Customer objects
• Active TrustBill SME account with API credentials
• Network egress from SAP host / middleware to TrustBill API endpoints
• For on-premise SAP: a Windows or Linux agent machine with .NET Framework 4.8 or .NET 6/8 runtime

Integration Architecture

The standard pattern keeps SAP as the source of record and uses a small middleware agent or scheduled script to transport invoice data into TrustBill.

1. Invoice posted in SAP (A/R Invoice, Billing Document or ByDesign Invoice).
2. TrustBill Agent / middleware queries the SAP API on a schedule or listens for an event trigger.
3. Payload normalised into TrustBill's PINT-AE JSON format.
4. POST to TrustBill /api/v1/invoices with API key authentication.
5. TrustBill validates, renders PINT-AE XML and submits over Peppol via the FTA-accredited ASP.
6. Acknowledgement written back to SAP UDFs or custom fields.

Connection Methods

Authentication

TrustBill API uses Bearer tokens. In SAP, store the token in a secure parameter or in your middleware's secret store.

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

SAP-side authentication depends on the product:

• Business One: Service Layer session cookie after POST /b1s/v2/Login
• S/4HANA: OAuth 2.0 client-credentials or basic auth with x-csrf-token
• ECC: SAP username + password + client number via RFC or SAP Gateway
• ByDesign: technical user username + password

SAP Business One Setup

This is the fastest production setup for Business One. The middleware logs into Service Layer, fetches new invoices and pushes them to TrustBill on a schedule.

Step 1: Add UDFs to A/R Invoice

• U_TB_Status (Alphanumeric 20): Pending / Submitted / Acknowledged / Rejected
• U_TB_UUID (Alphanumeric 50): TrustBill UUID
• U_TB_AckRef (Alphanumeric 50): FTA acknowledgement reference
• U_TB_Reject (Text): Error or rejection message

Step 2: Middleware Python sample

import requests
import json

B1_BASE = "https://sapserver:50001/b1s/v2"
TRUSTBILL_BASE = "https://trustbill.ae/api/v1"

# 1. Login to Service Layer
login = requests.post(f"{B1_BASE}/Login", json={
    "CompanyDB": "SBODemoAE",
    "UserName": "manager",
    "Password": "password",
    "Language": -1
})
login.raise_for_status()
cookies = login.cookies

# 2. Fetch posted A/R invoices not yet sent
invoices = requests.get(
    f"{B1_BASE}/Invoices?$filter=DocumentStatus eq 'bost_Open' and U_TB_Status eq null",
    cookies=cookies
).json()

for inv in invoices.get("value", []):
    customer = requests.get(
        f"{B1_BASE}/BusinessPartners('{inv['CardCode']}')",
        cookies=cookies
    ).json()

    payload = {
        "invoiceNumber": inv["DocNum"],
        "issueDate": inv["DocDate"].split("T")[0],
        "dueDate": inv["DocDueDate"].split("T")[0],
        "currency": inv["DocCurrency"],
        "seller": {
            "trn": "123456789100003",  # company TRN
            "legalName": "Your Company LLC",
            "address": "Dubai, UAE"
        },
        "buyer": {
            "trn": customer.get("FederalTaxID", ""),
            "legalName": customer.get("CardName", ""),
            "address": customer.get("Address", "")
        },
        "items": [
            {
                "name": line["ItemDescription"],
                "quantity": float(line["Quantity"]),
                "unitPrice": float(line["Price"]),
                "discount": float(line.get("DiscountPercent", 0)),
                "taxPercent": float(line["TaxPercentagePerRow"] or 0),
                "lineTotal": float(line["LineTotal"])
            }
            for line in inv["DocumentLines"]
        ],
        "totals": {
            "netAmount": float(inv["DocTotalNet"]),
            "taxAmount": float(inv["VatSum"]),
            "grossAmount": float(inv["DocTotal"])
        }
    }

    resp = requests.post(
        f"{TRUSTBILL_BASE}/invoices",
        headers={"Authorization": "Bearer tb_your_api_key"},
        json=payload
    )
    data = resp.json()

    # 3. Update UDFs via Service Layer
    patch = {
        "U_TB_Status": "Acknowledged" if resp.ok and data.get("acknowledged") else "Rejected",
        "U_TB_UUID": data.get("uuid", ""),
        "U_TB_AckRef": data.get("ackRef", ""),
        "U_TB_Reject": json.dumps(data) if not resp.ok else ""
    }
    requests.patch(
        f"{B1_BASE}/Invoices({inv['DocEntry']})",
        cookies=cookies,
        json=patch
    )

SAP S/4HANA Setup

For S/4HANA, use an OData service that exposes billing documents. The standard API is API_BILLING_DOCUMENT_SRV; if it is not enabled, your SAP Basis team can activate it via SICF and generate the service.

GET https://s4host:port/sap/opu/odata/sap/API_BILLING_DOCUMENT_SRV/A_BillingDocument('90000000')
  ?$expand=to_Item,to_Partner
  &sap-client=100
Accept: application/json
x-csrf-token: fetch
Authorization: Basic <base64(user:pass)>

After fetching the billing document and partner data, the transformation into TrustBill JSON is identical to the Business One flow. The main difference is the OData field names: BillingDocument, BillingDocumentItem, Customer and NetAmount.

SAP → TrustBill Field Mapping

UAE VAT / Tax Mapping

Map SAP tax code percentages to FTA tax category codes. The most common SAP tax codes for the UAE are OA5 (5% standard), OA0 (zero), OAE (exempt) and OAR (reverse charge).

Credit Notes

SAP credit memos / credit notes are mapped to TrustBill credit-note endpoint. Include the original SAP invoice number and a negative gross amount.

POST https://trustbill.ae/api/v1/credit-notes
{
  "originalInvoiceNumber": "90000001",
  "issueDate": "2026-09-08",
  "creditNoteNumber": "90000010",
  "reason": "Goods return",
  "totals": {
    "grossAmount": -525.00
  }
}

Status Tracking

TrustBill can call a webhook to your middleware or SAP gateway. The payload includes the invoice number, new status, acknowledgement reference and reason.

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

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

Your middleware then writes the status back to the SAP UDFs using the Service Layer PATCH, OData UPDATE or BAPI update method.

Bulk Migration

For historical invoices, export from SAP using SE16N, a custom query, or the OData service with a date filter. The CSV must contain the same columns as the field mapping table above.

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

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

Sandbox & Live Modes

Test end-to-end without touching the FTA. Switch to live once your FTA registration and ASP assignment are complete.

Multi-Company Code & Multi-Currency

SAP is frequently deployed with several company codes sharing one client — for example a UAE mainland entity and a free-zone entity, or a holding company with multiple UAE branches. TrustBill treats each company code as an independent seller with its own TRN, so the mapping layer must resolve the correct TrustBill profile per company code before submission.

Error Handling & API Errors

Design the SAP-side connector to treat every non-2xx TrustBill response as retryable-or-not based on the HTTP status, and always log the response body for audit.

Setup Checklist

Troubleshooting

• 422 validation error: Check that buyer TRN is 15 digits and that company TRN is set in SAP.
• SAP CSRF token error (S/4HANA): Fetch a fresh token with GET .../A_BillingDocument?$top=1 and x-csrf-token: fetch before POST/UPDATE.
• Service Layer 401: Renew the session cookie before it expires; the default timeout is 30 minutes.
• Missing Arabic names: Use the ForeignName or custom UDF to store Arabic legal names and map them to the payload.
• S/4HANA OData not found: Activate the required service in /IWFND/MAINT_SERVICE and assign the user to the correct authorization role.

Support

Need help with the SAP integration? Our team can review your Service Layer, OData, RFC or IDoc setup and provide a tailored middleware blueprint.