Skip to content
Learni
View all tutorials
Oracle Cloud

How to Integrate Oracle ERP Cloud via REST APIs in 2026

18 minEXPERT
TypeScriptOracle ERP CloudREST APIsOAuth 2.0Intégration ERP
Lire en français

Introduction

Oracle ERP Cloud, also known as Fusion Cloud ERP, is the leading ERP suite for enterprises handling complex financial, HR, and supply chain workflows. In 2026, its REST APIs (version 11.13.18.05+) enable native integrations without heavy middleware, perfect for microservices or custom automations. Why is this essential? 80% of modern ERP deployments require APIs to sync with CRM tools like Salesforce or BI platforms. This expert tutorial guides you step by step: from OAuth 2.0 authentication to handling massive volumes with pagination and idempotency. By the end, you'll deploy production-ready Node.js scripts to read/write invoices, account balances, and more. Time savings: 50% on manual integrations. Get ready to scale your cloud ERP operations.

Prerequisites

  • Oracle ERP Cloud account with Financial Application Administrator role and OAuth Client configured.
  • Node.js 20+ and npm installed.
  • Environment variables: ERP_HOST, CLIENT_ID, CLIENT_SECRET, USERNAME, PASSWORD (obtained via Oracle Identity Cloud Service).
  • Tool like Postman for testing (optional).
  • Advanced knowledge of TypeScript, async/await, and HTTP status codes.

Initialize the Node.js Project

setup.sh
#!/bin/bash
npm init -y
npm install axios dotenv typescript ts-node @types/node
npm install -D @types/axios

mkdir src
echo '{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}' > tsconfig.json

cat > .env << EOF
ERP_HOST=https://your-erp-instance.oraclecloud.com
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
USERNAME=your_username
PASSWORD=your_password
EOF

cat > src/index.ts << 'EOF'
console.log('Projet prêt pour Oracle ERP Cloud');
EOF

chmod +x setup.sh

This Bash script sets up a Node.js project with TypeScript, installs axios for HTTP calls and dotenv for secrets. It creates a strict tsconfig.json and a .env template. Run ./setup.sh then source .env to load the vars. Pitfall: Check Oracle permissions upfront to avoid 403 Forbidden errors from the start.

Understanding OAuth 2.0 Authentication

Oracle ERP Cloud uses OAuth 2.0 Resource Owner Password Credentials (ROPC) for server-side scripts, or Client Credentials for services. Analogy: like a company magnetic badge, the JWT token (valid for 3600s) carries scopes like urn:opc:idm:__mysc__ + https://your-erp/fscmRestApi. Refresh it via refresh_token to avoid downtime. Configure your OAuth Client in Setup & Maintenance > Manage OAuth Clients.

Obtain and Use the OAuth Token

src/auth.ts
import axios from 'axios';
import * as dotenv from 'dotenv';
dotenv.config();

const ERP_HOST = process.env.ERP_HOST!;
const CLIENT_ID = process.env.CLIENT_ID!;
const CLIENT_SECRET = process.env.CLIENT_SECRET!;
const USERNAME = process.env.USERNAME!;
const PASSWORD = process.env.PASSWORD!;

async function getToken(): Promise<string> {
  const tokenUrl = `${ERP_HOST}/ic/api/integration/v1/token`;
  const response = await axios.post(tokenUrl, new URLSearchParams({
    grant_type: 'password',
    username: USERNAME,
    password: PASSWORD,
    scope: `${CLIENT_ID}/your-erp-instance/*`
  }), {
    auth: { username: CLIENT_ID, password: CLIENT_SECRET },
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
  });
  return response.data.access_token;
}

(async () => {
  try {
    const token = await getToken();
    console.log('Token obtenu:', token.substring(0, 20) + '...');
  } catch (error) {
    console.error('Erreur auth:', error.response?.data || error.message);
  }
})();

This script fetches a bearer token via the ROPC flow, essential for all API calls. Use axios for robustness. Pitfall: Malformed scope causes 401; test in Postman first. Tokens expire quickly: implement Redis caching in production.

List Invoices Using Finder

src/listInvoices.ts
import axios from 'axios';
import * as dotenv from 'dotenv';
dotenv.config();

const ERP_HOST = process.env.ERP_HOST!;

async function getToken(): Promise<string> {
  // Copied from auth.ts
  const tokenUrl = `${ERP_HOST}/ic/api/integration/v1/token`;
  const response = await axios.post(tokenUrl, new URLSearchParams({
    grant_type: 'password',
    username: process.env.USERNAME!,
    password: process.env.PASSWORD!,
    scope: `${process.env.CLIENT_ID!}/your-erp-instance/*`
  }), {
    auth: { username: process.env.CLIENT_ID!, password: process.env.CLIENT_SECRET! },
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
  });
  return response.data.access_token;
}

async function listInvoices(token: string, limit: number = 25) {
  const url = `${ERP_HOST}/fscmRestApi/resources/11.13.18.05/invoices?q=InvoiceStatusCD=AVAILABLE`;
  const response = await axios.get(url, {
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
      'REST-Framework-Version': '4'
    },
    params: { limit, orderBy: 'InvoiceId:desc', finder: 'FindPayablesInvoices' }
  });
  console.log('Factures:', response.data);
  return response.data;
}

(async () => {
  const token = await getToken();
  await listInvoices(token);
})();

GET call with q param to filter (AVAILABLE status) and finder for complex queries. Limit prevents overload. Pitfall: Without 'REST-Framework-Version', responses are empty. Use fields=InvoiceId,InvoiceAmount to optimize bandwidth.

Handling Creation and Updates

POST to create: JSON payload valid against ERP schema (use /descriptors). PATCH for partial updates (idempotent). Analogy: like upsert in a DB, check existence via GET UUID first. Required headers: If-Match:* for concurrency.

Create a New Invoice

src/createInvoice.ts
import axios from 'axios';
import * as dotenv from 'dotenv';
dotenv.config();

// Functions getToken and listInvoices can be copied/imported

const ERP_HOST = process.env.ERP_HOST!;

async function getToken(): Promise<string> {
  // Same impl as before
  const tokenUrl = `${ERP_HOST}/ic/api/integration/v1/token`;
  // ... (identical code to auth.ts)
  return 'token-placeholder'; // Replace with full code
}

async function createInvoice(token: string) {
  const url = `${ERP_HOST}/fscmRestApi/resources/11.13.18.05/invoices`;
  const payload = {
    InvoiceAmount: 1500.00,
    InvoiceDate: '2026-01-15',
    InvoiceNum: 'INV-2026-001',
    SupplierId: 300000001, // UUID of an existing supplier
    InvoiceStatusCD: 'AVAILABLE',
    PayGroupName: 'DEFAULT'
  };
  const response = await axios.post(url, payload, {
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/vnd.oracle.adf.resourceitem+json',
      'REST-Framework-Version': '4',
      'If-Match': '*'
    }
  });
  console.log('Facture créée:', response.data);
  return response.data.InvoiceId;
}

(async () => {
  const token = await getToken();
  await createInvoice(token);
})();

Minimal but valid payload; SupplierId must exist (query first). ADF Content-Type for nesting. Pitfall: Amounts in base currency, or auto-conversion fails. Return InvoiceId for chaining.

Update and Paginate

src/updateAndPaginate.ts
import axios from 'axios';
import * as dotenv from 'dotenv';
dotenv.config();

const ERP_HOST = process.env.ERP_HOST!;

// getToken as before

async function updateInvoice(token: string, invoiceId: string) {
  const url = `${ERP_HOST}/fscmRestApi/resources/11.13.18.05/invoices/${invoiceId}`;
  const response = await axios.get(url, {
    headers: { Authorization: `Bearer ${token}`, 'REST-Framework-Version': '4' }
  });
  const etag = response.headers['etag'];

  await axios.patch(url, { InvoiceAmount: 2000.00 }, {
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/vnd.oracle.adf.resourceitem+json',
      'REST-Framework-Version': '4',
      'If-Match': etag
    }
  });
  console.log('Facture mise à jour');
}

async function paginateInvoices(token: string, offset: number = 0, limit: number = 25) {
  let allInvoices: any[] = [];
  let hasMore = true;
  while (hasMore) {
    const url = `${ERP_HOST}/fscmRestApi/resources/11.13.18.05/invoices?limit=${limit}&offset=${offset}`;
    const res = await axios.get(url, { headers: { Authorization: `Bearer ${token}`, 'REST-Framework-Version': '4' } });
    allInvoices.push(...res.data.items);
    hasMore = res.data.hasMore;
    offset += limit;
  }
  console.log(`Total factures: ${allInvoices.length}`);
  return allInvoices;
}

(async () => {
  const token = await getToken();
  await paginateInvoices(token);
  // await updateInvoice(token, '300000123456789');
})();

PATCH uses ETag for optimistic locking (anti-race conditions). Pagination loops over offset/limit/hasMore, critical for >10k records. Pitfall: Missing ETag = 412 Precondition Failed; always GET first.

Global Error Handling and Retries

src/errorHandler.ts
import axios, { AxiosError } from 'axios';
import * as dotenv from 'dotenv';
dotenv.config();

class ErpClient {
  private token: string;
  private host: string;

  constructor() {
    this.host = process.env.ERP_HOST!;
  }

  private async getToken(): Promise<void> {
    // getToken implementation
    this.token = 'token';
  }

  async request(method: string, endpoint: string, data?: any, retries: number = 3): Promise<any> {
    await this.getToken();
    for (let i = 0; i < retries; i++) {
      try {
        const response = await axios({
          method,
          url: `${this.host}${endpoint}`,
          data,
          headers: {
            Authorization: `Bearer ${this.token}`,
            'Content-Type': 'application/vnd.oracle.adf.resourceitem+json',
            'REST-Framework-Version': '4',
            'If-Match': '*'
          }
        });
        return response.data;
      } catch (error) {
        const err = error as AxiosError;
        if (err.response?.status === 401) {
          await this.getToken(); // Retry token
          continue;
        }
        if (err.response?.status >= 500 && i < retries - 1) {
          await new Promise(r => setTimeout(r, 1000 * (i + 1))); // Exponential backoff
          continue;
        }
        throw new Error(`ERP Error ${err.response?.status}: ${err.response?.data?.title || err.message}`);
      }
    }
  }

  async getInvoices() {
    return this.request('GET', '/fscmRestApi/resources/11.13.18.05/invoices');
  }
}

const client = new ErpClient();
(async () => {
  try {
    console.log(await client.getInvoices());
  } catch (error) {
    console.error(error);
  }
})();

Class wrapper with exponential retry, auto token refresh, and typed errors. Handles 429 RateLimit, 5xx server errors. Pitfall: Without backoff, risk IP ban; log OData errors for debugging (title/detail).

Best Practices

  • Cache tokens with Redis (TTL 3500s) and proactive refresh.
  • Validate payloads against /descriptors endpoint for schemas.
  • Use advanced q params (e.g., q=InvoiceDate>='2026-01-01') and expand=lines for nested data.
  • Implement idempotency via unique InvoiceNum.
  • Monitor with Oracle Logging Analytics; rate limit at 1000/min.

Common Errors to Avoid

  • 401/403: Incomplete OAuth scope or missing role (add FSM_APPLICATION_ADMIN).
  • 400 Bad Request: Payload missing required fields (use /childDescriptors).
  • Infinite pagination: Forget hasMore=false after last page.
  • ETag mismatch: Always refresh ETag before PATCH in loops.

Next Steps

Explore Oracle Integration Cloud (OIC) for low-code, Visual Builder for custom UIs, or Redwood UX extensions. Check the official REST APIs docs. Level up with our Learni Group training courses on Oracle Cloud certifications.

How to Integrate Oracle ERP Cloud REST APIs in 2026 | Learni