Smithery is now a part of Arcade.dev! Read more in our announcement here
Generate code to integrate Frappe with external REST APIs. Use when connecting to third-party services, payment gateways, or external data sources.
Generate robust API client code for integrating Frappe with external REST APIs, handling authentication, error recovery, and data transformation.
These Frappe conventions apply to everything this skill generates, and override any conflicting example below.
bench (never ./env/bin/bench or a full path). Always pass --site <site> explicitly — never run a bare bench migrate / bench run-tests. Run bench start in the background and only if it isn't already running. Don't run discovery commands (which bench, bench --version).apps/<app>/<app>/<module>/doctype/<name>/<name>.json — the app name appears twice (directory + Python package) — with an empty __init__.py alongside. Never mkdir the folder; write the JSON and run bench --site <site> migrate to create the structure. Don't add creation, modified, owner, modified_by, or docstatus as fields — Frappe manages them.frappe.qb.get_query() over raw frappe.db.sql(). Use frappe.db.get_all() for server logic (ignores permissions) and frappe.db.get_list() for user-facing APIs (enforces them). Never use frappe.db.set_value() on a field with validation or lifecycle logic — load the doc and doc.save() so controller hooks run. Batch-fetch related records; never query inside a loop (N+1).frappe.db.commit() in controllers, request handlers, background jobs, or patches — Frappe auto-commits on success and rolls back on uncaught errors. Flush manually only to make a write visible to a subsequent frappe.enqueue() (or pass enqueue_after_commit=True).@frappe.whitelist() parameter so Frappe validates and casts it, and pass methods=[...] to pin the HTTP verb.Claude should invoke this skill when:
REST API Client Template:
import requests
import frappe
from frappe import _
class ExternalAPIClient:
def __init__(self):
self.base_url = frappe.conf.get('external_api_url')
self.api_key = frappe.conf.get('external_api_key')
self.timeout = 30
def get_headers(self):
return {
'Authorization': f'Bearer {self.api_key}',
'Content-Type': 'application/json',
'User-Agent': 'Frappe/1.0'
}
def get(self, endpoint, params=None):
"""GET request with error handling"""
try:
response = requests.get(
f'{self.base_url}/{endpoint}',
params=params,
headers=self.get_headers(),
timeout=self.timeout
)
response.raise_for_status()
return response.json()
except requests.exceptions.Timeout:
frappe.throw(_('Request timeout'))
except requests.exceptions.HTTPError as e:
self._handle_http_error(e)
except Exception as e:
frappe.log_error(frappe.get_traceback(),
'External API Error')
frappe.throw(_('API request failed'))
def post(self, endpoint, data):
"""POST request"""
response = requests.post(
f'{self.base_url}/{endpoint}',
json=data,
headers=self.get_headers(),
timeout=self.timeout
)
response.raise_for_status()
return response.json()
def _handle_http_error(self, error):
"""Handle HTTP errors"""
status_code = error.response.status_code
if status_code == 401:
frappe.throw(_('API authentication failed'))
elif status_code == 404:
frappe.throw(_('Resource not found'))
elif status_code == 429:
frappe.throw(_('Rate limit exceeded'))
else:
frappe.throw(_(f'API error: {status_code}'))
OAuth 2.0 Flow:
def get_oauth_token():
"""Get OAuth access token with refresh"""
# Check cache first. Note: frappe.cache is an attribute, NOT frappe.cache().
# Pass a logical key — the wrapper auto-prefixes the site name; don't prefix manually.
token = frappe.cache.get_value('oauth_token:provider')
if token:
return token
# Get from settings
settings = frappe.get_single('OAuth Settings')
response = requests.post(
settings.token_url,
data={
'grant_type': 'client_credentials',
'client_id': settings.client_id,
'client_secret': settings.get_password('client_secret')
},
timeout=30
)
if response.status_code == 200:
token_data = response.json()
access_token = token_data['access_token']
# Cache token, refreshing well before expiry (60s buffer)
frappe.cache.set_value(
'oauth_token:provider',
access_token,
expires_in_sec=token_data.get('expires_in', 3600) - 60
)
return access_token
frappe.throw(_('OAuth authentication failed'))
Never block the web request on a slow or unreliable external call — enqueue it. Use the long queue with an explicit timeout for heavy work, and enqueue_after_commit=True when the job depends on data written in the current request:
# apps/myapp/myapp/integrations/tasks.py
import frappe
import requests
def push_to_external(invoice_name: str):
"""Runs in a worker process — fetch data via args, not request state."""
doc = frappe.get_doc("Sales Invoice", invoice_name)
try:
resp = requests.post(
frappe.conf.get("external_api_url"),
json=doc.as_dict(),
timeout=30
)
resp.raise_for_status()
except Exception:
# Log full traceback with a context label; do NOT frappe.db.commit() here
frappe.log_error(frappe.get_traceback(), "External push failed")
raise
Enqueue from a controller hook:
class SalesInvoice(Document):
def on_submit(self):
frappe.enqueue(
"myapp.integrations.tasks.push_to_external",
queue="long",
timeout=600,
enqueue_after_commit=True, # job sees this request's writes
invoice_name=self.name
)
frappe.cache.set_value(key, value, expires_in_sec=...) and read with frappe.cache.get_value(key). frappe.cache is an attribute (not frappe.cache()); it auto-prefixes the site name, so pass plain logical keys. Refresh tokens before they expire.frappe.log_error(frappe.get_traceback(), "<context>") so the full traceback is captured.timeouts and add a bounded retry (a fixed small number of attempts), not an unbounded loop.frappe.db.commit() after API calls in request context — Frappe auto-commits on success.Frappe Integration Patterns:
