Bitrix 24 REST API

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.

Getting started

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
  • etc.

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

  1. Is my status (technical partner)
  2. Menu, where you can find the required link
  3. 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.

Attention!

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

Managing bitrix24

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!

Tokens

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

You will receive a new refresh token. Answer will look like this:

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>

Examples

Get all leads

https://your-portal-url.bitrix24.ru/rest/crm.lead.list.json?&auth=uoefoqa8mridzaapux6ja649jbo621xq

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

Searching (and filtering)

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
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.

Everything else

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

Conclusion

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.

Happy new energy! This is how you make bitrix work with git.

I wish everyone a pleasant new 2015!

May your business flourish, your apps find new users and your customer forget the number of your technical hotline.

Besides, if you should ever happen to work with 1C-Bitrix framework here are some hints how to befriend it with git. If you just try to plain start developing a Bitrix app under git you may encounter few uncomfortable things – since Bitrix is huge (more than 18000 files) ever commit will take long. In most cases I received plain errors instead of pleasant working.

So here what you should do:

First, add this to your local git config

You may want to play around with the numbers, just keep in mind following:

Larger window sizes may allow your system to process a smaller number of large pack files more quickly. Smaller window sizes will negatively affect performance due to increased calls to the operating system’s memory manager, but may improve performance when accessing a large number of large pack files.

As seen here

So now which files to exclude from bitrix using rather .gitignore or /.git/info/exclude? Of course I can’t tell you where to put your development files, but it is a good practice not to touch those:

Meaning ignoring them is generally a good idea. This will save you a lot of time! Happy coding. (For the record – we’re using GitLab instead of GitHub for reasons of security, however commands are just the same for both of them)

Next book sneak peak

The next one, “The Software Development Edge” by Joe Marasco is finally done. Since I’m continuing my more “scientific” approach on book summarizations this time it turned out to be really extensive. I guess it will take a while to write everything important down.

A little sneak peak on my work regarding this awesome book by Joe Marasco.
A little sneak peak on my work regarding this awesome book by Joe Marasco.

[readolog_blockquote ]One of the main reasons for Joe being able to deliver software in time was his effort to understand every detail of development, every problem occuring, thus, leading to knowledge where you can make right decisions for the whole project movement. This effort is not based upon some kind of magic, but simply upon investing a lot of time in talking with developers.[/readolog_blockquote]