frappe-impl-integrations

Name: frappe-impl-integrations
Author: Impertio-Studio

151stars49forks

How to install frappe-impl-integrations?

impertio-studio/frappe_claude_skill_package/frappe-impl-integrations

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-impl-integrations

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Frappe Integrations
2
3	Step-by-step workflows for OAuth, Webhooks, Payment Gateways, Data Import/Export, and external API calls.
4
5	Version: v14/v15/v16
6
7	---
8
9	## Decision Tree: Which Integration Pattern?
10
11	```
12	WHAT ARE YOU INTEGRATING?
13	│
14	├─► External service needs to call YOUR Frappe site?
15	│ ├─► On document events → Webhook (push to external)
16	│ ├─► External sends data to you → Whitelisted API endpoint
17	│ └─► External needs user auth → OAuth 2.0 Provider
18	│
19	├─► YOUR Frappe site calls an external service?
20	│ ├─► Needs user-level OAuth consent → Connected App
21	│ ├─► Server-to-server with API key → make_request / requests
22	│ └─► Recurring sync → Scheduler + API calls
23	│
24	├─► Bulk data in/out?
25	│ ├─► Import CSV/XLSX → Data Import DocType
26	│ ├─► Export data → Report Builder / export-csv / API
27	│ └─► Programmatic bulk → frappe.get_doc().insert()
28	│
29	├─► Payment processing?
30	│ └─► Payment Request + Payment Gateway controller
31	│
32	└─► Real-time vs batch?
33	├─► Real-time → Webhook or API endpoint
34	├─► Near real-time → frappe.enqueue() after event
35	└─► Batch → Scheduler task (hourly/daily)
36	```
37
38	---
39
40	## Workflow 1: OAuth 2.0: Frappe as Provider
41
42	Use when external applications need "Sign in with Frappe" or API access on behalf of users.
43
44	### Step 1: Configure OAuth Provider Settings
45
46	Navigate to Setup > Integrations > OAuth Provider Settings:
47	- Force: ALWAYS asks user for confirmation
48	- Auto: Asks only if no active token exists
49
50	### Step 2: Create OAuth Client
51
52	Navigate to Setup > Integrations > OAuth Client:
53
54	\| Field \| Value \|
55	\|-------\|-------\|
56	\| App Name \| External app identifier \|
57	\| Scopes \| Space-separated (e.g., `openid all`) \|
58	\| Redirect URIs \| Space-separated callback URLs \|
59	\| Default Redirect URI \| Primary callback URL \|
60	\| Grant Type \| `Authorization Code` (RECOMMENDED) or `Implicit` \|
61	\| Response Type \| `Code` (for Auth Code) or `Token` (for Implicit) \|
62	\| Skip Authorization \| Check for trusted first-party apps only \|
63
64	### Step 3: Use the Generated Endpoints
65
66	\| Endpoint \| URL \|
67	\|----------\|-----\|
68	\| Authorize \| `/api/method/frappe.integrations.oauth2.authorize` \|
69	\| Token \| `/api/method/frappe.integrations.oauth2.get_token` \|
70	\| Profile \| `/api/method/frappe.integrations.oauth2.openid_profile` \|
71
72	### Step 4: Configure External App
73
74	```ini
75	# Example: Grafana generic_oauth config
76	client_id = <generated_client_id>
77	client_secret = <generated_client_secret>
78	auth_url = https://your-frappe.com/api/method/frappe.integrations.oauth2.authorize
79	token_url = https://your-frappe.com/api/method/frappe.integrations.oauth2.get_token
80	api_url = https://your-frappe.com/api/method/frappe.integrations.oauth2.openid_profile
81	scopes = openid all
82	```
83
84	### Critical Rules
85
86	- NEVER use `Implicit` grant type for server-side apps — use `Authorization Code`
87	- ALWAYS use HTTPS in production for all OAuth endpoints
88	- NEVER expose `client_secret` in client-side JavaScript
89
90	---
91
92	## Workflow 2: Connected App: Frappe as OAuth Consumer
93
94	Use when your Frappe instance needs to access external services (Google, Microsoft, etc.) on behalf of users.
95
96	### Step 1: Create Connected App DocType
97
98	\| Field \| Purpose \|
99	\|-------\|---------\|
100	\| Name \| Identifier for the connection \|
101	\| OpenID Configuration URL \| Auto-fetches endpoints (e.g., `/.well-known/openid-configuration`) \|
102	\| Authorization URI \| Consent screen URL (auto-filled from OpenID) \|
103	\| Token URI \| Token exchange URL (auto-filled from OpenID) \|
104	\| Redirect URI \| Auto-generated — copy this to external provider \|
105	\| Client ID \| From external provider \|
106	\| Client Secret \| From external provider \|
107	\| Scopes \| Permissions needed (e.g., `https://mail.google.com/`) \|
108
109	### Step 2: Register Redirect URI with Provider
110
111	Copy the auto-generated Redirect URI and register it in the external provider's OAuth console.
112
113	### Step 3: Add Extra Parameters (if needed)
114
115	```
116	access_type=offline # Google: enables refresh tokens
117	prompt=consent # Google: forces re-consent for refresh token
118	```
119
120	### Step 4: Use in Code
121
122	```python
123	import frappe
124
125	connected_app = frappe.get_doc("Connected App", "My Google App")
126	# Initiates OAuth flow — user clicks "Connect to..." button
127	# After co

People who liked this also viewed

6 picks

Type

frappe-impl-integrations

151stars49forks

View on GitHub

How to install frappe-impl-integrations?

impertio-studio/frappe_claude_skill_package/frappe-impl-integrations

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-impl-integrations

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Frappe Integrations
2
3	Step-by-step workflows for OAuth, Webhooks, Payment Gateways, Data Import/Export, and external API calls.
4
5	Version: v14/v15/v16
6
7	---
8
9	## Decision Tree: Which Integration Pattern?
10
11	```
12	WHAT ARE YOU INTEGRATING?
13	│
14	├─► External service needs to call YOUR Frappe site?
15	│ ├─► On document events → Webhook (push to external)
16	│ ├─► External sends data to you → Whitelisted API endpoint
17	│ └─► External needs user auth → OAuth 2.0 Provider
18	│
19	├─► YOUR Frappe site calls an external service?
20	│ ├─► Needs user-level OAuth consent → Connected App
21	│ ├─► Server-to-server with API key → make_request / requests
22	│ └─► Recurring sync → Scheduler + API calls
23	│
24	├─► Bulk data in/out?
25	│ ├─► Import CSV/XLSX → Data Import DocType
26	│ ├─► Export data → Report Builder / export-csv / API
27	│ └─► Programmatic bulk → frappe.get_doc().insert()
28	│
29	├─► Payment processing?
30	│ └─► Payment Request + Payment Gateway controller
31	│
32	└─► Real-time vs batch?
33	├─► Real-time → Webhook or API endpoint
34	├─► Near real-time → frappe.enqueue() after event
35	└─► Batch → Scheduler task (hourly/daily)
36	```
37
38	---
39
40	## Workflow 1: OAuth 2.0: Frappe as Provider
41
42	Use when external applications need "Sign in with Frappe" or API access on behalf of users.
43
44	### Step 1: Configure OAuth Provider Settings
45
46	Navigate to Setup > Integrations > OAuth Provider Settings:
47	- Force: ALWAYS asks user for confirmation
48	- Auto: Asks only if no active token exists
49
50	### Step 2: Create OAuth Client
51
52	Navigate to Setup > Integrations > OAuth Client:
53
54	\| Field \| Value \|
55	\|-------\|-------\|
56	\| App Name \| External app identifier \|
57	\| Scopes \| Space-separated (e.g., `openid all`) \|
58	\| Redirect URIs \| Space-separated callback URLs \|
59	\| Default Redirect URI \| Primary callback URL \|
60	\| Grant Type \| `Authorization Code` (RECOMMENDED) or `Implicit` \|
61	\| Response Type \| `Code` (for Auth Code) or `Token` (for Implicit) \|
62	\| Skip Authorization \| Check for trusted first-party apps only \|
63
64	### Step 3: Use the Generated Endpoints
65
66	\| Endpoint \| URL \|
67	\|----------\|-----\|
68	\| Authorize \| `/api/method/frappe.integrations.oauth2.authorize` \|
69	\| Token \| `/api/method/frappe.integrations.oauth2.get_token` \|
70	\| Profile \| `/api/method/frappe.integrations.oauth2.openid_profile` \|
71
72	### Step 4: Configure External App
73
74	```ini
75	# Example: Grafana generic_oauth config
76	client_id = <generated_client_id>
77	client_secret = <generated_client_secret>
78	auth_url = https://your-frappe.com/api/method/frappe.integrations.oauth2.authorize
79	token_url = https://your-frappe.com/api/method/frappe.integrations.oauth2.get_token
80	api_url = https://your-frappe.com/api/method/frappe.integrations.oauth2.openid_profile
81	scopes = openid all
82	```
83
84	### Critical Rules
85
86	- NEVER use `Implicit` grant type for server-side apps — use `Authorization Code`
87	- ALWAYS use HTTPS in production for all OAuth endpoints
88	- NEVER expose `client_secret` in client-side JavaScript
89
90	---
91
92	## Workflow 2: Connected App: Frappe as OAuth Consumer
93
94	Use when your Frappe instance needs to access external services (Google, Microsoft, etc.) on behalf of users.
95
96	### Step 1: Create Connected App DocType
97
98	\| Field \| Purpose \|
99	\|-------\|---------\|
100	\| Name \| Identifier for the connection \|
101	\| OpenID Configuration URL \| Auto-fetches endpoints (e.g., `/.well-known/openid-configuration`) \|
102	\| Authorization URI \| Consent screen URL (auto-filled from OpenID) \|
103	\| Token URI \| Token exchange URL (auto-filled from OpenID) \|
104	\| Redirect URI \| Auto-generated — copy this to external provider \|
105	\| Client ID \| From external provider \|
106	\| Client Secret \| From external provider \|
107	\| Scopes \| Permissions needed (e.g., `https://mail.google.com/`) \|
108
109	### Step 2: Register Redirect URI with Provider
110
111	Copy the auto-generated Redirect URI and register it in the external provider's OAuth console.
112
113	### Step 3: Add Extra Parameters (if needed)
114
115	```
116	access_type=offline # Google: enables refresh tokens
117	prompt=consent # Google: forces re-consent for refresh token
118	```
119
120	### Step 4: Use in Code
121
122	```python
123	import frappe
124
125	connected_app = frappe.get_doc("Connected App", "My Google App")
126	# Initiates OAuth flow — user clicks "Connect to..." button
127	# After co

People who liked this also viewed

6 picks

Type