Sending documents via MakeLeaps is a secure and hassle-free process and can be done in just five simple steps.
In this tutorial we will go through the process of creating a client, a contact and a document and then sending it via the API. We will use Python to demonstrate this process, but will provide enough explanation to easily implement it in the language of your choice.
Let’s assume you have the following data on one of your client companies, a contact within that organisation, an invoice that you want to send to them and you want to send the invoice to this client using securesend via the MakeLeaps API.
Client: CLIENT-12345 ------------------- Example Co ------------------- Sato sato@example.com ------------------- Document: INV001 ------------------- Something small: 1000 JPY Something big: 98999 JPY -------------------
To keep your data safe, MakeLeaps uses OAuth2 to authenticate API users. This requires you to create an API key and obtain a Client Id and Client Secret.
This can be done via the web interface by going to https://app.makeleaps.com/integrations/makeleaps/api-users/ and clicking the “Add API Key” button.
Once you have created your API key, you can see your Client Id and can reveal your Client Secret by clicking the Show API Secret button.
Now that you have your Client ID and Secret, you can request an access token from MakeLeaps and then pass it with all of your following requests to authorise them.
Here we are writing a helper class to handle authentication for us. We make a POST request to https://api.makeleaps.com/user/oauth2/token/ with our Client Id and Secret in the “Authorization” header, base64 encoded and preceded by the authentication type “Basic”.
The Authorization header should be in the form `Authorization: Basic client_id:client_secret` and we should also provide the grant type `client_credentials` in the request body.
import requests import base64 class MakeLeapsAPI: def __init__(self, client_id, client_secret): self.client_id = client_id self.client_secret = client_secret self.token = None def auth_client(self): url = 'https://api.makeleaps.com/user/oauth2/token/' creds = f'{self.client_id}:{self.client_secret}'.encode('utf-8') creds_encoded = base64.b64encode(creds).decode('utf-8') headers = {'Authorization': f'Basic {creds_encoded}'} data = {'grant_type': 'client_credentials'} response = requests.post(url, data=data, headers=headers) response_json = response.json() return response_json['access_token']
Below, we add a post method to our helper class to send POST requests with the correct headers, authorisation and a correctly formatted POST body. We’ll also create a method to add the Bearer token to the `Authorization` header preceded with “Bearer”. This can be used for other requests to the API as well.
When the MakeLeaps API receives the request, it will check for the Bearer token here, and if it is still valid, will authenticate your request.
import json class MakeLeapsAPI: ... def authorize_header(self): return {'Authorization': f'Bearer {self.token}'} def post(self, url, data): headers = self.authorize_header() headers['Content-Type'] = 'application/json' data = json.dumps(data) response = requests.post(url, data=data, headers=headers) return response.status_code, response.json()['response']
We can then use our helper class in our main application file to create a new Client.
To do this we need to assemble the data that represents the client that we want to create and send a POST request to the API with the client data in the request body.
from api import MakeLeapsAPI CLIENT_ID = '<your client id>' CLIENT_SECRET = '<your client secret>' api = MakeLeapsAPI(client_id=CLIENT_ID, client_secret=CLIENT_SECRET) partner_mid = 'XXXXXXXXXXXXXXXXXXX' client = { "client_external_id": "CLIENT-12345", "contacts": [ { "contact_type": "organization", "name": "Example Co", "addresses": [], "email": None, }, { "contact_type": "person", "family_name": "Sato", "addresses": [], "email": {"address": "sato@example.com"}, }], } client_url = f'https://api.makeleaps.com/api/partner/{partner_mid}/client/' client_status, client_res = api.post(url=client_url, data=client)
Once you have created a client, you can create a document in a similar manner. Prepare the document data and send it in the request body of a POST request to the MakeLeaps API.
Notice that here we are passing the client that we just created via the URL pointing to that resource. We can get this from the response of the creation request we made in the previous step.
Likewise we can do that same with “client_contact” which is created from the contact data we pass when creating a client.
document = { "document_number": "INV001", "document_type": "invoice", "document_template": "ja_JP_2", "date": "2018-02-05", "client": f"{client_res['url']}", "client_contact": f"{client_res['contacts'][0]}", "lineitems": [ {"kind": "simple", "description": "Something small", "price": "1000"}, {"kind": "simple", "description": "Something big", "price": "98999"} ], "currency": "JPY", "total": "99999", "subtotal": "99999", "tax": "0", } document_url = f'https://api.makeleaps.com/api/partner/{partner_mid}/document/' status, response = api.post(url=document_url, data=document)
If you want to specify different tax rates for each item, we can add a “mixed_tax_rate_totals” field to the document. For example, if the first item is taxed at 8% and the second is taxed at 10%, it will look like the following.
document = { … "mixed_tax_rate_totals": { "8": { "subtotal": {"amount": "10000", "currency": "JPY"}, "tax": {"amount": "800", "currency": "JPY"} }, "10": { "subtotal": {"amount": "98999", "currency": "JPY"}, "tax": {"amount": "9899.9", "currency": "JPY"} } },
Make sure to update the “tax” field from 0 and add “tax_rate” fields to each item.
"lineitems": [ {"kind": "simple", "description": "Something small", "price": "1000", "tax_rate": "8"}, {"kind": "simple", "description": "Something big", "price": "98999", "tax_rate": "10"}, ],
Now we have created a document and a client and client contact to send it to, all that is left is to send it.
Sending a document required the creation of a sending order. You can think of a sending order as something similar to an envelope; it contains what we want to send and has the instructions for sending it.
Sending orders is a little bit more sophisticated than an envelope though. They allow you to send you documents by post, by secure inbox via email, or by both of these methods at the same time. They also offer the option of MakeLeaps payments, which allow your clients to use their credit or debit card to pay amounts of money.
Here we are just going to send the document that we created by secure inbox. When sent, an email will be sent to your client with a link that leads to a secure page displaying the document’s PDF. Payments can also be made from this page if `enable_cc_payments` is turned on.
As with the client and the document that we created, simply assembling the data representing the sending order and then sending it in the request body of a POST request to the API will create the sending order in the MakeLeaps application.
# Create Sending Order sending_order = { "recipient_organization": f"{client_res['url']}", "securesend_selected": True, "to_emails": ["sato@makeleaps.com"], "subject": "Invoices for February", "message": "Invoices are attached. Thank you for your business.", "enable_cc_payments": False, "sendbypost_selected": False, "stamp_type": "invoice", } sending_order_url = f'https://api.makeleaps.com/api/partner/{partner_mid}/sending/order/' order_status, order_res = api.post(url=sending_order_url, data=sending_order) print(order_status, order_res) # Add document item to send order. doc_item = {"position": 0, "document": document_res['url']} doc_item_status, doc_item_res = api.post(url=order_res['items_url'], data=doc_item) print(doc_item_status, doc_item_res)
As mentioned before a sending order is like an envelope. Up to this point, we have put what we want to send in the envelope and written the instructions for sending on it. We have not, however, actually sent it.
Before sending the MakeLeaps API needs to do some processing on the created sending order. If you try to send the document before the processing has been completed, you will get an error and the order will not be sent.
You can check the current state of the sending order by making a GET request to the API URL of the created sending order.
Here, we add yet another method to our helper class that allows us to make authenticated GET requests to the MakeLeaps API.
Then we can keep polling for the completion of the processing by checking the `ready_to_order` property returned in the response to the GET request to the sending order’s API URL.
Here we are simply looping over the process, but in reality you will probably want to loop until it is done and implement a time out condition so that it doesn’t poll forever if something goes wrong.
class MakeLeapsAPI: … def get(self, url): headers = self.authorize_header() headers['Content-Type'] = 'application/json' response = requests.get(url, headers=headers) return (response.status_code, response.json()['response'])
When `ready_to_order` is `true` we can send the sending order by making a POST request to the `send_url` that is returned in the GET request to the sending order’s API URL.
And that’s it!
You have created your first client, document and Sending Order with the MakeLeaps API and then sent it once it had finished processing.
# Poll for when the sending order is ready to send. for i in range(10): ready_status, ready_res = api.get(url=order_res['url']) print("GET STATUS") print(ready_status, ready_res) if ready_res['ready_to_order']: # Send sending order send_status, send_res = api.post(url=order_res['send_url'], data={}) print(send_status, send_res) break else: time.sleep(5)
