Download OpenAPI specification:
PRE-LAUNCH: registration, payments, sending and receiving are NOT open. This is a preview contract. Do not collect credentials or documents, request login codes, or call transactional endpoints. Check https://faxhub.us/launch.json before any operation.
FaxHub API backed by the existing BMI ERP. Base URL: https://api.faxhub.us/v1. This dedicated contract is built and published by sites/faxhub.us only. The branded API hostname is planned; its production activation has not been verified.
After launch, sign in at https://app.faxhub.us using the existing ERP account system (service=faxhub).
API keys use the existing ERP format: X-API-Key: <id>:<secret>.
Key management requires a genuine customer cabinet Bearer session, not another API key.
X-Account-Id selects an owned billing account returned by GET /accounts.
Prefer an account-bound key. Existing ERP keys are not automatically fax-only or spend-limited.
PUT creates a fax draft; POST /faxes/{faxId}/send starts real transmission and billing. Use send_now=false when creating a draft. Never blindly repeat a write after a timeout. Currently billing occurs before transmission; automatic failure refunds are not implemented. Approved launch prices do not establish that backend billing has already been configured. Incoming-number purchase, inbound inbox, quotes, agent OAuth and new Stripe offers are not yet represented by implemented FaxHub-specific operations in this contract.
Загрузка документа для факса (multipart/form-data, поле file). Файл конвертируется
в fax-ready PDF (US Letter, 200 dpi, grayscale), считаются страницы, создаётся превью.
Поддерживаемые форматы: PDF, DOC, DOCX, JPG, PNG, TIFF, BMP, HEIC. Лимит размера — 50 МБ.
Полученный id передаётся в file_ids при создании факса. Вложения, не привязанные
к факсу в течение 24 часов, удаляются.
FaxHub gateway limit: the complete HTTP payload, including multipart overhead, must be below 10 MB. The ERP 50 MB limit above does not apply through API Gateway. Large-file direct uploads and asynchronous conversion must be implemented separately before advertising larger uploads.
| file required | string <binary> Документ |
| enhance | boolean Улучшение фото с камеры (выравнивание освещения); к документам не применять |
{- "id": "c1f876d4-e18b-44b4-b49e-173397394095",
- "name": "contract.pdf",
- "mime": "application/pdf",
- "pages": 12,
- "created_at": "2026-07-03T10:00:00Z"
}Список контактов-получателей факсов
| q | string Example: q=acme Поиск по имени |
| page_num | integer Example: page_num=1 |
| page_size | integer Example: page_size=50 |
{- "data": [
- {
- "id": 1,
- "name": "Acme Corp",
- "company": "Acme Inc.",
- "fax_number": "18772096018",
- "phone_number": "18775551234",
- "email": "fax@acme.com",
- "notes": "Main office fax"
}
], - "navigation": {
- "page_size": 50,
- "page_num": 1,
- "page_count": 1
}
}| name required | string |
| fax_number required | string Номер факса (7-15 цифр, любые разделители игнорируются) |
| company | string |
| phone_number | string |
string | |
| notes | string |
{- "name": "Acme Corp",
- "fax_number": "+1 (877) 209-6018",
- "company": "Acme Inc.",
- "phone_number": "18775551234",
- "email": "fax@acme.com",
- "notes": "Main office fax"
}{- "id": 1,
- "name": "Acme Corp",
- "company": "Acme Inc.",
- "fax_number": "18772096018",
- "phone_number": "18775551234",
- "email": "fax@acme.com",
- "notes": "Main office fax"
}Частичное обновление — передаются только изменяемые поля
| contactId required | integer <int64> Example: 1 ID контакта |
| name required | string |
| fax_number required | string Номер факса (7-15 цифр, любые разделители игнорируются) |
| company | string |
| phone_number | string |
string | |
| notes | string |
{- "name": "Acme Corp",
- "fax_number": "+1 (877) 209-6018",
- "company": "Acme Inc.",
- "phone_number": "18775551234",
- "email": "fax@acme.com",
- "notes": "Main office fax"
}{- "id": 1,
- "name": "Acme Corp",
- "company": "Acme Inc.",
- "fax_number": "18772096018",
- "phone_number": "18775551234",
- "email": "fax@acme.com",
- "notes": "Main office fax"
}Список сохранённых шаблонов cover page клиента
{- "data": [
- {
- "id": 1,
- "name": "Standard",
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018",
- "message": "Please find the documents attached.",
- "is_default": true
}
], - "navigation": {
- "page_size": 50,
- "page_num": 1,
- "page_count": 1
}
}| name required | string |
| sender_name required | string |
| contact_info | string |
| message | string |
| is_default | boolean |
{- "name": "Standard",
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018",
- "message": "Please find the documents attached.",
- "is_default": true
}{- "id": 1,
- "name": "Standard",
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018",
- "message": "Please find the documents attached.",
- "is_default": true
}Частичное обновление; is_default: true делает шаблон дефолтным (снимая флаг с остальных)
| templateId required | integer <int64> Example: 1 ID шаблона |
| name required | string |
| sender_name required | string |
| contact_info | string |
| message | string |
| is_default | boolean |
{- "name": "Standard",
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018",
- "message": "Please find the documents attached.",
- "is_default": true
}{- "id": 1,
- "name": "Standard",
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018",
- "message": "Please find the documents attached.",
- "is_default": true
}Webhooks клиента для событий статусов факсов (secret не возвращается)
{- "data": [
- {
- "id": 1,
- "events": [
- "fax.sent",
- "fax.error"
], - "is_active": true,
- "last_status": "http 200",
- "last_sent_at": "2026-07-03T10:00:00Z",
- "secret": "whsec_1a2b3c..."
}
], - "navigation": {
- "page_size": 50,
- "page_num": 1,
- "page_count": 1
}
}Регистрация URL для событий факсов. Ответ содержит secret — он показывается
ЕДИНСТВЕННЫЙ раз, сохраните его. Доставка подписывается заголовком
X-FaxHub-Signature: sha256=<HMAC-SHA256(body, secret)>; событие — в X-FaxHub-Event.
После 10 неудачных доставок подряд webhook отключается автоматически.
| url | string HTTPS URL доставки (обязателен при создании) |
| events | Array of strings Items Enum: "fax.sent" "fax.error" События подписки (обязательны при создании) |
| is_active | boolean Включить/выключить (только для обновления) |
{- "events": [
- "fax.sent"
], - "is_active": true
}{- "id": 1,
- "events": [
- "fax.sent",
- "fax.error"
], - "is_active": true,
- "last_status": "http 200",
- "last_sent_at": "2026-07-03T10:00:00Z",
- "secret": "whsec_1a2b3c..."
}Частичное обновление url/events/is_active; включение сбрасывает счётчик неудач
| webhookId required | integer <int64> Example: 1 ID webhook |
| url | string HTTPS URL доставки (обязателен при создании) |
| events | Array of strings Items Enum: "fax.sent" "fax.error" События подписки (обязательны при создании) |
| is_active | boolean Включить/выключить (только для обновления) |
{- "events": [
- "fax.sent"
], - "is_active": true
}{- "id": 1,
- "events": [
- "fax.sent",
- "fax.error"
], - "is_active": true,
- "last_status": "http 200",
- "last_sent_at": "2026-07-03T10:00:00Z",
- "secret": "whsec_1a2b3c..."
}Синхронно отправляет тестовое событие webhook.test на URL и возвращает результат
| webhookId required | integer <int64> Example: 1 ID webhook |
{- "error": false,
- "delivered": true,
- "status": "http 200"
}Генерирует новый секрет подписи; старый перестаёт действовать немедленно. Ответ содержит новый secret (единственный показ).
| webhookId required | integer <int64> Example: 1 ID webhook |
{- "id": 1,
- "events": [
- "fax.sent",
- "fax.error"
], - "is_active": true,
- "last_status": "http 200",
- "last_sent_at": "2026-07-03T10:00:00Z",
- "secret": "whsec_1a2b3c..."
}Публичная проверка подлинности квитанции — этот URL зашит в QR-код на PDF-квитанции.
Авторизация не требуется; вместо неё обязателен подписанный параметр key.
Подтверждает только факт отправки: в fax пустые file_url и preview_url, cover_page = null.
| faxId required | string <uuid> ID факса (uuid) |
| key required | string Подпись из QR-кода |
{- "valid": true,
- "fax": {
- "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
- "status": "sent",
- "pages": 3,
- "from": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "to": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "cover_page": {
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018, john@example.com",
- "message": "Please find the contract documents attached."
}, - "error": null,
- "error_code": null,
- "scheduled_at": null,
- "created_at": "2026-07-03T10:00:00Z",
- "started_at": "2026-07-03T10:01:00Z",
- "finished_at": "2026-07-03T10:03:00Z"
},
}Список факсов клиента за период + агрегированная статистика
| date_from | string <date> Example: date_from=2026-07-01 Период от (включительно). По умолчанию — 30 дней назад |
| date_to | string <date> Example: date_to=2026-07-31 Период до (включительно). По умолчанию — сегодня |
| status | string Enum: "new" "queued" "in_progress" "sent" "error" Example: status=sent Фильтр по статусу |
| to_number | string Example: to_number=+18772096018 Фильтр по номеру получателя |
| page_num | integer Example: page_num=1 Номер страницы |
| page_size | integer Example: page_size=50 Количество элементов на странице |
{- "statistics": {
- "total": 42,
- "sent": 35,
- "failed": 3,
- "pending": 4,
- "total_pages": 150
}, - "data": [
- {
- "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
- "status": "sent",
- "pages": 3,
- "from": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "to": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "cover_page": {
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018, john@example.com",
- "message": "Please find the contract documents attached."
}, - "error": null,
- "error_code": null,
- "scheduled_at": null,
- "created_at": "2026-07-03T10:00:00Z",
- "started_at": "2026-07-03T10:01:00Z",
- "finished_at": "2026-07-03T10:03:00Z"
}
], - "navigation": {
- "page_size": 50,
- "page_num": 1,
- "page_count": 1
}
}Создание факса-черновика из загруженных вложений (POST /faxes/files).
С send_now: true факс сразу ставится в очередь отправки (требуется положительный баланс).
| to_number required | string Номер факса получателя (E.164). В v1 доступны только США и Канада (NANP, код страны 1) — номер другого направления отклоняется с ошибкой ещё при создании факса. |
| file_ids required | Array of strings <uuid> [ items <uuid > ] ID загруженных вложений ( |
object (FaxCoverPage) | |
| cover_template_id | integer ID шаблона cover page (альтернатива cover_page; поля cover_page перекрывают шаблон) |
| scheduled_at | string <date-time> Отложенная отправка (UTC, будущее время); отправится после вызова send |
| send_now | boolean true — сразу поставить в очередь отправки (эквивалент POST /faxes/{faxId}/send) |
{- "to_number": "+18772096018",
- "file_ids": [
- "c1f876d4-e18b-44b4-b49e-173397394095"
], - "cover_page": {
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018, john@example.com",
- "message": "Please find the contract documents attached."
}, - "cover_template_id": 1,
- "scheduled_at": "2026-07-04T09:00:00Z",
- "send_now": false
}{- "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
- "status": "sent",
- "pages": 3,
- "from": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "to": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "cover_page": {
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018, john@example.com",
- "message": "Please find the contract documents attached."
}, - "error": null,
- "error_code": null,
- "scheduled_at": null,
- "created_at": "2026-07-03T10:00:00Z",
- "started_at": "2026-07-03T10:01:00Z",
- "finished_at": "2026-07-03T10:03:00Z"
}Данные факса по его ID
| faxId required | string <uuid> Example: f47ac10b-58cc-4372-a567-0e02b2c3d479 ID факса (uuid) |
{- "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
- "status": "sent",
- "pages": 3,
- "from": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "to": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "cover_page": {
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018, john@example.com",
- "message": "Please find the contract documents attached."
}, - "error": null,
- "error_code": null,
- "scheduled_at": null,
- "created_at": "2026-07-03T10:00:00Z",
- "started_at": "2026-07-03T10:01:00Z",
- "finished_at": "2026-07-03T10:03:00Z"
}Удаление факса. Факс в очереди или в процессе передачи удалить нельзя — сначала cancel.
| faxId required | string <uuid> ID факса (uuid) |
{- "error": false,
- "message": "Operation completed successfully"
}Постановка факса в очередь отправки. Требуется положительный баланс лицевого счёта.
Отправить можно факс в статусе new или error (повторная отправка после ошибки).
Страницы факса тарифицируются по тарифному плану (1 страница = 1 минута).
| faxId required | string <uuid> ID факса (uuid) |
{- "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
- "status": "sent",
- "pages": 3,
- "from": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "to": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "cover_page": {
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018, john@example.com",
- "message": "Please find the contract documents attached."
}, - "error": null,
- "error_code": null,
- "scheduled_at": null,
- "created_at": "2026-07-03T10:00:00Z",
- "started_at": "2026-07-03T10:01:00Z",
- "finished_at": "2026-07-03T10:03:00Z"
}Отмена запрошенной/запланированной отправки: queued → new (черновик сохраняется).
Факс, уже переданный в шлюз (in_progress), отменить нельзя.
| faxId required | string <uuid> ID факса (uuid) |
{- "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
- "status": "sent",
- "pages": 3,
- "from": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "to": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "cover_page": {
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018, john@example.com",
- "message": "Please find the contract documents attached."
}, - "error": null,
- "error_code": null,
- "scheduled_at": null,
- "created_at": "2026-07-03T10:00:00Z",
- "started_at": "2026-07-03T10:01:00Z",
- "finished_at": "2026-07-03T10:03:00Z"
}Создание черновика-копии факса (те же вложения, получатель и cover page)
| faxId required | string <uuid> ID факса для дублирования (uuid) |
{- "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
- "status": "sent",
- "pages": 3,
- "from": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "to": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "cover_page": {
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018, john@example.com",
- "message": "Please find the contract documents attached."
}, - "error": null,
- "error_code": null,
- "scheduled_at": null,
- "created_at": "2026-07-03T10:00:00Z",
- "started_at": "2026-07-03T10:01:00Z",
- "finished_at": "2026-07-03T10:03:00Z"
}Установка или обновление cover page черновика (status new/error).
Пустое тело {} — убрать cover page. Страницы факса пересчитываются.
| faxId required | string <uuid> ID факса (uuid) |
| sender_name required | string Имя отправителя |
| contact_info | string Контактные данные отправителя |
| message | string Сопроводительный текст |
{- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018, john@example.com",
- "message": "Please find the contract documents attached."
}{- "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
- "status": "sent",
- "pages": 3,
- "from": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "to": {
- "phone_number": "18772096018",
- "station_name": "FaxHub"
}, - "cover_page": {
- "sender_name": "John Smith",
- "contact_info": "+1 877 209 6018, john@example.com",
- "message": "Please find the contract documents attached."
}, - "error": null,
- "error_code": null,
- "scheduled_at": null,
- "created_at": "2026-07-03T10:00:00Z",
- "started_at": "2026-07-03T10:01:00Z",
- "finished_at": "2026-07-03T10:03:00Z"
}PDF «Fax Confirmation Report» с параметрами передачи и QR-кодом публичной проверки подлинности. Доступна после финального статуса (sent/error); генерируется при первом обращении.
| faxId required | string <uuid> ID факса (uuid) |
{
}Получение списка лицевых счетов клиента. Закрытые лицевые счета не возвращаются, если у клиента
есть хотя бы один незакрытый; если незакрытых нет (например, единственный счёт закрыт) —
возвращаются все счета клиента. Закрытый счёт по-прежнему доступен по GET /accounts/{accountId}
и через заголовок X-Account-Id.
| page_num | integer Example: page_num=1 Номер страницы |
| page_size | integer Example: page_size=50 Количество элементов на странице |
{- "data": [
- {
- "id": 137154,
- "status": "active",
- "name": "Основной",
- "id_customer": 3001,
- "currency": {
- "id": 1,
- "name": "Доллар США",
- "code": "USD",
- "symbol": "$"
}, - "monthly_fee": 150,
- "balance_opening": 1351,
- "income": 500,
- "expense": 350.5,
- "balance": 1500.5,
- "limit": -5000,
- "remainder": 6500.5,
- "provider": {
- "name": "ООО \"Артагон\"",
- "full_name": "string",
- "legal_form": "string",
- "inn": "7703814060",
- "kpp": "string",
- "ogrn": "1147746801850",
- "address": "string",
- "type": "russian"
}
}
], - "navigation": {
- "page_size": 50,
- "page_num": 1,
- "page_count": 1
}
}Возвращает данные лицевого счёта по его ID
| accountId required | integer <int64> Example: 137154 ID лицевого счёта |
{- "id": 137154,
- "status": "active",
- "name": "Основной",
- "id_customer": 3001,
- "currency": {
- "id": 1,
- "name": "Доллар США",
- "code": "USD",
- "symbol": "$"
}, - "monthly_fee": 150,
- "balance_opening": 1351,
- "income": 500,
- "expense": 350.5,
- "balance": 1500.5,
- "limit": -5000,
- "remainder": 6500.5,
- "provider": {
- "name": "ООО \"Артагон\"",
- "full_name": "string",
- "legal_form": "string",
- "inn": "7703814060",
- "kpp": "string",
- "ogrn": "1147746801850",
- "address": "string",
- "type": "russian"
}
}Активные и просроченные ключи клиента (отозванные не показываются). Секрет всегда
маскирован — полное значение доступно только у одного ключа через ?reveal=1.
Ключами управляют только из интерактивной сессии ЛК (Authorization: Bearer): запрос с
X-API-Key (любым, в том числе действующим) отклоняется 403, в режиме менеджерского входа
под клиентом — тоже 403.
| page_num | integer Example: page_num=1 Номер страницы |
| page_size | integer Example: page_size=50 Количество элементов на странице (2..200) |
{- "data": [
- {
- "id": 42,
- "key_masked": "42:Xq7L••••••••bX9",
- "api_key": "42:Xq7Lm2Rz9TbV4kPw8NcY3dHf6GsJ1aEuQ5oZbX9",
- "account_id": 100001,
- "active": true,
- "created_at": "2026-08-21T09:15:00Z",
- "last_used_at": "2026-08-21T14:02:11Z",
- "expires_at": null
}
], - "navigation": {
- "page_size": 50,
- "page_num": 1,
- "page_count": 1
}
}Самообслуживание: клиент выпускает себе ключ (бессрочный). Ответ содержит полное значение
api_key — единственный момент, когда его отдают без ?reveal=1. Больше
10 активных ключей на клиента не выпускается — сначала отзовите неиспользуемые.
Только из сессии ЛК (Authorization: Bearer), не в менеджерском входе. Выпуск пишется в журнал
авторизации клиента (событие apikey_created: учётка, сессия, IP, маска ключа).
| account_bound | boolean Default: false true — привязать ключ к эффективному лицевому счёту запроса (модель интеграций:
заголовок |
{- "account_bound": true
}{- "id": 42,
- "key_masked": "42:Xq7L••••••••bX9",
- "api_key": "42:Xq7Lm2Rz9TbV4kPw8NcY3dHf6GsJ1aEuQ5oZbX9",
- "account_id": 100001,
- "active": true,
- "created_at": "2026-08-21T09:15:00Z",
- "last_used_at": "2026-08-21T14:02:11Z",
- "expires_at": null
}Один ключ клиента. По умолчанию секрет маскирован; reveal=1 возвращает полное значение
в поле api_key (кнопка «Показать» в ЛК — секрет хранится обратимо, поэтому доступен
и после создания). Чужой или отозванный ключ — 404.
Только из сессии ЛК (Authorization: Bearer), не в менеджерском входе. Раскрытие (reveal=1)
пишется в журнал авторизации клиента (событие apikey_revealed: учётка, сессия, IP, маска ключа).
| keyId required | integer Example: 42 ID ключа |
| reveal | integer Enum: 0 1 Example: reveal=1 1 — вернуть полное значение ключа в поле api_key |
{- "id": 42,
- "key_masked": "42:Xq7L••••••••bX9",
- "api_key": "42:Xq7Lm2Rz9TbV4kPw8NcY3dHf6GsJ1aEuQ5oZbX9",
- "account_id": 100001,
- "active": true,
- "created_at": "2026-08-21T09:15:00Z",
- "last_used_at": "2026-08-21T14:02:11Z",
- "expires_at": null
}Ключ немедленно перестаёт авторизовывать запросы и пропадает из списка. Действие необратимо — восстановить отозванный ключ нельзя, нужно выпустить новый. Отзыв, как выпуск и раскрытие, фиксируется в журнале доступа клиента (видно менеджеру в карточке клиента).
Только из сессии ЛК (Authorization: Bearer), не в менеджерском входе.
| keyId required | integer Example: 42 ID ключа |
{- "error": false,
- "message": "Operation completed successfully"
}