API для Codex-публикации документов

Скачать helper

Эти файлы публичные и не содержат рабочего API-ключа. Ключ нужно добавить локально отдельным файлом или через переменную окружения.

Быстрый старт с нуля

1. Скачай helper выше или скопируй готовый codex_document_sync.py. Путь может быть любым: дальше он обозначается как <helper>.
2. Создай локальный файл ключа рядом с helper-проектом или укажи путь через ONEDESK_API_KEY_FILE. Формат файла ниже; настоящий ключ не показывать в ответах.
3. Проверь, что helper запускается: python <helper> ping.
4. Если ping вернул ok=true и documents_schema_ready=true, можно смотреть список карточек, читать карточки, скачивать файлы, резервировать номера, публиковать и делать patch-metadata.

source_code=codex_docs
api_base=https://za.a-rial.ru
api_key=ВСТАВИТЬ_СЮДА_API_КЛЮЧ

Endpoint: ping

Безопасная проверка подключения. Не создает резерв, не публикует файлы и не меняет карточки.

POST /api/v1/documents/ping
{
  "source_code": "codex_docs"
}

Успешный ответ содержит ok=true, documents_schema_ready, список типов документов, время сервера и лимиты загрузки.

{
  "ok": true,
  "request_id": "req_20260704130303_ab12cd34ef56ab78",
  "service": "onedesk_documents",
  "source_code": "codex_docs",
  "documents_schema_ready": true,
  "document_types": ["kp", "invoice", "closing"],
  "server_time": "2026-07-04 13:03:03"
}

Endpoint: list

Возвращает список карточек текущего source_code с фильтрами и пагинацией. По умолчанию файлы и события не включаются, чтобы список был легким.

POST /api/v1/documents/list
{
  "source_code": "codex_docs",
  "document_type": "kp",
  "q": "client",
  "status": "issued",
  "date_from": "2026-07-01",
  "date_to": "2026-07-04",
  "page": 1,
  "per_page": 25,
  "include_files": false
}

{
  "ok": true,
  "request_id": "req_...",
  "total": 41,
  "page": 1,
  "per_page": 25,
  "pages": 2,
  "documents": [
    {
      "document_uid": "KP-client_subject_20260704",
      "document_type": "kp",
      "local_id": "client_subject_20260704",
      "document_no": "КП-20260704-01",
      "title": "КП для клиента",
      "client_name": "ООО Клиент",
      "files_count": 6,
      "files_total_bytes": 1234567,
      "card_url": "https://za.a-rial.ru/documents/KP-client_subject_20260704"
    }
  ]
}

Endpoint: get

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

POST /api/v1/documents/get
{
  "source_code": "codex_docs",
  "document_uid": "KP-client_subject_20260704",
  "include_files": true,
  "include_events": false
}

{
  "ok": true,
  "request_id": "req_...",
  "document": {
    "document_uid": "KP-client_subject_20260704",
    "document_type": "kp",
    "local_id": "client_subject_20260704",
    "document_no": "КП-20260704-01",
    "metadata": {},
    "files": [
      {
        "id": 123,
        "label": "КП.pdf",
        "original_name": "КП.pdf",
        "relative_path": "КП.pdf",
        "mime_type": "application/pdf",
        "size_bytes": 123456,
        "sha256": "...",
        "preview_kind": "pdf"
      }
    ]
  }
}

Endpoint: download-file

Скачивает конкретный файл документа по file_id. Ответ бинарный; request_id возвращается в заголовке X-Request-ID.

POST /api/v1/documents/download-file
{
  "source_code": "codex_docs",
  "document_uid": "KP-client_subject_20260704",
  "file_id": 123
}

Если файл найден и доступен этому source_code, сервер отдает Content-Type, Content-Disposition, X-OneDesk-SHA256 и содержимое файла. Для ошибок ответ остается JSON.

Endpoint: reserve-number

Резервирует номер перед выпуском финального комплекта и ловит гонки между несколькими Codex.

POST /api/v1/documents/reserve-number
{
  "source_code": "codex_docs",
  "document_type": "kp",
  "document_no": "КП-20260704-01",
  "local_id": "client_subject_20260704",
  "ttl_seconds": 3600
}

Успешный ответ содержит reservation_token. Его можно передать в publish, но обычно helper делает это сам.

{
  "ok": true,
  "request_id": "req_...",
  "reserved": true,
  "document_type": "kp",
  "document_no": "КП-20260704-01",
  "local_id": "client_subject_20260704",
  "reservation_token": "...",
  "expires_at": "2026-07-04 14:03:03"
}

Endpoint: publish

Создает или обновляет карточку документа и загружает финальные файлы. Повторная публикация идемпотентна по связке source_code + document_type + local_id.

POST /api/v1/documents/publish
{
  "source_code": "codex_docs",
  "reservation_token": "...",
  "document": {
    "document_type": "kp",
    "local_id": "client_subject_20260704",
    "document_no": "КП-20260704-01",
    "title": "КП для клиента",
    "client_name": "ООО Клиент",
    "object_title": "Объект / предмет",
    "amount_text": "7 500 руб. с НДС 5%",
    "status": "issued",
    "workspace_path": "D:\\Загрузки\\10_codex_Kp\\outputs\\client_subject_20260704",
    "metadata": {
      "contact_name": "Иван Иванов",
      "contact_email": "client@example.ru"
    }
  },
  "files": [
    {
      "group_code": "final",
      "label": "КП.pdf",
      "original_name": "КП.pdf",
      "relative_path": "КП.pdf",
      "mime": "application/pdf",
      "size_bytes": 123456,
      "sha256": "optional-client-side-sha256",
      "content_base64": "..."
    }
  ]
}

{
  "ok": true,
  "request_id": "req_...",
  "created": true,
  "document_uid": "KP-client_subject_20260704",
  "document_no": "КП-20260704-01",
  "local_id": "client_subject_20260704",
  "card_url": "https://za.a-rial.ru/documents/KP-client_subject_20260704",
  "files": {
    "count": 6,
    "total_bytes": 1234567,
    "largest_bytes": 345678
  }
}

Endpoint: patch-metadata

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

POST /api/v1/documents/patch-metadata
{
  "source_code": "codex_docs",
  "document_uid": "KP-client_subject_20260704",
  "metadata_patch": {
    "contact_name": "Иван Иванов",
    "contact_email": "client@example.ru",
    "contact_source": "README.md"
  },
  "preserve_dates": true,
  "dry_run": true
}

Сначала запускать с dry_run=true. Если ответ успешный, повторить без dry_run.

{
  "ok": true,
  "request_id": "req_...",
  "dry_run": true,
  "document_uid": "KP-client_subject_20260704",
  "metadata_keys": ["contact_name", "contact_email", "contact_source"],
  "preserve_dates": true,
  "card_url": "https://za.a-rial.ru/documents/KP-client_subject_20260704"
}

Идемпотентность и retry

• publish идемпотентен по связке source_code + document_type + local_id.
• Повтор с тем же local_id обновляет существующую карточку и заменяет/дополняет файловый комплект согласно payload helper.
• Если тот же document_no уже опубликован другим local_id, API возвращает 409 number_taken.
• Если номер зарезервирован другим выпуском, API возвращает 409 number_reserved.
• После успешного publish использованный резерв помечается consumed. Истекший или несовпадающий токен дает reservation_invalid.
• При сетевой ошибке helper сохраняет JSON payload в локальную очередь; retry переотправляет payload и при необходимости обновляет reservation token.

HTTP-статусы и ошибки

Каждый JSON-ответ содержит request_id; тот же идентификатор отдается в заголовке X-Request-ID. При разборе ошибок сохранять его в сообщении пользователю.

{
  "ok": false,
  "error": "number_taken",
  "request_id": "req_...",
  "document_uid": "KP-existing_document"
}

Формат файлов

Текущий v1-контракт принимает файлы внутри JSON как content_base64. Это удобно для Codex/helper и небольших комплектов; multipart/chunk upload пока не используется.

{
  "group_code": "final",
  "label": "КП.pdf",
  "original_name": "КП.pdf",
  "relative_path": "КП.pdf",
  "mime": "application/pdf",
  "size_bytes": 123456,
  "sha256": "optional-client-side-sha256",
  "content_base64": "..."
}

Сервер сохраняет собственный sha256, размер и MIME. Клиентские size_bytes/sha256 можно передавать как ожидаемые значения для диагностики, но источник истины - серверная проверка сохраненного файла.

Правила безопасности

Не делать прямые SQL-правки, удаление карточек, чистку очереди и повторную отправку чужих payload без явного разрешения пользователя.