It is quite possible, that none of my visitors will ever stumble upon the Russian CRM system called Bitrix, however if you are one among the unluckiest people, this article might be useful for you. More specific, I will cover how to work with the cloud solution, Bitrix24 and its REST API. There is almost no clear documentation, thus, I think a complete resource might come in handy some time.
So what exactly will we be doing? We will connect a web application to an existing bitrix24 portal. Possible use cases are:
- Upon registration on your web application you want to create a lead inside the CRM
- Upon completing an order you want to create an order inside the CRM
First and foremost you need to register yourself as a developer at bitrix24 marketplace, there are a lot of links leading to different sub-pages of 1c-bitrix.ru, you’ll need this one: https://marketplace.1c-bitrix.ru/about/for-dev/become.php. Don’t worry, you won’t need to fill out papers as required for a partner account. Just a regular one will do, I think it’s called a ‚technological partner‘.
Create your app
Next step is to create your app on marketplace. I don’t like calling it an app, because it collides with our web app, so let’s call it a container for our web application. When logged in as a technical partner, visit this page: https://partners.1c-bitrix.ru/personal/b24marketplace/
There you can register a container. Detailed on screenshot – http://take.ms/xNU1o
- Is my status (technical partner)
- Menu, where you can find the required link
- The actual button you need to press to create a new container
Check all those checkboxes – http://take.ms/FSujv
After creation you can click on your app container (most likely you’ll have just this one – recently created – in the list) and then you should see something like this: http://take.ms/osom0
client_id and client_secret is what’s important.
Do not forget to create at least one version! There you can type in a url for callbacks, it’s important for proper functioning aswell. Check out the screenshot: http://take.ms/fCoZC
Now comes the tricky part – we need to authorize your web app inside the bitrix24 portal. To do so you need to contact the administrator of bitrix portal.
If you are yourself an admin it gets a bit easier. Just visit „add an app“ – http://take.ms/To7hP and click on „for personal usage“.
Check „API use only“ and at least CRM in the long options list. In the marked field we need to provide the url we typed in in the versions tab at marketplace website (http://take.ms/is5ekP)
After adding your app container to your Bitrix24 portal you’ll obtain new client_id and client_secret, just like here – http://take.ms/x4qxr. Only use them from now on! You won’t need any tokens from marketplace.
Last part is to obtain refresh and access tokens. This might be quite cumbersome due to the fact, that you’ll need to retrieve a „code“ parameter which lives only 30 seconds. It’s not a big deal if you use some written program for all this stuff, but you can do it by hand as well.
Now open two tabs. Type in the first one (don’t hit enter yet!) – https://your-portal-url.bitrix24.ru/oauth/authorize/?response_type=code&client_id=<ENTER CLIENT ID FROM BITRIX PORTAL HERE>&redirect_uri=<ENTER URL FROM MARKETPLACE PAGE>
Type in the second one (don’t hit enter yet!) – https://your-portal-url.bitrix24.ru/oauth/token/?grant_type=authorization_code&client_id=<CLIENT ID FROM BITRIX PORTAL>&client_secret=<CLIENT SECRET FROM BITRIX PORTAL>&redirect_uri=<ENTER URL FROM MARKETPLACE HERE>&scope=<your-scope>&code=<LEAVE EMPTY AS OF NOW>
Input every variable without <>. Now hit enter in the first tab. You will be redirected to another URL where there will be a code parameter (with a value). Copy that value and insert it in the corresponding place in the second tab. Hit enter again. Now you should receive the desired tokens. Keep them safe!
Refresh token is valid for about a month. It is wise to store it in your database with a separate created_at date point. Upon expiring hit the url
&refresh_token=<CURRENT REFRESH TOKEN>
You will receive a new refresh token. Answer will look like this:
HTTP/1.1 200 OK
Same process goes for access token, with the only difference that it expires every hour. So you should check if the creation date was larger than 3600 seconds, and if yes, call the same url. You can separate those two refresh methods or call them all at once and update both tokens every time.
The fun part
Now you surely want to interact with the data from your Bitrix24 portal, right? You’ve made all the way down for this one reason. There are several methods (I will be covering only the CRM part, no calendar etc.).
The general url is following: https://<YOUR BITRIX PORTAL>.bitrix24.ru/rest/<METHOD NAME>.<TRANSPORT TYPE>&auth=access_token&<PARAMETERS>
Get all leads
Post a new lead
Please be careful as there are no quotation marks allowed. If there are whitespaces inside your data, make sure to use %20 instead. If you are using cyrillic data, make sure to encode it to stuff like this: %D0B3%D1B10 (in rails I do it by using URI.escape – encoded_name = URI.escape(name) )
Post a new deal
&auth=<YOUR TOKEN HERE>&fields[TITLE]=SOME-TITLE
Searching (and filtering)
&auth=<YOUR TOKEN HERE>&filter[PHONE]=8903227
Please note, that the filter method only searches from the left side, i.e. if the number in the Bitrix 24 portal is as following: 8 903 227 88 74 and you search for 8874 you won’t find anything. You need to start from the left, meaning searching either 8903 or 8903227 or even the full number. It also matter how the phone number is stored inside Bitrix (that’s some crazy bullsh*t, I tell you), because you need to check for all number formats,
8 903 227 88 74
8 903 227-88-74
Are all different numbers for the filter method.
Last, but not least you can specify the output with „select“ chaining. In my example I’m grabbing ID, Name and Last_Name from all possible fields.
It is highly recommended to create a new portal for testing, then install the documentation app. It has a console built in where your can look up all the remaining methods and url calls. Simply hit the „run this code“, then click on the „post“ tab – http://take.ms/GH5hM
Scroll down. There you should thee the complete url from the example – http://take.ms/vnU3i
Working with Bitrix24 REST API is far away from being easy like working with Twitter or Instagram API. However you can still do it. I hope my guide will help one lost soul out there. I’m planning on writing a gem for Ruby on Rails which will do all the ugly work for you. It should be out on the githubs around winter 2016/2017.