Made withERPNextClip

ERPNext/Frappe: Making API Calls

K

Karani Geoffrey

Creator on the ERPNext channel

Watch on YouTube ↗

27K viewsApr 12, 20219:12 runtime

Learn how to create and consume APIs within the ERPNext and Frappe framework. This tutorial guides you through writing a custom Python API endpoint in a DocType folder, handling file permissions, and executing SQL queries using `frappe.db.sql`. Discover the necessity of…

Chapters

#erpnext#clip#cmscrm

Creating an API Endpoint in Frappe

You can create a dedicated API file, such as api.py, directly within a specific DocType's folder (e.g., erpnext/healthcare/doctype/patient/api.py).
If you encounter file system errors, you may need to use sudo touch to create the file with the correct permissions.
The first step in your script is to import frappe.

Defining and Whitelisting the API Method

Define a standard Python function to contain your logic (e.g., def get_patient_details():).
To expose this function through the API, you must decorate it with @frappe.whitelist.

Important
Without the @frappe.whitelist decorator, Frappe will block all external requests to the method with a permissions error.

If your function requires parameters that might not be provided in the call, set a default value (e.g., def get_patient_details(patient_id=None):) to avoid missing required parameter errors.

Querying Data with Frappe's DB API

Frappe provides a safe way to execute SQL queries using frappe.db.sql().
To get results back as a list of Python dictionaries instead of tuples, use the as_dict=True argument.
Example: frappe.db.sql("SELECT * FROM tab Patient WHERE owner='Administrator'", as_dict=True)

Tip
You can test your SQL queries beforehand by using the bench mariadb command in your terminal to get a direct database shell.

API URL Structure

The URL to call your custom method follows a specific pattern:

Format: http://<your-site>/api/method/<app>.<module>.<doctype>.<api_filename>.<function_name>
Example: http://localhost:8000/api/method/erpnext.healthcare.doctype.patient.api.get_patient_details

Authentication for External Clients (like Postman)

External clients must provide authentication headers to consume the API.
Frappe supports Token-Based Authentication, which is recommended over password-based methods.

Steps to Authenticate:

Navigate to the User record in your ERPNext desk (e.g., Administrator).
Scroll down to the API Access section.
Click Generate Keys to create an API Key and API Secret.
In your API client (like Postman), set an Authorization header.
The value for the header must be in the format: token <api_key>:<api_secret>.

Note
The authorization value is the literal string token, a space, your API Key, a colon (:), and then your API Secret, with no extra spaces (e.g., token 123abc456def:789ghi012jkl).

Setting Up the API File and Permissions

Hello, in this one I'm going to be showing you how to consume APIs in ERPNext. So, I'm going to be writing a custom file here in my PC and doctype. If this is where I want to write my API, and I want to use the Patient doctype, but you can write this file, you can put this file basically anywhere, including on your apps, your app directory here. But because I'm working with this doctype only, I just want to write a file here. So, create a new file and call it api.py. I want to save it.

Save the file, and I'm not able to save that because I don't have permissions. So I can just come here and go to... and go to change directory to erp.

Where am I? Let me just check where I am. So, change directory to apps and then to erpnext, and then another erpnext, and then to healthcare, and then to doctype, and then to the patient doctype.

And when you list this, you'll see that I do not have any api file here. So I can just say touch... maybe I can just do sudo touch api.py and I have my file. So if I list now, I have an api.py file there. So coming back here, just remove this without saving. I have my api.file.

Writing the Basic API Function

So the first thing to do here is to import, import Frappe. And then I'm going to write my function. So I'm just going to say define a function. I'm going to call get_patient_details. You can call it whatever you want to call it. And this one, I'm going to pass in the patient, the patient ID. And then here, I'm going to just say return... um, return Frappe... and before I return this, let me show you how I'm going to get this content.

Crafting and Testing the SQL Query

So I'll go back to my opt then bench then erp. This is the directory of my app and here you can just see bench mariadb. Good.

Executing the SQL Query via Frappe DB API

And then you can see select... I just want to select the first name from the table is tab Patient. And then I'm going to put a condition here. And if I go to MySQL of my of my app, this is the table name and here I just want to put one, one, one parameter that you can use that you can use here. But this, this just to demo this example. So you, you can do basically anything. You can pass in the patient ID, you can pass in whatever you want to pass here. But I just want to pass in the owner because I can see the patients here with the owner of administrator. So I'll just say where owner equals the administrator. Okay? So when I do that, I can see that I have three patients there. So I only grabbed the first name. Let me pick this query; this is what we'll be needing. And they can just exist from there and then so here I can run this. I can, I can run the same thing, but remember, basically here you can put in whatever logic you want to put into this section. So, I'll say on the frappe.db.sql and then this is .sql. And then here I'm going to do... you can do a formatted string. That is if, of course, because you will be passing this patient ID dynamically. So, this is three, four, five, six. Make sure you have six of them here. And then paste this. This one I have pasted what that we wrote on the on the command here on the terminal here. And then I want to return this thing as a Python dictionary. So just say as_dict equals true. All right?

So when that is done, I am now ready... Let me just allow this to save. I have saved my file, and now I am ready to consume this uh, this this API.

Browser Access, Whitelisting, and Error Handling

So, how will, how I will do that? How I'll do that, I'll come to my browser. And then how we access this is through... you put in... If you go to Frappe documentation, you'll see that you put in your base URL, and then api, and method, and then your app, and then the doctype and the doctype, and then the... this is the module, and then the doctype is patient, and then you put in your file. So this is my file, and this is the function inside of that file. So my function is get_patient_details. Let me just copy that and paste here to confirm. And not reachable because bench is not running. So let me bench start there quickly. And then now I can reload here. And it is accessing our method successfully but is this thing that we do not have permissions to do that.

Reason being, in Frappe if you want to access these things through API, you have to whitelist them. So we need to say @frappe.whitelist here. So whitelist our our method, okay? And then when we refresh... oh no I clicked go home. When we refresh this, now we get another error here but telling us that patient details is missing one required parameter. And we can just come here and say allow it to accept None. So allow it to save again and go back and refresh. And there we go. So we have our first name, Jeffrey and Kevin and Steve. Very good. So it is running on the browser.

Consuming the API in Postman with Token Authentication

But now we want to consume this API through an uh, an application like uh, like Postman. So how do we do that? Let me just clear this. This is what I was using to test. So how we get that to work on Postman is we are going to use exactly the same, the same, uh the same the same URL here. So let me paste it on the URL section, and then I try to access it. This doesn't work. And the reason why it doesn't work, if you come to preview here, is telling you that you do not have permissions to do this. This is because ERPNext expects you to pass in some headers here. In the header, you are supposed to pass in authorization... it's a token.

And where I'm getting this is from the documentation here. You can see that we have two types of authorization. We have token-based and we have password-based. We are going to be using token-based in this tutorial. So we have authorization which is a token, and then we concat... we we concatenate the, not concatenate, but we get the token by joining the API key and the API secret. So what we're going to do to get this, go to the user, user section of your app. I want to use the administrator, and then scroll down to where you see API access. And then here, I had already generated this, but you can just generate others. Just click on Generate Keys, and this one gives me the secret. So I can just copy the secret... come with it. So this is supposed to be token... that is the secret. If you come to the documentation, you see that we are told to give the token, colon, the secret. So back here we have the secret, and then we just copy the token. This is the key, sorry, the key and then the secret. So go back to your Postman and paste it there. So we have that. If we push that one more time, we get our data. If we preview the pretty one, here we go. So we have a message and the first name Kevin, Steve, and Geoffrey.

Modifying the API and Final Demonstration

If we wanted to get all the data, of course we can just come to our method here and instead of getting that we just add an asterisk, or you can get whatever you want. Then I can save that and then I go to my token... to my Postman, send, I get everything. So we have message, name Joffrey, all that detail, and then we have Kevin with all that detail, and then we have Steve with all that detail. So that's how you do it in ERPNext. Thank you so much for watching, and see you in the next one.