---
# === IDENTITY ===
id: business/erp-integration/oracle-financials-cloud-api/2026
canonical_question: "What are the Oracle Financials Cloud API capabilities - GL, AP, AR, FA, journal import, intercompany?"
aliases:
  - "Oracle Fusion Cloud Financials REST API endpoints and rate limits"
  - "Oracle ERP Cloud GL journal import API vs FBDI"
  - "Oracle Cloud AP invoice API capabilities and integration patterns"
  - "Oracle Financials Cloud intercompany and subledger accounting API"
entity_type: erp_integration
domain: business > erp-integration > oracle-financials-cloud-api
region: global
jurisdiction: global
temporal_scope: 2024-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Oracle Fusion Cloud Financials"
    vendor: "Oracle"
    version: "Release 25D / 26A (API v11.13.18.05)"
    edition: "Enterprise"
    deployment: cloud
    api_surface: "REST, SOAP, FBDI (File-Based Data Import)"

# === VERIFICATION ===
last_verified: 2026-03-09
confidence: 0.88
version: 1.0
first_published: 2026-03-09

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: volatile
  last_breaking_change: "26A (January 2026) - new Payables Interface Invoices actions"
  next_review: 2026-09-05
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "REST API POST operations: limit payloads to 500 records per request for reliable processing"
  - "FBDI file uploads: max 250 MB per ZIP file uploaded to UCM (WebCenter Content)"
  - "No official published per-minute or per-day API rate limits — Oracle uses fair-use throttling with HTTP 429 responses"
  - "Journal Import via REST requires two-step process: upload FBDI file to UCM, then submit ESS job via erpintegrations endpoint"
  - "REST API does not support direct GL journal line creation — must use journalBatches parent resource with child journalHeaders and journalLines"
  - "Intercompany transactions cannot be created via REST — use FBDI template fin/intercompany/import with ESS job"
  - "Fixed Assets mass additions require FBDI — REST API covers asset queries and updates only"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User needs Oracle E-Business Suite (EBS) Financials APIs — on-premise, different API surface"
    use_instead: "N/A — EBS uses PL/SQL APIs and SOAP, not covered here"
  - condition: "User needs Oracle NetSuite Financials APIs — separate product line"
    use_instead: "Search knowledgelib.io for NetSuite APIs (SuiteTalk, SuiteQL, RESTlet) - no financials unit yet"
  - condition: "User needs Oracle SCM or HCM REST APIs — different API documentation set"
    use_instead: "N/A — SCM and HCM have separate API references"

# === AGENT HINTS ===
inputs_needed:
  - key: integration_pattern
    question: "What integration pattern do you need?"
    type: choice
    options:
      - "real-time sync (individual records, <1s latency)"
      - "batch/bulk (scheduled, high volume)"
      - "event-driven (Business Events, ERP callbacks)"
      - "file-based (FBDI CSV/XML import/export)"
  - key: data_volume
    question: "What's your daily data volume?"
    type: choice
    options:
      - "< 1,000 records/day"
      - "1,000-100,000 records/day"
      - "> 100,000 records/day"
  - key: direction
    question: "What's the data flow direction?"
    type: choice
    options:
      - "inbound (writing to Oracle Financials)"
      - "outbound (reading from Oracle Financials)"
      - "bidirectional sync"

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/business/erp-integration/oracle-financials-cloud-api/2026"
suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-03-09)"

# === RELATED UNITS ===
related_kos:
  depends_on: []
  related_to: []
  solves: []
  alternative_to: []
  often_confused_with: []

# === SOURCES (6 authoritative sources) ===
sources:
  - id: src1
    title: "REST API for Oracle Fusion Cloud Financials — All REST Endpoints (25D)"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/financials/25d/farfa/rest-endpoints.html
    type: official_docs
    published: 2025-10-01
    reliability: authoritative
  - id: src2
    title: "REST API for Oracle Fusion Cloud Financials — Quick Start (25A)"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/financials/25a/farfa/Quick_Start.html
    type: official_docs
    published: 2025-04-01
    reliability: authoritative
  - id: src3
    title: "Oracle Financials Cloud API Integration Guide: REST & OAuth 2.0"
    author: Knit
    url: https://www.getknit.dev/blog/oracle-financials-api-integration-guide-rest-oauth-2-0
    type: technical_blog
    published: 2025-06-15
    reliability: moderate_high
  - id: src4
    title: "Oracle Fusion Cloud ERP Integration Challenges, Patterns & Use Cases"
    author: Oracle A-Team
    url: https://www.ateam-oracle.com/oracle-fusion-cloud-erp-applications-integrations-guidelines-patternsuse-cases-using-oracle-paas
    type: technical_blog
    published: 2024-09-01
    reliability: high
  - id: src5
    title: "File-Based Data Import (FBDI) for Financials — Intercompany Transaction Import"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/financials/25a/oefbf/intercompanytransactionimport-3042.html
    type: official_docs
    published: 2025-04-01
    reliability: authoritative
  - id: src6
    title: "REST API for Oracle Fusion Cloud Financials — Invoices REST Endpoints (25D)"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/financials/25d/farfa/api-invoices.html
    type: official_docs
    published: 2025-10-01
    reliability: authoritative
---

# Oracle Financials Cloud API Capabilities — GL, AP, AR, FA, Journal Import, Intercompany

## TL;DR

- **Bottom line**: Oracle Fusion Cloud Financials exposes 100+ REST endpoints across GL, AP, AR, Cash Management, Expenses, and Collections — but high-volume or complex operations (journal import, intercompany, FA mass additions) require FBDI file uploads through the erpintegrations endpoint, not direct REST CRUD.
- **Key limit**: REST POST operations should be limited to 500 records per request; FBDI ZIP files max 250 MB; Oracle enforces fair-use throttling (no published hard rate limits) returning HTTP 429 when exceeded.
- **Watch out for**: Journal import is a two-step async process (upload FBDI CSV to UCM, then submit ESS job) — agents often recommend direct REST POST to a journals endpoint, which does not exist for bulk import.
- **Best for**: Real-time individual record operations (create/read/update AP invoices, query GL balances, manage AR receipts) under 500 records per request; use FBDI for anything above that threshold.
- **Authentication**: OAuth 2.0 Client Credentials via Oracle IDCS (3600s token lifetime, no refresh tokens — re-authenticate on expiry); Basic Auth over SSL also supported but not recommended for production.

## System Profile

Oracle Fusion Cloud Financials (also branded Oracle Financials Cloud or Oracle Cloud ERP — Financials pillar) is Oracle's SaaS ERP financial suite. The REST API surface covers General Ledger, Accounts Payable, Accounts Receivable, Cash Management, Expenses, Collections, Tax, and related configuration objects. The API version is tied to Oracle's quarterly release cycle (e.g., 25A, 25B, 25C, 25D, 26A), with the REST resource version remaining at 11.13.18.05 across releases while new endpoints and actions are added each quarter. [src1]

This card covers Oracle Fusion Cloud Financials only — not Oracle E-Business Suite (on-premise, PL/SQL APIs), Oracle NetSuite (separate SaaS product with SuiteTalk/REST APIs), or Oracle Cloud Infrastructure (IaaS). Fixed Assets, Intercompany, and Subledger Accounting have limited REST coverage — bulk operations for these modules require FBDI. [src4]

| Property | Value |
|---|---|
| **Vendor** | Oracle |
| **System** | Oracle Fusion Cloud Financials (Release 25D / 26A) |
| **API Surface** | REST (primary), SOAP (legacy), FBDI (bulk) |
| **Current API Version** | 11.13.18.05 (resource version, stable across releases) |
| **Editions Covered** | Enterprise (single edition for cloud) |
| **Deployment** | Cloud (Oracle Cloud Infrastructure) |
| **API Docs URL** | [Oracle Fusion Cloud Financials REST API](https://docs.oracle.com/en/cloud/saas/financials/25d/farfa/rest-endpoints.html) |
| **Status** | GA — quarterly feature releases (25A through 26A+) |

## API Surfaces & Capabilities

Oracle Financials Cloud offers three primary integration surfaces, each suited to different volume and latency requirements. The REST API handles real-time CRUD, FBDI handles bulk imports via file upload, and SOAP remains available for legacy integrations. [src1, src4]

| API Surface | Protocol | Best For | Max Records/Request | Rate Limit | Real-time? | Bulk? |
|---|---|---|---|---|---|---|
| REST API | HTTPS/JSON | Individual record CRUD, queries, real-time operations | 500 (POST), pagination for GET | Fair-use throttling (429) | Yes | No |
| FBDI (File-Based Data Import) | CSV/ZIP via UCM + ESS | Bulk data loads, migrations, journal import, intercompany | 250 MB per ZIP file | ESS job queue (serial per job type) | No | Yes |
| SOAP Web Services | HTTPS/XML | Legacy integrations, metadata operations | Varies by service | Shared with REST | Yes | No |
| ERP Business Events | HTTPS/JSON (callback) | Event-driven outbound notifications | N/A (push-based) | Configurable per event | Yes | N/A |
| BI Publisher Reports | HTTPS/XML or CSV | Bulk data extraction, scheduled reports | Report-dependent | ESS scheduler | No | Yes |
| ERP Integrations REST | HTTPS/JSON + file | Orchestrating FBDI uploads + ESS job submission | 1 file per request | ESS job queue | No | Yes |

## Rate Limits & Quotas

### Per-Request Limits

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| Max records per POST | 500 | REST API (all modules) | Oracle recommends limiting to 500 for reliable processing [src4] |
| Max FBDI ZIP file size | 250 MB | UCM file upload | Split larger data sets into multiple files |
| Max response page size | 25 items default, configurable via limit parameter | REST API GET | Use offset + limit for pagination |
| Max request body size | Not officially published | REST API | Practical limit ~10 MB for JSON payloads |
| Concurrent ESS jobs | 1 per job type (serial) | FBDI import jobs | Multiple different job types can run in parallel |
| Max attachment size | 2 GB | REST API attachments | Per-file limit for document uploads |

[src1, src2]

### Rolling / Daily Limits

| Limit Type | Value | Window | Edition Differences |
|---|---|---|---|
| REST API calls | No published hard limit | Fair-use | Oracle uses dynamic throttling — returns 429 when threshold exceeded |
| ESS job submissions | No published hard limit | Per pod | Queued and serialized per job type; concurrent cross-type |
| UCM file uploads | No published hard limit | Per pod | Practical limit driven by storage quota |
| BI Publisher report runs | No published hard limit | Per pod | Subject to ESS scheduler capacity |

[src2, src3]

### Throttling Behavior

Oracle Fusion Cloud does not publish fixed API rate limits like Salesforce. Instead, it applies fair-use throttling at the pod level. When throttled, the API returns HTTP 429 with a Retry-After header. The throttling threshold varies by pod load, time of day, and tenant configuration. There is no self-service way to check remaining quota — you must implement 429 handling with exponential backoff. [src3]

## Authentication

| Flow | Use When | Token Lifetime | Refresh? | Notes |
|---|---|---|---|---|
| OAuth 2.0 Client Credentials | Server-to-server integrations (recommended) | 3600 seconds | No (re-authenticate) | Register Confidential Application in Oracle IDCS [src3] |
| Basic Auth over SSL | Testing, simple integrations | Session-based | N/A | Username + password; not recommended for production |
| SAML 2.0 Bearer Token | SSO-federated user-context operations | Session timeout | N/A | SAML assertion in HTTP header over SSL |
| JWT Bearer Token | Service account access | Configurable | N/A | JWT in HTTP header over SSL [src2] |

[src2, src3]

### Authentication Gotchas

- Client Credentials flow via Oracle IDCS does not provide refresh tokens — your integration must re-authenticate every 3600 seconds by requesting a new access token. Hardcoding token expiry is risky because IDCS administrators can change the timeout. [src3]
- The integration user (service account) must have the correct Oracle Financials duty roles assigned — API calls execute under the integration user's security context, and missing roles produce HTTP 403, not 401. [src2]
- IDCS token endpoint URL varies by data center region: `https://{identity-domain}.identity.oraclecloud.com/oauth2/v1/token`. Using the wrong region endpoint returns connection errors, not auth errors. [src3]
- Basic Auth requires the user to have MFA disabled or exempted — if MFA is enforced org-wide, Basic Auth breaks silently with 401 responses. [src3]

## Constraints
<!-- Agents: read this section before recommending any integration approach from this unit.
     These are hard constraints that must not be violated. -->

- GL journals cannot be created in bulk via REST POST — journal import requires FBDI file upload to UCM (Universal Content Management) followed by ESS job submission via the erpintegrations endpoint. Direct REST on journalBatches creates individual journal batches only. [src1, src4]
- Intercompany transactions have no REST API for creation — the only supported inbound path is FBDI template `fin/intercompany/import` uploaded via the erpintegrations endpoint. Query-only REST access may be available for read operations. [src5]
- Fixed Assets mass additions require FBDI — REST API covers asset queries and individual updates but not bulk asset creation or mass addition import. [src4]
- Subledger Accounting journal entries are generated by internal ESS processes (Create Accounting) — they cannot be directly created or modified via REST API. External systems trigger Create Accounting via ESS job submission. [src4]
- FBDI imports are asynchronous — after uploading the file and submitting the ESS job, you must poll for job completion. There is no webhook callback for FBDI job completion out of the box (requires custom Business Events configuration). [src4]
- REST API resource version 11.13.18.05 is the current stable version across all releases — Oracle does not version-bump the resource path with each quarterly release, but new endpoints and actions are silently added. [src1]
- All REST API requests require HTTPS — HTTP is not supported. Self-signed certificates are rejected in production environments. [src2]

## Integration Pattern Decision Tree

```
START — User needs to integrate with Oracle Financials Cloud
├── What's the financial module?
│   ├── General Ledger (GL)
│   │   ├── Query balances / periods / ledgers?
│   │   │   └── YES → REST API: GET /ledgerBalances, /accountingPeriods
│   │   ├── Create individual journal entries?
│   │   │   ├── < 10 journals → REST API: POST /journalBatches (with child headers + lines)
│   │   │   └── > 10 journals → FBDI journal import (GlInterface.csv → ESS Import Journals)
│   │   └── Bulk journal import (migration, subledger feed)?
│   │       └── ALWAYS → FBDI: upload CSV to UCM → POST /erpintegrations to run Import Journals
│   ├── Accounts Payable (AP)
│   │   ├── Create/update individual invoices?
│   │   │   ├── < 500 invoices → REST API: POST /invoices
│   │   │   └── > 500 invoices → FBDI: AP Invoice Import or REST /payablesInterfaceInvoices
│   │   ├── Query invoices / payments / suppliers?
│   │   │   └── YES → REST API: GET /invoices, /payablesPayments, /suppliers
│   │   └── Bulk invoice import (migration)?
│   │       └── FBDI: ApInvoicesInterface.csv → ESS Import Payables Invoices
│   ├── Accounts Receivable (AR)
│   │   ├── Create/update individual transactions?
│   │   │   ├── < 500 transactions → REST API: POST /receivablesInvoices
│   │   │   └── > 500 transactions → FBDI: AutoInvoice import
│   │   ├── Apply receipts?
│   │   │   └── REST API: POST /standardReceiptApplications or FBDI for bulk
│   │   └── Query AR balances / aging?
│   │       └── REST API: GET /receivablesInvoices or BI Publisher report
│   ├── Fixed Assets (FA)
│   │   ├── Query existing assets?
│   │   │   └── REST API: GET /assets (limited)
│   │   └── Bulk asset creation / mass additions?
│   │       └── ALWAYS → FBDI: FA Mass Additions import
│   ├── Intercompany
│   │   └── Create intercompany transactions?
│   │       └── ALWAYS → FBDI: fin/intercompany/import template
│   └── Cash Management
│       └── Bank accounts, transfers, reconciliation?
│           └── REST API: /cashBankAccounts, /cashBankAccountTransfers
├── What integration pattern?
│   ├── Real-time (< 500 records) → REST API
│   ├── Batch/Bulk (> 500 records) → FBDI via erpintegrations
│   ├── Event-driven (outbound) → ERP Business Events + callback
│   └── Scheduled extraction → BI Publisher reports via ESS
├── Which direction?
│   ├── Inbound (writing) → REST POST/PATCH or FBDI upload
│   ├── Outbound (reading) → REST GET or BI Publisher
│   └── Bidirectional → REST for real-time + FBDI for bulk inbound + BI Publisher for bulk outbound
└── Error tolerance?
    ├── Zero-loss required → FBDI with ESS job status polling + error report download
    └── Best-effort → REST with retry on 429/5xx
```

## Quick Reference

### Key REST Endpoints by Module

| Module | Resource | Endpoint Path | Operations | Notes |
|---|---|---|---|---|
| GL — Journals | journalBatches | /fscmRestApi/resources/11.13.18.05/journalBatches | GET, POST, PATCH | Child: journalHeaders, journalLines |
| GL — Balances | ledgerBalances | /fscmRestApi/resources/11.13.18.05/ledgerBalances | GET | Query by ledger, period, account |
| GL — Periods | accountingPeriods | /fscmRestApi/resources/11.13.18.05/accountingPeriods | GET, PATCH | Open/close periods |
| AP — Invoices | invoices | /fscmRestApi/resources/11.13.18.05/invoices | GET, POST, PATCH, DELETE | Full CRUD; child: invoiceLines, invoiceDistributions |
| AP — Interface | payablesInterfaceInvoices | /fscmRestApi/resources/11.13.18.05/payablesInterfaceInvoices | GET, POST | Staging table for import; submit import action |
| AP — Payments | payablesPayments | /fscmRestApi/resources/11.13.18.05/payablesPayments | GET | Read-only payment details |
| AP — Suppliers | suppliers | /fscmRestApi/resources/11.13.18.05/suppliers | GET, POST, PATCH | Supplier master management |
| AR — Invoices | receivablesInvoices | /fscmRestApi/resources/11.13.18.05/receivablesInvoices | GET, POST, PATCH | Child: installments, distributions |
| AR — Credit Memos | receivablesCreditMemos | /fscmRestApi/resources/11.13.18.05/receivablesCreditMemos | GET, POST, PATCH | Credit memo transactions |
| AR — Receipts | standardReceipts | /fscmRestApi/resources/11.13.18.05/standardReceipts | GET, POST | Cash receipt creation |
| AR — Receipt Application | standardReceiptApplications | /fscmRestApi/resources/11.13.18.05/standardReceiptApplications | POST | Apply receipts to invoices |
| Cash Mgmt | cashBankAccounts | /fscmRestApi/resources/11.13.18.05/cashBankAccounts | GET, POST, PATCH | Bank account management |
| Cash Mgmt | cashBankAccountTransfers | /fscmRestApi/resources/11.13.18.05/cashBankAccountTransfers | GET, POST, PATCH | Inter-bank transfers |
| Collections | collectionsDelinquencies | /fscmRestApi/resources/11.13.18.05/collectionsDelinquencies | GET, POST, PATCH | Delinquency management |
| Expenses | expenseReports | /fscmRestApi/resources/11.13.18.05/expenseReports | GET, POST, PATCH | Submit action available |
| ERP Integration | erpintegrations | /fscmRestApi/resources/11.13.18.05/erpintegrations | GET, POST | FBDI file upload + ESS job submission |
| Business Events | erpBusinessEvents | /fscmRestApi/resources/11.13.18.05/erpBusinessEvents | GET, PATCH | Enable/disable event subscriptions |

[src1, src6]

## Step-by-Step Integration Guide

### 1. Authenticate via OAuth 2.0 Client Credentials

Register a Confidential Application in Oracle IDCS, obtain Client ID and Client Secret, then request an access token. [src3]

```bash
# Input:  IDCS Client ID, Client Secret, Identity Domain URL
# Output: Access token (JWT, 3600s lifetime)

curl -X POST \
  "https://{identity-domain}.identity.oraclecloud.com/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all"
```

**Verify**: Response contains `"access_token"` field and `"expires_in": 3600`

### 2. Query GL Ledger Balances

Use the ledgerBalances endpoint to retrieve account balances for a specific ledger and period. [src1]

```bash
# Input:  Access token, ledger name, accounting period
# Output: JSON array of account balances

curl -X GET \
  "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/ledgerBalances?q=LedgerName=US%20Primary%20Ledger;AccountingPeriod=Mar-26" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"
```

**Verify**: Response contains `"items"` array with `AccountCombination`, `CurrentPeriodBalance` fields

### 3. Create an AP Invoice via REST

POST a new invoice to the invoices endpoint. Include header fields and invoice lines as nested child resources. [src6]

```bash
# Input:  Access token, supplier info, invoice details
# Output: Invoice ID and status

curl -X POST \
  "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" \
  -d '{
    "InvoiceNumber": "INV-2026-001",
    "InvoiceCurrency": "USD",
    "InvoiceAmount": 5000,
    "InvoiceDate": "2026-03-09",
    "BusinessUnit": "US1 Business Unit",
    "Supplier": "Acme Corp",
    "SupplierSite": "HQ",
    "invoiceLines": [{
      "LineNumber": 1,
      "LineAmount": 5000,
      "Description": "Consulting services March 2026"
    }]
  }'
```

**Verify**: Response HTTP 201 with `InvoiceId` populated

### 4. Upload FBDI File for GL Journal Import

For bulk journal import, prepare a CSV file matching the GlInterface FBDI template, ZIP it, upload to UCM via erpintegrations, then submit the Import Journals ESS job. [src4, src5]

```bash
# Step 4a: Upload FBDI ZIP to UCM
# Input:  Base64-encoded ZIP file containing GlInterface.csv
# Output: Document ID in UCM

curl -X POST \
  "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" \
  -d '{
    "OperationName": "importBulkData",
    "DocumentContent": "{base64_encoded_zip}",
    "ContentType": "zip",
    "FileName": "GlInterface.zip",
    "DocumentAccount": "fin$/journal$/import$"
  }'

# Step 4b: Submit Import Journals ESS Job
curl -X POST \
  "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" \
  -d '{
    "OperationName": "submitESSJobRequest",
    "JobPackageName": "/oracle/apps/ess/financials/generalLedger/programs/",
    "JobDefName": "JournalImportLauncher",
    "ESSParameters": "300000001234567,1,US Primary Ledger"
  }'
```

**Verify**: Poll `GET /erpintegrations/{RequestId}` until `RequestStatus` = `SUCCEEDED`

### 5. Create an AR Invoice

POST a receivables invoice for customer billing. [src1]

```bash
# Input:  Access token, customer info, transaction details
# Output: CustomerTransactionId

curl -X POST \
  "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/receivablesInvoices" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" \
  -d '{
    "BusinessUnit": "US1 Business Unit",
    "TransactionDate": "2026-03-09",
    "TransactionType": "Invoice",
    "BillToCustomerName": "GlobalTech Inc",
    "BillToCustomerNumber": "CUST-001",
    "CurrencyCode": "USD"
  }'
```

**Verify**: Response HTTP 201 with `CustomerTransactionId` populated

### 6. Handle Pagination for Large Result Sets

Oracle REST API returns paginated results with `hasMore`, `offset`, and `limit` parameters. [src2]

```python
# Input:  API base URL, access token
# Output: Complete list of all AP invoices

import requests

base_url = "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05"
headers = {"Authorization": f"Bearer {access_token}"}
all_invoices = []
offset = 0
limit = 25  # default page size; max varies by resource

while True:
    resp = requests.get(
        f"{base_url}/invoices",
        headers=headers,
        params={"offset": offset, "limit": limit, "onlyData": "true"}
    )
    resp.raise_for_status()
    data = resp.json()
    all_invoices.extend(data.get("items", []))
    if not data.get("hasMore", False):
        break
    offset += limit
```

**Verify**: `len(all_invoices)` matches expected count; last page has `"hasMore": false`

### 7. Implement Retry Logic for 429 Throttling

Oracle returns HTTP 429 when fair-use throttling kicks in. Implement exponential backoff. [src3]

```python
import time
import requests

def oracle_api_call(url, headers, method="GET", data=None, max_retries=5):
    for attempt in range(max_retries):
        if method == "GET":
            resp = requests.get(url, headers=headers)
        else:
            resp = requests.post(url, headers=headers, json=data)

        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(retry_after)
            continue
        elif resp.status_code >= 500:
            time.sleep(2 ** attempt)
            continue
        else:
            resp.raise_for_status()
            return resp.json()

    raise Exception(f"Max retries ({max_retries}) exceeded for {url}")
```

**Verify**: Function returns data on 200; retries on 429/5xx; raises after max retries

## Code Examples

### Python: Create AP Invoice with Error Handling

```python
# Input:  Oracle Fusion host, OAuth token, invoice data dict
# Output: Created invoice ID or error details

import requests  # requests==2.31.0

def create_ap_invoice(host, token, invoice_data):
    url = f"https://{host}/fscmRestApi/resources/11.13.18.05/invoices"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/vnd.oracle.adf.resourceitem+json"
    }
    resp = requests.post(url, headers=headers, json=invoice_data)

    if resp.status_code == 201:
        return {"success": True, "invoice_id": resp.json().get("InvoiceId")}
    elif resp.status_code == 429:
        retry_after = resp.headers.get("Retry-After", "60")
        return {"success": False, "error": "throttled", "retry_after": retry_after}
    else:
        return {"success": False, "status": resp.status_code, "detail": resp.text}
```

### JavaScript/Node.js: Query GL Balances

```javascript
// Input:  Oracle host URL, OAuth token, ledger name, period
// Output: Array of account balance objects

// node-fetch@3.3.2
import fetch from 'node-fetch';

async function getGLBalances(host, token, ledger, period) {
  const url = new URL(`https://${host}/fscmRestApi/resources/11.13.18.05/ledgerBalances`);
  url.searchParams.set('q', `LedgerName=${ledger};AccountingPeriod=${period}`);
  url.searchParams.set('onlyData', 'true');

  const resp = await fetch(url.toString(), {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });

  if (!resp.ok) {
    throw new Error(`GL balance query failed: ${resp.status} ${resp.statusText}`);
  }
  const data = await resp.json();
  return data.items || [];
}
```

### cURL: Test Authentication

```bash
# Input:  IDCS domain, client_id, client_secret
# Output: JSON with access_token field

# Step 1: Get token
curl -s -X POST \
  "https://{idcs-domain}.identity.oraclecloud.com/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all" \
  | python -m json.tool

# Step 2: Test token against a read-only endpoint
curl -s -X GET \
  "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/ledgersLov" \
  -H "Authorization: Bearer {access_token}" \
  | python -m json.tool
```

## Data Mapping

### GL Journal Import — FBDI Field Mapping (GlInterface Template)

| FBDI Column | GL Interface Field | Type | Required | Notes |
|---|---|---|---|---|
| Status | STATUS | String | Yes | Always set to "NEW" for import |
| Ledger Name | LEDGER_NAME | String | Yes | Must match configured ledger exactly |
| Accounting Date | ACCOUNTING_DATE | Date | Yes | Format: YYYY/MM/DD |
| Currency Code | CURRENCY_CODE | String | Yes | ISO 4217 (e.g., USD, EUR) |
| Journal Category | USER_JE_CATEGORY_NAME | String | Yes | Must match defined category |
| Journal Source | USER_JE_SOURCE_NAME | String | Yes | Must match defined source |
| Segment1-30 | SEGMENT1-SEGMENT30 | String | Varies | Account segments per chart of accounts |
| Entered Debit | ENTERED_DR | Number | Conditional | Debit amount in entered currency |
| Entered Credit | ENTERED_CR | Number | Conditional | Credit amount in entered currency |
| Reference (batch name) | REFERENCE1 | String | No | Used as batch name |
| Reference (header name) | REFERENCE4 | String | No | Used as journal header name |

### AP Invoice REST — Key Field Mapping

| REST Field | DB Column | Type | Required | Notes |
|---|---|---|---|---|
| InvoiceNumber | INVOICE_NUM | String | Yes | Must be unique per supplier |
| InvoiceDate | INVOICE_DATE | Date | Yes | Format: YYYY-MM-DD in JSON |
| InvoiceAmount | INVOICE_AMOUNT | Number | Yes | Must match sum of line amounts |
| InvoiceCurrency | INVOICE_CURRENCY_CODE | String | Yes | ISO 4217 |
| Supplier | VENDOR_NAME | String | Yes | Must match supplier master |
| SupplierSite | VENDOR_SITE_CODE | String | Yes | Must match supplier site |
| BusinessUnit | ORG_NAME | String | Yes | Must match configured BU |

### Data Type Gotchas

- Oracle REST dates use ISO 8601 format (YYYY-MM-DD) but FBDI templates use YYYY/MM/DD with forward slashes — mixing formats causes silent import failures with no clear error message. [src1]
- Amount fields in REST use decimal notation (5000.50) but FBDI CSV amounts must not include thousands separators — "5,000.50" fails validation. [src4]
- Account segment values are validated against the chart of accounts value sets during journal import — invalid segments cause the entire batch to reject, not just the offending line. [src4]
- Oracle internally stores all amounts in the ledger currency — if entering in a foreign currency, the conversion rate type and date must be specified or the default corporate rate is applied. [src1]

## Error Handling & Failure Points

### Common Error Codes

| Code | Meaning | Cause | Resolution |
|---|---|---|---|
| 400 | Bad Request | Invalid JSON payload, missing required fields, validation failure | Check field names (case-sensitive), required fields, data types |
| 401 | Unauthorized | Invalid or expired access token | Re-authenticate via OAuth; check token expiry |
| 403 | Forbidden | Integration user lacks required duty role or data access | Assign correct Financials duty roles to integration user |
| 404 | Not Found | Invalid endpoint path or resource ID does not exist | Verify resource version (11.13.18.05) and resource name |
| 409 | Conflict | Record locked by another user/process, or duplicate key | Retry with jitter; check for concurrent operations |
| 429 | Too Many Requests | Fair-use throttling threshold exceeded | Exponential backoff using Retry-After header value |
| 500 | Internal Server Error | Oracle server-side issue, often transient | Retry after 30-60 seconds; check Oracle Cloud status page |
| JE_INVALID_PERIOD | Journal Import Error | Accounting period is not open for the specified ledger | Open the period via GL Period Statuses before import |
| AP_INVALID_SUPPLIER | Invoice Import Error | Supplier name or site does not match supplier master | Verify supplier is active and site is correct |

[src1, src3]

### Failure Points in Production

- **FBDI upload succeeds but ESS job fails silently**: The erpintegrations POST returns 200 for the file upload, but the subsequent ESS job may fail due to data validation errors. The only way to see errors is to poll the job status and download the error report. Fix: `Always poll GET /erpintegrations/{RequestId} and download the output file for error details`. [src4]
- **Journal import rejects entire batch for one bad line**: GL journal import validates all lines in a batch — one invalid account segment rejects every line in that batch. Fix: `Pre-validate account combinations via REST GET /accountCombinations before importing, and split into smaller batches`. [src4]
- **OAuth token expires mid-batch**: A long-running FBDI import may span beyond the 3600s token lifetime. The import itself continues (server-side), but your polling calls fail with 401. Fix: `Re-authenticate before each poll request; never cache tokens beyond 3500s`. [src3]
- **Content-Type header mismatch**: Oracle REST API requires `application/vnd.oracle.adf.resourceitem+json` for single-record POST and `application/vnd.oracle.adf.resourcecollection+json` for batch operations. Using plain `application/json` may work for GET but fails for POST/PATCH. Fix: `Always use the oracle.adf Content-Type headers`. [src2]
- **Intercompany import with mismatched business units**: FBDI intercompany import requires both the sending and receiving business units to have intercompany enabled and balanced accounts configured. Mismatches produce generic "validation error" messages. Fix: `Verify intercompany setup for both BUs via GL configuration before importing`. [src5]
- **Concurrent ESS jobs of same type**: Submitting a second Journal Import while one is running causes the second to queue indefinitely or fail. Fix: `Serialize ESS job submissions per type; poll previous job completion before submitting next`. [src4]

## Anti-Patterns

### Wrong: Creating GL journals one-at-a-time via REST for bulk feeds

```python
# BAD — creates N API calls for N journals, hits throttling quickly
for journal in journals:  # 10,000 journals
    requests.post(f"{base}/journalBatches", json=journal, headers=headers)
```

### Correct: Use FBDI for bulk journal import

```python
# GOOD — single file upload + single ESS job for any volume
import csv, base64, zipfile, io

# 1. Write all journals to GlInterface CSV
buf = io.StringIO()
writer = csv.writer(buf)
writer.writerow(["STATUS","LEDGER_NAME","ACCOUNTING_DATE",...])
for j in journals:
    writer.writerow(["NEW", j["ledger"], j["date"], ...])

# 2. ZIP and base64-encode
zip_buf = io.BytesIO()
with zipfile.ZipFile(zip_buf, 'w') as zf:
    zf.writestr("GlInterface.csv", buf.getvalue())
encoded = base64.b64encode(zip_buf.getvalue()).decode()

# 3. Upload via erpintegrations
requests.post(f"{base}/erpintegrations", json={
    "OperationName": "importBulkData",
    "DocumentContent": encoded,
    "ContentType": "zip",
    "FileName": "GlInterface.zip",
    "DocumentAccount": "fin$/journal$/import$"
}, headers=headers)
```

### Wrong: Ignoring Content-Type headers

```bash
# BAD — using generic Content-Type for Oracle REST POST
curl -X POST .../invoices \
  -H "Content-Type: application/json" \
  -d '{"InvoiceNumber": "INV-001"}'
```

### Correct: Use Oracle ADF Content-Type

```bash
# GOOD — Oracle requires ADF-specific Content-Type for write operations
curl -X POST .../invoices \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" \
  -d '{"InvoiceNumber": "INV-001"}'
```

### Wrong: Assuming REST API covers all Financials operations

```python
# BAD — trying to create intercompany transactions via REST
requests.post(f"{base}/intercompanyTransactions", json=ic_data, headers=headers)
# Returns 404 — this endpoint does not exist
```

### Correct: Use FBDI for modules without REST write support

```python
# GOOD — use FBDI template for intercompany
# Prepare fin/intercompany/import CSV → ZIP → upload via erpintegrations
requests.post(f"{base}/erpintegrations", json={
    "OperationName": "importBulkData",
    "DocumentContent": encoded_zip,
    "ContentType": "zip",
    "FileName": "IntercompanyImport.zip",
    "DocumentAccount": "fin$/intercompany$/import$"
}, headers=headers)
```

## Common Pitfalls

- **Assuming published rate limits exist**: Unlike Salesforce, Oracle does not publish fixed API quotas. Developers build without throttle handling, then get 429s in production under load. Fix: `Implement exponential backoff with Retry-After header from day one`. [src3]
- **Using Basic Auth in production**: Basic Auth works in testing but breaks when org-wide MFA enforcement is enabled. Fix: `Always use OAuth 2.0 Client Credentials for production integrations`. [src3]
- **Not pre-validating FBDI data**: FBDI imports fail at the ESS job level with cryptic error reports when data doesn't match reference data (chart of accounts, supplier master, etc.). Fix: `Pre-validate reference data via REST GET queries before preparing FBDI files`. [src4]
- **Hardcoding the 3600s token lifetime**: IDCS administrators can change token expiry settings. Fix: `Read the expires_in field from the token response and refresh proactively at 90% of lifetime`. [src3]
- **Mixing FBDI date formats with REST date formats**: FBDI uses YYYY/MM/DD while REST uses YYYY-MM-DD. Fix: `Use format-specific date serialization per API surface; never reuse the same date formatting function for both`. [src1]
- **Not downloading ESS job error reports**: When an FBDI import fails, developers see "FAILED" status but don't download the error output file, missing the actual validation errors. Fix: `Always GET the job result file via /erpintegrations/{RequestId} with OperationName=downloadESSJobExecutionDetails`. [src4]

## Diagnostic Commands

```bash
# Test OAuth authentication
curl -s -X POST \
  "https://{idcs}.identity.oraclecloud.com/oauth2/v1/token" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all" \
  | python -m json.tool

# List available ledgers (verifies API connectivity + GL access)
curl -s -X GET \
  "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/ledgersLov?onlyData=true" \
  -H "Authorization: Bearer {token}" \
  | python -m json.tool

# Check ESS job status (after FBDI import)
curl -s -X GET \
  "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations/{RequestId}" \
  -H "Authorization: Bearer {token}" \
  | python -m json.tool

# Verify AP invoice exists
curl -s -X GET \
  "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices?q=InvoiceNumber={invoice_num}" \
  -H "Authorization: Bearer {token}" \
  | python -m json.tool

# List enabled Business Events (for event-driven integrations)
curl -s -X GET \
  "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpBusinessEvents?onlyData=true" \
  -H "Authorization: Bearer {token}" \
  | python -m json.tool

# Describe invoices resource (field metadata)
curl -s -X GET \
  "https://{host}.fa.{dc}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices/describe" \
  -H "Authorization: Bearer {token}" \
  | python -m json.tool
```

## Version History & Compatibility

| Release | Release Date | Status | Key Changes | Migration Notes |
|---|---|---|---|---|
| 26A | 2026-01 | Current | Payables Interface Invoices import action; AR transaction completion via REST | Evaluate new submitImportInvoices action for AP migration |
| 25D | 2025-10 | Supported | New Cash Pool endpoints; enhanced Expense Policies | No breaking changes from 25C |
| 25C | 2025-07 | Supported | Receivables Credit Memos CRUD; Collections Strategies | New resource: receivablesCreditMemos |
| 25B | 2025-04 | Supported | Enhanced ledgerBalances query filters | No breaking changes |
| 25A | 2025-01 | Supported | Payables Interface Invoices resource; expanded FBDI templates | New resource: payablesInterfaceInvoices |
| 24D | 2024-10 | Supported | ERP Business Events enhancements | Evaluate event-driven patterns |
| 24C | 2024-07 | Supported | Baseline for current API documentation | Minimum recommended version |

[src1, src2]

### Deprecation Policy

Oracle Fusion Cloud follows a quarterly release cadence (A/B/C/D per year). REST API resource version 11.13.18.05 has been stable for multiple years — Oracle adds new endpoints and actions without changing the version number. Oracle has not publicly deprecated any REST API endpoints, but SOAP services are considered legacy and not recommended for new development. Oracle provides a minimum 12-month notice before any breaking change via the What's New documentation. [src1]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Real-time AP invoice creation, <500 per batch | Bulk journal import (>100 journals) | FBDI via erpintegrations endpoint |
| Querying GL balances, AR aging, AP payment status | Creating intercompany transactions | FBDI template fin/intercompany/import |
| Managing suppliers, customers, bank accounts | Fixed Assets mass additions | FBDI FA Mass Additions template |
| Event-driven outbound notifications | Bulk data extraction (>10K records) | BI Publisher scheduled reports |
| AR receipt application and cash posting | Subledger Accounting journal creation | Create Accounting ESS job via erpintegrations |
| Expense report submission and approval | Data migration (>100K records) | FBDI with specialized migration templates |

## Important Caveats

- Oracle does not publish fixed API rate limits — fair-use throttling thresholds vary by pod, tenant size, and time of day. What works in testing may hit 429s in production during month-end close.
- The REST API resource version (11.13.18.05) does not change with quarterly releases, but new endpoints and actions are added silently. Always check the latest release documentation for your target release.
- FBDI is the only supported path for several critical Financials operations (journal import, intercompany, FA mass additions, subledger accounting). Agents recommending REST-only integration patterns for these modules will produce incorrect advice.
- Oracle test/sandbox instances may have different configurations, fewer open periods, and missing reference data compared to production — always validate your integration against a representative test environment.
- ESS jobs are serialized per job type — submitting multiple Journal Import jobs concurrently causes queueing, not parallelism. Design batch strategies around serial ESS execution.
- The Content-Type header requirements (`application/vnd.oracle.adf.resourceitem+json` for single records, `application/vnd.oracle.adf.resourcecollection+json` for collections) are non-negotiable — using standard `application/json` causes silent failures on write operations.
- API endpoint availability depends on which Oracle Cloud modules are licensed and opted in — not all endpoints listed in the documentation may be available in every tenant.

## Related Units
<!-- Generated from related_kos frontmatter -->

- No related units currently published.