Как-то раз, одним прекрасным то ли летним то ли осенним днём (уже не помню) мне прилетел новый таск. «Влад, поздравляю, ты будешь пилить приложение для QuickBooks». «Квикбукс? Что за...» — подумал я, но отказаться не мог, таск есть таск. «Ну, погуглю что такое квикбукс, потом что такое квикбукс-приложение, потом читну статью на хабре об этом всём, потом найти sdk, и дело в шляпе» — подумал я, и открыл гугл. Как же я ошибался…

Первое — хабр ничего не знает по поводу всего этого. Нет, есть три с половиной статьи в которых упомянут QuickBooks (далее просто — QB), но ничего полезного я в них не нашёл. Меня это сразу же смутило — как так, вроде известная вещь — а хабр молчит. Странно.

Второе — пришлось убить немного времени на то чтобы понять что такое «QuickBooks Application», и с чем его едят. Не знаю, может это только я такой далёкий, но далеко не сразу я понял что приложение — это просто сайт. При слове «приложение» у меня сразу возникли мысли о чём-то ином, о каком-нибудь хостинге от QB, о хитрой-хитрой апишке. Оказалось попроще. Ох уж эта мода называть всё в web — приложением.

И третье — официальный PHP SDK для QuickBooks Online. А его нет. Точнее как — он то есть, но он настолько неполный, плохо документированный и недоделанный что использовать его не представлялось возможным. В нём напрочь отсутствовала часть API мне необходимая. Не знаю, возможно его уже допилили, но я сильно в этом сомневаюсь. На момент написания поста — он так и остаётся убогим.

В целом, этот пост для тех кому понадобится так же само создать приложение для QB на PHP. Он поможет по-быстрому осознать основные моменты и грабли на которые я наступил. Местами будут просто очевидные вещи из документации — но я предпочёл ещё раз их уточнить.

Итак, что же вообще такое QuickBooks Application, и с чем его едят

Как я уже сказал выше — по своей сути QuickBooks Application это сайт. Это может быть отдельный сайт (как получилось в моём случае) или же его часть. Если обобщить — это просто тесная интеграция сайта с QB которая позволяет логиниться через него, получать кое-какие данные и совершать операции. И если всё по интуитовскому фэн-шую (intuit — компания-владелец QB) — вам разрешат разместить ваше приложение на QuickBooks App Store по адресу Apps.com. Буду честным — меня смутило имя домена когда я увидел его впервые. Я ожидал бы увидеть там гугловский плеймаркет, эпловый аппстор, да хоть магазин Microsoft — но никак не квикбукс… Ну да ладно.

Проблемы с PHP

Как я опять таки уже писал выше — с PHP есть некоторая проблема. По сути, вы не можете использовать официальный PHP-SDK для QuickBooks Online (далее — QBO). Я не знаю, может для чьих-то нужд его и будет достаточно, но он настолько неполный и слабо документирован что я сомневаюсь в его целеобразности. Для C#, Java — шикарные SDKи с полной документацией. Для PHP — недописанный обрезок. Это удивляет и смущает. Серъёзная фирма, работа с деньгами, ориентированость на веб — и такая подстава с PHP. Всё было бы совсем плохо если бы не ребята из ConsoliByte. Судя по их сайту — они то-ли предлагают свои услуги по QB, то-ли просто консультанты — не знаю вообщем, но факт в том что они создали OpenSource QBOv3 PHP-SDK. Более того — ссылку на него разместили даже в документации самого квикбукса, как «3-rd party contibuted». Так что несмотря на то что код этого SDK — не образец прекрасного — используем его. Тыц. Там же есть и готовый мини-пример в который нужно только подсунуть апи-ключи.

Мой некрасивый скриншот

Суть приложения

Суть работы приложения заключается в следующем — юзер подключается к вашему приложению (разрешает ему доступ к своим данным, если говорить проще) и потом работает с ним. Всё просто!

Для подключения используется фирменная кнопка от QB. Интересность в том, что использовать можно ТОЛЬКО её. Юзер может подключится к вам напрямую с apps.com, через интерфейс QBO, или же прямо из приложения через эту кнопку. Вы не имеете права изменять её внешний вид, размеры, надписи — только использовать такую как выдаёт QB (есть в двух цветах и четырёх размерах). Вы не имеете право как-то по другому инициализировать подключение вашего приложения. Только через кнопку «Connect to QB» которая в документации называется не иначе как «C2QB Widget». Это во-первых. Во-вторых, как окажется позже — эту кнопку нельзя использовать для аутентефикации юзера в вашем приложении. В нашем приложении не было системы аутентификации — оно отделённое от основного сайта и других юзеров просто не бывает. Поэтому первоначально я сделал всё так — коннектим юзера, если он новый — пишем его в базу, и пошло-поехало. Для моих нужд этого было достаточно. Как оказалось позже — так нельзя. Для аутентификации нужно использовать только «Sign in using QB» виджет, и кнопка C2QB должна быть внутри приложения, и только так. Неприятно было узнать об этом в самом конце.

Connect To QuickBooks будет работать через OAuth (всё скрыто под капотом SDK, довольно удобно), Sign in — через OpenId. Я использовал библиотеку LightOpenId тыц, опять таки — OpenSource.

Когда я работал с примером из SDK — я не сильно углублялся в конфиг, и пропустил мимо взгляда параметр the_tenant. Я не встречал его в документации или readme поэтому не придал этому особого значения. Не знаю, может это общепризнанное название — но я его не встречал ранее. Как оказалось позже — это идентификатор нашего юзера который сделал коннект к нашему приложению. Каждому юзеру надо его предоставлять. У меня получилась забавная история с этим — тенант у меня был статический, в конфиге, и отправил я приложение на ревью. Захожу — залогинен как квикбуксовский юзер какой-то. «Тю» — подумал я, и забыл. А потом начал замечать что я постоянно уже под кем-то залогинен. Разлогинился, попросил коллегу зайти со своего компа, потом обновил страницу — и я залогинен! Ох ты ж ёжик…

Review для публикации на apps.com

Для того чтобы ваше приложение пустили на apps.com — оно обязано пройти 3 вида проверок. Marketing, Security и Functional reviews. Происходит это так — вы сабмитите своё приложение. Через время вам начинают писать с трёх имейлов (3 проверки) о том что у вас не так.

Marketing проверка смотрит на ваше описание приложения, скриншоты с него, наличие саппорта, и всё такое. Грубо говоря — проверка того что вы красиво его представляете.

Аудит безопасности проводит внешняя компания cigital.com, по наёму интуитом. Они делают аудит а потом присылают вам отчёт, который гласит где что плохого, как это зарепродьюсить и как зафиксить. Отличный, вообщем-то репорт. Тестят судя по всему какими то скриптами, проверяют все возможные уязвимости. У нас в приложении есть открытая форма — для фидбека. Так вот судя по всему — их скрипт атакует все формы которые находит, потому что нам на почту пришло тысячи полторы писем с этой формы в которых менялся только текст в стиле . 4 поля в форме — тупой перебор каждого из 300+ (примерно) вариантов для каждого поля. Если честно — до сих пор не понимаю что они проверяли этим. Форма нигде не выводится в приложении, откуда им знать если что-то сработает? Кстати, на форумах я читал что-то о том что они проводят и код-ревью, но, наверное, это было раньше — ибо у нас никакого кода не просили. Грабли на которые мы наступили:

1) Server:Apache/2.4.7 (Ubuntu)
X-Powered-By:PHP/5.5.9-1ubuntu4.12 — вот такие хедеры в респонсе от сервера. Признаюсь честно — плохо понимаю чем это сильно опасно, но у них это значилось как уязвимость типа «Лишняя информация отдаваемая сервером», хоть и с минимальным priоrity.
2) Cookie не через https. С этим отдельная история. Почему-то аудит они проводили не на прод-приложении, а на нашем стейджинге. Естественно, никто не будет покупать ssl для стейджинга, поэтому https там не было. За что получили 5 или 6 записей. Чтобы быть честным — проблемы это не составило, мы просто написали что это стейджинг а на проде всё норм будет — и нам поверили на слово.
3) Возможность замены куки. the_tenant (о котором я писал выше) хранится в куках, и если его изменить — приложение успешно его принимало. Это не представляло никакой опасности, на самом деле, да и сами они написали что это самый низкий приоритет, но всё же.

Ревью функционала. Люди (вручную) проверяют и нажимают всё что может и умеет ваше приложение. Если что не так (вёрстка поплыла, ошибка вылезла, не сработало вообще, и т.д.) — пишут мол так и так. Иногда даже видео аттачат, как они это воспроизвели. И да, ещё одно — проверяйте слово QuickBooks! В правилах написано что не допускается никаких сокращений, и QuickBooks должно писаться как QuickBooks, и никак иначе. У меня в нескольких местах было Quickbooks («b» с маленькой) — на это сразу же указали мол проблема. Так что надо следить.

Итог

Cпустя чуть больше месяца я зафиксил всё что у нас нашли, и мы успешно прошли ревью. Сейчас наше приложение успешно размещается на apps.com. Показать, увы, не могу — ибо NDA. Что интересно — после размещения можно делать что угодно в коде, повторного ревью не нужно. Для изменений описания — нужно, а функционал — меняй сколько влезет.

Надеюсь мой пост кому-нибудь пригодится и благодаря ему он съэкономит несколько часов своей жизни. Если что не так — пишите в комментарии, вполне возможно что я что-то неправильно описал