Public API: подключение своей программы к Norman

Что можно сделать через API

Public API позволяет программе читать и изменять поддерживаемые записи Norman с помощью HTTP-запросов. Например, выгружать транзакции в дашборд, обновлять клиентов из CRM, готовить черновики счетов или загружать подтверждающие документы.

Публичный справочник охватывает сведения о компании, транзакции, существующие банковские подключения, клиентов, каталог товаров и услуг, счета, расписания повторяющихся счетов, документы и чтение налоговых отчётов и настроек. Также доступны распознавание документов, получение PDF/XML и связывание счетов с платежами. Доступные действия различаются по ресурсу. Платежи, авторизация банка и подача налоговых деклараций не входят в этот набор операций Public API.

Точные методы, поля и примеры находятся в документации разработчика. Если для интеграции нужен файл OpenAPI JSON, обратитесь в поддержку.

Выберите сценарий

• Документы и OCR: загрузите чек, прочитайте распознанные поля, запустите распознавание повторно или отправьте фрагмент изображения. Уже обработанные документы можно импортировать без OCR, указав внешний источник и ID для повторных запросов.
• Пакетная обработка: загрузите до 20 документов, не более 10 МБ на файл и 50 МБ суммарно. Затем запрашивайте прогресс, созданные транзакции и ошибки по каждому файлу. Этот сценарий может создавать или связывать транзакции, поэтому загрузка требует write_documents и write_transactions, а чтение статуса требует обоих прав чтения. Завершённое задание может содержать файлы с ошибками.
• Подтверждающие файлы: добавьте накладную или другой дополнительный файл к транзакции без OCR и замены основного документа. Исправление полей документа может обновлять связанные транзакции и требует обоих прав записи.
• Счета: синхронизируйте товары и услуги, получите предложенный номер следующего счёта, скачайте PDF/XML, свяжите платёж и отправьте доступное напоминание о просрочке. Можно прочитать расписание существующей серии счетов или остановить её. Каталог товаров использует права для счетов.
• Предложения из договоров: извлеките условия выставления счёта, затем проверьте получателя, суммы, даты и замечания перед созданием счёта. Цены позиций в предложении указаны в основных единицах валюты, а создание счёта принимает минимальные единицы. Само предложение не создаёт и не отправляет счёт.

Полные примеры: документы и OCR и работа со счетами. У каждого метода в справочнике указаны необходимые права.

Создайте ключ

1. Откройте Automations → Integrations → Public API или управление ключами.
2. Выберите компанию, с данными которой должна работать интеграция. При необходимости скопируйте её company ID.
3. Создайте именованный ключ, выберите права и срок действия. Для отчётов начните с Read only. Набор Invoicing включает чтение и изменение клиентов и счетов.
4. Скопируйте ключ при создании. Полное значение показывается один раз; в списке остаются его префикс и статус.
5. Сохраните ключ в переменной окружения сервера или хранилище учётных данных инструмента автоматизации. Не размещайте его на публичной странице, в репозитории, скриншоте или общем экспорте сценария.

Один ключ связан с одной компанией

Передавайте Authorization: Bearer YOUR_API_KEY вместе с запросом. Ключ привязан к своей компании. Идентификаторы компании в пути, теле запроса и необязательном заголовке X-Company-Id должны ей соответствовать. Клиенты и документы, на которые ссылается запрос, тоже должны принадлежать этой компании.

Права чтения и изменения выдаются отдельно. Например, read_transactions позволяет читать транзакции, а write_invoices разрешает поддерживаемые изменения счетов, но автоматически не добавляет право чтения счетов. full_access охватывает публичные операции для компании ключа. Права аккаунта, ограничения тарифа и статус документа продолжают действовать.

Выполните первый запрос

Этот пример читает сведения о компании ключа. Замените значение-заглушку у себя:

export NORMAN_API_KEY='nrm_replace_with_your_key'

curl --fail-with-body 'https://api.norman.finance/api/v1/companies/' \
  -H "Authorization: Bearer $NORMAN_API_KEY"

Успешный ответ имеет HTTP-статус 200 и список results. Сохраните publicId компании для запросов, которым нужен company ID. Архивные компании по умолчанию скрыты из списка; при необходимости добавьте ?include_archived=true.

С правом read_transactions можно затем получить первую страницу транзакций:

curl --fail-with-body 'https://api.norman.finance/api/v1/accounting/transactions/?page=1&page_size=20' \
  -H "Authorization: Bearer $NORMAN_API_KEY"

Ответы со списком содержат results, next, previous и count. Для полной выгрузки переходите по next, пока значение не станет null. Пустой список транзакций тоже может быть успешным ответом.

Настройте следующий шаг

В примерах показаны создание клиента, черновик счёта, загрузка документа и выгрузка нескольких страниц. Поля JSON используют camelCase; названия query-параметров, например page_size, берите из справочника. Суммы транзакций и ставки позиций счёта указываются в минимальных единицах валюты: 4999 для EUR означает 49,99 €. Перед записью проверяйте схему запроса, а не просто копируйте значения из ответа.

Замена ключа и ошибки

Создайте новый ключ, обновите интеграцию, проверьте один запрос и затем отзовите старый ключ. Истёкшие и отозванные ключи перестают работать. Доступ также зависит от действующего аккаунта создателя ключа и его доступа к компании.

• 401: проверьте Bearer-заголовок, срок действия и отзыв ключа.
• 403: проверьте права, компанию, поддержку операции и требования аккаунта.
• 400 или 422: исправьте значения полей или состояние документа по сведениям в ответе.
• 429: подождите время, указанное в Retry-After.

Перед повтором запроса на изменение после тайм-аута проверьте, не создана ли уже запись. Подробнее: ошибки и повторные запросы.

Для визуальных сценариев переходите к n8n или Make. Для ИИ-ассистента используйте инструкцию MCP.