Sage X3 API Landscape — Research Findings

Overview: Three API Types

Sage X3 exposes three distinct API layers, each suited to different integration scenarios:

1. GraphQL API (Newest — V12+, via Sage X3 Builder)

Architecture: Syracuse server → GraphQL endpoint → Node-based schema Auth: OAuth2 (Authorization Code flow) Best for: Modern integrations, complex queries, typed schema

Key Concepts:

Nodes: Data models published as GraphQL types (e.g., SalesInvoice, PurchaseOrder, Customer)
Operations/Mutations: GraphQL mutations linked to X3 functions (subprograms, windows, classes, import templates)
Node Bindings: Customization of API nodes and properties
Packages: Organizational units for nodes in the GraphQL schema

Example Query (Purchasing):

{
  x3Purchasing {
    purchaseOrder {
      query(filter: "{purchaseSite: 'FR011', orderFromSupplier: 'FR053', isClosed: {_ne: 'yes'}}") {
        edges {
          node {
            id
            purchaseSite { code }
            receiptSite { code }
            orderFromSupplier { code { code } }
            isClosed
            receiptStatus
            signatureStatus
            purchaseOrderLines { query { edges { node { orderedQuantity } } } }
          }
        }
      }
    }
  }
}

Modules Available: x3Sales, x3Purchasing, x3Financials, x3CommonData, x3Manufacturing, x3Stock

Authorization Flow (OAuth2):

GET https://api.myregion-sagex3.com/v1/token/authorise with client_id, scope, redirect_uri
User approves in Sage X3 UI, selects folder(s)
App receives callback with authorization code
Exchange code for access token + refresh token

2. REST Web Services (V7+ style — Syracuse/SData)

Architecture: Syracuse server → REST endpoints → Classes + Representations Auth: Basic, Client Certificate (on-prem), OAuth2 (cloud) Best for: Standard CRUD operations on business objects

URL Pattern:

http://SERVER:PORT/api1/x3/erp/ENDPOINT/CLASS?representation=REPR.$query

Parameters:

count=N — pagination (default 20)
startRecord=N — pagination offset
orderBy=field asc|desc — sorting
where=condition — filtering

Example: Query customers

GET http://server:8124/api1/x3/erp/X3/BPCUSTOMER?representation=BPCUSTOMER.$query&count=50

Key Entities: BPCUSTOMER, SINVOICE (sales invoice), SORDER (sales order), PORDER (purchase order), etc.

3. SOAP Web Services (Legacy V6 style)

Architecture: Syracuse server → SOAP pool → X3 classic programs/subprograms Auth: Basic (username/password in request), Bearer Token Best for: Legacy integrations, subprogram calls, complex object manipulation

WSDL Endpoint:

http://SERVER:PORT/soap-wsdl/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC?wsdl

Operations: read, save, delete, query, run (subprogram), getDescription

Call Context:

<callContext xsi:type="wss:CAdxCallContext">
   <codeLang xsi:type="xsd:string">ENG</codeLang>
   <poolAlias xsi:type="xsd:string">POOL_NAME</poolAlias>
   <poolId xsi:type="xsd:string"></poolId>
   <requestConfig xsi:type="xsd:string">adxwss.optreturn=JSON&adxwss.beautify=true</requestConfig>
</callContext>

Response Format: XML or JSON (configurable via adxwss.optreturn)

SIH (Sales Invoice) Example Description:

Fields: SALFCY (Sales site), SIVTYP (Type), NUM (Invoice no.), BPCINV (Bill-to customer), CUR (Currency), INVDAT (Date)
Methods: READ, CREATE, MODIFY, DELETE, LIST
Read key: NUM (Invoice number)

Authentication Summary

API Type	On-Premise	Cloud
GraphQL	OAuth2	OAuth2
REST	Basic, Client Cert, OAuth2	OAuth2
SOAP	Basic Auth, Bearer Token	OAuth2

Key Business Objects (Common Names)

Object Code	Description	SOAP Public Name
SIH	Sales Invoice Header	SIH / WSIH
SIV	Sales Invoice	WSIV
SOH	Sales Order Header	SOH
SOQ	Sales Quote	SOQ
POH	Purchase Order Header	POH
BPC	Business Partner Customer	WSBPC
BPS	Business Partner Supplier	WSBPS
ITM	Item/Product	WITM
STK	Stock	—

Integration Architecture Notes

Syracuse Server is the middleware layer for all APIs
SOAP uses connection pools with configurable channels
REST uses representations (views of data) and classes (business objects)
GraphQL uses nodes (data models) with operations (mutations)
Licensing controls data volume for SOAP (WSSIZELIMIT per period)
On-premise vs Cloud affects auth options and file/DB integration access

4.6 KiB Raw Permalink Blame History