Первый вызов API

Typizer принимает документ и схему (JSON Schema) и отдаёт структурированные данные одним вызовом — без сохранения типизатора. Этот путь короче всего для первой проверки; для повторного использования схемы см. раздел ниже «Сохранить типизатор».

1. Получить ключСкопировать ссылку

В кабинете откройте раздел «Ключи API» и создайте ключ со скоупом runs:write. Ключ показывается один раз — сохраните его, например в переменную окружения:

export TYPIZER_API_KEY="tz_live_…"

Подробнее о скоупах — на странице «Ключи API».

2. Вызвать POST /v1/extractСкопировать ссылку

Запрос — multipart/form-data: файл (file), схема (schema, JSON-объект как строка) и заголовок Idempotency-Key, чтобы случайный повтор запроса не тарифицировался дважды (подробнее — «Обработка ошибок и повторов»). Генерируйте новый Idempotency-Key на каждый вызов: повтор с тем же ключом и теми же аргументами в течение 24 часов вернёт тот же прогон, а с другими аргументами — ошибку 409 idempotency_conflict.

#!/bin/sh
# Первый вызов API: POST /v1/extract с разовой схемой, без сохранения типизатора.
# Ключ создаётся в кабинете (раздел «Ключи API»).

curl https://api.typizer.ru/v1/extract \
  -H "Authorization: Bearer $TYPIZER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F file=@invoice.pdf \
  -F schema='{
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string" },
      "total": { "type": "number" },
      "inn": { "type": "string", "x-typizer-check": "inn" }
    },
    "required": ["invoice_number", "total"]
  }'

3. Разобрать ответСкопировать ссылку

Ответ — объект Run. Основные поля:

• status — succeeded, failed, queued или processing (если wait не задан или истёк);
• output — результат в выбранном формате (по умолчанию JSON);
• fields — те же данные с метаданными на поле: статус ok / warn / missing, источники в документе. Подробнее — «Проверки полей»;
• pages — объект { physical, billed }: физические страницы документа и страницы, фактически списанные с баланса (они расходятся в режиме precise — множитель, подробнее «Тарификация страниц»).

4. Сохранить типизаторСкопировать ссылку

Разовая схема в каждом запросе быстро устаревает. Схему стоит сохранить один раз как типизатор — POST /v1/typizers — и затем просто ссылаться на него по id:

curl https://api.typizer.ru/v1/typizers \
  -H "Authorization: Bearer $TYPIZER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Счета поставщиков",
    "schema": {
      "type": "object",
      "properties": {
        "invoice_number": { "type": "string" },
        "total": { "type": "number" },
        "inn": { "type": "string", "x-typizer-check": "inn" }
      },
      "required": ["invoice_number", "total"]
    }
  }'

Затем каждый следующий документ — короткий вызов с ?wait=60, который ждёт результат синхронно до 60 секунд (после — опрос GET /v1/runs/{id} или вебхук, см. «Получить результат»):

curl "https://api.typizer.ru/v1/typizers/$TYPIZER_ID/runs?wait=60" \
  -H "Authorization: Bearer $TYPIZER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F file=@invoice.pdf

Что дальшеСкопировать ссылку

• SDK для TypeScript и Python вместо прямых вызовов fetch/requests.
• Приём вебхуков вместо ожидания ответа.
• Пакетная обработка для много документов сразу.