# 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)**:
```graphql
{
  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):
1. GET `https://api.myregion-sagex3.com/v1/token/authorise` with client_id, scope, redirect_uri
2. User approves in Sage X3 UI, selects folder(s)
3. App receives callback with authorization code
4. 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**:
```xml
<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