API

API-интерфейс нужен для обмена данными между сервисами FreshOffice и внешними системами: сайтом, личным кабинетом, 1С, собственным приложением.

Адрес API — do.freshoffice.ru. Описание методов с примерами запросов на разных языках — в подразделах: начните с быстрого старта, дальше таблица разделов.

О протоколе

Доступ устроен по протоколу OData (Open Data Protocol) — стандарту, специально предназначенному для выборки и представления данных в API.

Примеры в этой документации показывают полезные возможности OData, но не претендуют на полное описание протокола — за ним лучше обратиться к спецификации OData.

Токен доступа

Токен выпускается в приложении: Настройки → API. Нужны права доступа к этому разделу.

Все выпущенные токены хранятся в реестре, и любой из них можно выключить — трафик по нему сразу прекратится.

В запросе токен передаётся заголовком:

Authorization: Bearer XXXXXXX.XXXXXXX.XXXXXXX
Content-Type: application/json

Проверить связку удобно запросом GET https://do.freshoffice.ru/welcome/ — в ответ приходит стандартный объект со статусом.

Что доступно

Раздел Что умеет
Контрагенты Компании и физлица, контактные лица, телефоны, адреса почты, платёжные реквизиты: список и добавление
Сделки Список сделок и добавление новой
Почта Список писем, отправка, почтовые аккаунты
Пользователи Список активных сотрудников
Фильтры Общедоступные фильтры и созданные владельцем токена
Добавленные поля Ваши собственные поля по модулям
Справочники Значения справочников для контрагентов и сделок

Что стоит учесть

  • Ответы приходят только в JSON: форматы XML и ATOM не поддерживаются.
  • Служебные поля OData __metadata и __deferred не выводятся.
  • Данные выдаются по правам владельца токена: в списке будет ровно то, что этот сотрудник видит в приложении. Поэтому уровень прав доступа у технической учётной записи стоит продумать заранее.
  • Если ваша подписка ещё не переехала на freshoffice.ru, тот же API отвечает по прежнему адресу do.myfreshcloud.com — примеры в документации везде используют новый домен.
  • Описание предыдущей версии API (api.myfreshcloud.com) живёт отдельно — на Apiary. Токены между версиями не взаимозаменяемы.
Предыдущая
Оплата подписки
Следующая
Быстрый старт