/frappe-impl-integrations

name: frappe-impl-integrations
description: >
  Use when implementing OAuth providers, Connected Apps, Webhooks, Payment Gateways, or Data Import/Export in Frappe.
  Prevents authentication failures from wrong OAuth flow, missed webhook deliveries, and data corruption during bulk imports.
  Covers OAuth2 provider/client, Connected App DocType, Webhook DocType, Payment Gateway integration, Data Import, Data Export, frappe.integrations module.
  Keywords: OAuth, Connected App, Webhook, Payment Gateway, Data Import, Data Export, integration, API key, OAuth2, webhook trigger, connect to external service, OAuth setup, webhook configuration, import data, export data..
license: MIT
compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
metadata:
  author: OpenAEC-Foundation
  version: "2.0"

Frappe Integrations

Step-by-step workflows for OAuth, Webhooks, Payment Gateways, Data Import/Export, and external API calls.

**Version**: v14/v15/v16

---

Decision Tree: Which Integration Pattern?

WHAT ARE YOU INTEGRATING?
│
├─► External service needs to call YOUR Frappe site?
│   ├─► On document events → Webhook (push to external)
│   ├─► External sends data to you → Whitelisted API endpoint
│   └─► External needs user auth → OAuth 2.0 Provider
│
├─► YOUR Frappe site calls an external service?
│   ├─► Needs user-level OAuth consent → Connected App
│   ├─► Server-to-server with API key → make_request / requests
│   └─► Recurring sync → Scheduler + API calls
│
├─► Bulk data in/out?
│   ├─► Import CSV/XLSX → Data Import DocType
│   ├─► Export data → Report Builder / export-csv / API
│   └─► Programmatic bulk → frappe.get_doc().insert()
│
├─► Payment processing?
│   └─► Payment Request + Payment Gateway controller
│
└─► Real-time vs batch?
    ├─► Real-time → Webhook or API endpoint
    ├─► Near real-time → frappe.enqueue() after event
    └─► Batch → Scheduler task (hourly/daily)

---

Workflow 1: OAuth 2.0: Frappe as Provider

Use when external applications need "Sign in with Frappe" or API access on behalf of users.

Step 1: Configure OAuth Provider Settings

Navigate to **Setup > Integrations > OAuth Provider Settings**:

• **Force**: ALWAYS asks user for confirmation
• **Auto**: Asks only if no active token exists

Step 2: Create OAuth Client

Navigate to **Setup > Integrations > OAuth Client**:

| Field | Value | |-------|-------| | App Name | External app identifier | | Scopes | Space-separated (e.g., `openid all`) | | Redirect URIs | Space-separated callback URLs | | Default Redirect URI | Primary callback URL | | Grant Type | `Authorization Code` (RECOMMENDED) or `Implicit` | | Response Type | `Code` (for Auth Code) or `Token` (for Implicit) | | Skip Authorization | Check for trusted first-party apps only |

Step 3: Use the Generated Endpoints

| Endpoint | URL | |----------|-----| | Authorize | `/api/method/frappe.integrations.oauth2.authorize` | | Token | `/api/method/frappe.integrations.oauth2.get_token` | | Profile | `/api/method/frappe.integrations.oauth2.openid_profile` |

Step 4: Configure External App

# Example: Grafana generic_oauth config
client_id = <generated_client_id>
client_secret = <generated_client_secret>
auth_url = https://your-frappe.com/api/method/frappe.integrations.oauth2.authorize
token_url = https://your-frappe.com/api/method/frappe.integrations.oauth2.get_token
api_url = https://your-frappe.com/api/method/frappe.integrations.oauth2.openid_profile
scopes = openid all

Critical Rules

• **NEVER** use `Implicit` grant type for server-side apps — use `Authorization Code`
• **ALWAYS** use HTTPS in production for all OAuth endpoints
• **NEVER** expose `client_secret` in client-side JavaScript

---

Workflow 2: Connected App: Frappe as OAuth Consumer

Use when your Frappe instance needs to access external services (Google, Microsoft, etc.) on behalf of users.

Step 1: Create Connected App DocType

| Field | Purpose | |-------|---------| | Name | Identifier for the connection | | OpenID Configuration URL | Auto-fetches endpoints (e.g., `/.well-known/openid-configuration`) | | Authorization URI | Consent screen URL (auto-filled from OpenID) | | Token URI | Token exchange URL (auto-filled from OpenID) | | Redirect URI | Auto-generated — copy this to external provider | | Client ID | From external provider | | Client Secret | From external provider | | Scopes | Permissions needed (e.g., `https://mail.google.com/`) |

Step 2: Register Redirect URI with Provider

Copy the auto-generated Redirect URI and register it in the external provider's OAuth console.

Step 3: Add Extra Parameters (if needed)

access_type=offline    # Google: enables refresh tokens
prompt=consent         # Google: forces re-consent for refresh token

Step 4: Use in Code

import frappe

connected_app = frappe.get_doc("Connected App", "My Google App")
# Initiates OAuth flow — user clicks "Connect to..." button
# After consent, tokens are stored automatically

# Making authenticated calls:
session = connected_app.get_oauth2_session()
response = session.get("https://www.googleapis.com/gmail/v1/users/me/messages")

Critical Rules

• **ALWAYS** add `access_type=offline` for Google APIs to get refresh tokens
• **NEVER** store tokens manually — Connected App manages token lifecycle
• **ALWAYS** handle `TokenExpiredError` — call `session.refresh_token()` or reconnect

---

Workflow 3: Webhooks: Push Notifications to External Services

Step 1: Create Webhook DocType

Navigate to **Integrations > Webhook**:

| Field | Value | |-------|-------| | DocType | Target document type | | Doc Event | `on_update`, `after_insert`, `on_submit`, `on_cancel`, `on_trash` | | Request URL | External endpoint | | Request Method | POST (default) | | Conditions | Optional Jinja filter (e.g., `doc.status == "Approved"`) | | Enabled | Check to activate |

Step 2: Configure Headers

Add custom headers for authenti