SAP
SAPService → SAPAdapter → SAP OData API
Business logic
OData param building
Response mapping
Pagination handling
Auth injection
CSRF token fetch
OData serialization
x-csrf-token header
S/4HANA Cloud
SAP Business One
OData v2 / v4
JSON + XML formats
- Client credentials flow (machine-to-machine)
- POST to SAP token endpoint
- Bearer token in Authorization header
- Fetch CSRF token via GET before writes
Base64(username:password)
Authorization: Basic …
SAP_CLIENT header (optional)
Fetch CSRF token via GET before writes
What & Why
SAP is the backbone of enterprise resource planning. The Octopus SAP integration exposes procurement, vendor, materials, and financial data from SAP S/4HANA Cloud or SAP Business One through a single consistent OData adapter pattern.
The SAPAdapter handles both auth modes: OAuth 2.0 via SAP BTP (the standard for cloud deployments) and Basic Auth (common for on-premise and legacy systems). Both modes share identical method signatures so switching auth doesn't change calling code.
Write operations require a CSRF token. The adapter automatically fetches a CSRF token via a GET request (with x-csrf-token: Fetch header) before any POST or PATCH, then injects the returned token into the write request. This is transparent to callers.
SAP data volumes are large and write operations should not be run at high frequency. The integration is primarily designed for reading procurement and financial data, enabling cross-system workflows — for example: when a GitHub issue is resolved, look up the related SAP purchase order to confirm budget allocation or delivery status.
Filter, Select, Expand, Paginate
Vendor eq 'V001'
Amount gt 10000
Status eq 'Active'
PONumber
Amount,Currency
VendorName
to_Items
to_Vendor
to_AccountAssignment
$top=50
$skip=100
page through results
GET /sap/opu/odata/sap/API_PURCHASEORDER_PROCESS_SRV/A_PurchaseOrder
?$filter=Vendor eq 'V001'
&$select=PurchaseOrder,Vendor,TotalNetAmount,Currency
&$expand=to_PurchaseOrderItem
&$top=50&$skip=0
&$format=json
x-csrf-token: Fetch
set-cookie: sap-usercontext
x-csrf-token: abc123
Methods Reference
All 8 methods grouped by category.
Purchase Orders
| Method | Description | Key Params |
|---|---|---|
list_purchase_orders | List purchase orders with optional filtering | vendor, company_code, status, top, skip |
get_purchase_order | Get full details for a single purchase order | po_number |
create_purchase_order | Create a new purchase order (CSRF required) | vendor, company_code, items, delivery_date, currency |
Vendors
| Method | Description | Key Params |
|---|---|---|
list_vendors | List vendors registered in the system | company_code, top, skip |
get_vendor | Get vendor master data by vendor ID | vendor_id |
Materials
| Method | Description | Key Params |
|---|---|---|
list_materials | List material master records | plant, material_type, top, skip |
get_material | Get material master data by material ID | material_id |
Finance
| Method | Description | Key Params |
|---|---|---|
list_gl_accounts | List General Ledger accounts | company_code, top, skip |
get_cost_center | Get cost center details | cost_center, controlling_area |
get_profit_center | Get profit center details | profit_center, controlling_area |
Setup & CLI Reference
Required Configuration
OAuth 2.0 (SAP BTP / Cloud Platform):
SAP_BASE_URL=https://your-sap-system.s4hana.cloud.sap
SAP_CLIENT_ID=your-client-id
SAP_CLIENT_SECRET=your-client-secret
SAP_TOKEN_URL=https://your-subaccount.authentication.eu10.hana.ondemand.com/oauth/token
Basic Auth (Legacy / On-Premise):
SAP_BASE_URL=https://your-sap-host:44300
SAP_USERNAME=your-sap-user
SAP_PASSWORD=your-sap-password
SAP_CLIENT=100
CLI Examples
# List purchase orders for a vendor
constellation sap list-purchase-orders --vendor V001 --top 20
# Get a specific purchase order
constellation sap get-purchase-order --po-number 4500001234
# Create a purchase order
constellation sap create-purchase-order \
--vendor V001 \
--company-code 1000 \
--currency EUR \
--delivery-date 2026-06-30
# List vendors in a company code
constellation sap list-vendors --company-code 1000
# Get vendor master data
constellation sap get-vendor --vendor-id V001
# List materials for a plant
constellation sap list-materials --plant 1000 --top 50
# Get material details
constellation sap get-material --material-id 1000234
# List GL accounts
constellation sap list-gl-accounts --company-code 1000
# Get cost center
constellation sap get-cost-center --cost-center CC1000 --controlling-area A000
# Get profit center
constellation sap get-profit-center --profit-center PC1000 --controlling-area A000
HTTP API
# List purchase orders via HTTP
curl -X POST https://api.yourdomain.com/sap/list-purchase-orders \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"vendor": "V001", "top": 20}'
# Response
# {
# "purchase_orders": [
# {"PurchaseOrder": "4500001234", "Vendor": "V001", "TotalNetAmount": "50000.00", "Currency": "EUR"}
# ]
# }
# Get purchase order detail via HTTP
curl -X POST https://api.yourdomain.com/sap/get-purchase-order \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"po_number": "4500001234"}'
# List vendors via HTTP
curl -X POST https://api.yourdomain.com/sap/list-vendors \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"company_code": "1000", "top": 50}'
Usage Notes
- Data volumes: SAP entities can return thousands of records. Always use
--topto limit result size. Start with--top 20and paginate with--skip. - CSRF tokens: Automatically managed by the adapter. No manual token handling needed.
- OData version: Most SAP S/4HANA Cloud APIs use OData v2. Check your system's service catalog at
/sap/opu/odata/sap/for available services and their paths. - Write frequency: SAP is an ERP, not a message bus. Avoid high-frequency write operations. Batch or schedule bulk updates.
- Company code: Most financial and procurement operations are scoped to a company code (e.g.
1000). Confirm your system's codes before querying.