API Документация

Руководство по интеграции с PDFGpt OCR API

Введение

PDFGpt OCR API позволяет распознавать бухгалтерские и юридические документы: счета-фактуры, акты, УПД, товарные накладные и другие. API извлекает структурированные данные из сканов и фотографий документов с высокой точностью.

Base URL

https://pdfgpt.ru/api/v1

Формат ответов

application/json

Rate Limit

60 запросов / минуту

Кодировка

UTF-8

Аутентификация

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

Заголовок
Authorization: Bearer aix_your_api_key_here

Безопасность ключей

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

Распознавание (OCR)

Основной эндпоинт для распознавания документов. Отправьте один или несколько файлов и получите структурированные данные.

POST /api/v1/ocr

Заголовки

Заголовок Значение
Authorization Bearer aix_your_api_key_here
Content-Type multipart/form-data

Параметры

Параметр Тип Обязателен Описание
files[] file Да Файлы для распознавания (PDF, JPG, PNG). До 10 файлов, до 25MB каждый

Примеры запроса

curl -X POST https://pdfgpt.ru/api/v1/ocr \
  -H "Authorization: Bearer aix_your_api_key_here" \
  -F "files[]=@invoice.pdf" \
  -F "files[]=@receipt.jpg"
import requests

url = "https://pdfgpt.ru/api/v1/ocr"
headers = {"Authorization": "Bearer aix_your_api_key_here"}

files = [
    ("files[]", ("invoice.pdf", open("invoice.pdf", "rb"), "application/pdf")),
    ("files[]", ("receipt.jpg", open("receipt.jpg", "rb"), "image/jpeg")),
]

response = requests.post(url, headers=headers, files=files)
data = response.json()

for doc in data["documents"]:
    print(f"{doc['filename']}: {doc['result']['document_type']}")
const formData = new FormData();
formData.append('files[]', fileInput.files[0]);

const response = await fetch('https://pdfgpt.ru/api/v1/ocr', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer aix_your_api_key_here',
  },
  body: formData,
});

const data = await response.json();
console.log(data.documents);
$client = new \GuzzleHttp\Client();

$response = $client->post('https://pdfgpt.ru/api/v1/ocr', [
    'headers' => [
        'Authorization' => 'Bearer aix_your_api_key_here',
    ],
    'multipart' => [
        [
            'name'     => 'files[]',
            'contents' => fopen('invoice.pdf', 'r'),
            'filename' => 'invoice.pdf',
        ],
    ],
]);

$data = json_decode($response->getBody(), true);

Ответ

200 OK
{
  "status": "success",
  "documents": [
    {
      "filename": "invoice.pdf",
      "result": {
        "document_type": "Счёт-фактура",
        "number": "СФ-00123",
        "date": "15.03.2026",
        "seller": {
          "name": "ООО \"Поставщик\"",
          "inn": "7712345678",
          "kpp": "771201001"
        },
        "buyer": {
          "name": "ООО \"Покупатель\"",
          "inn": "7798765432"
        },
        "items": [
          {
            "name": "Товар 1",
            "quantity": 10,
            "unit": "шт",
            "price": 100.00,
            "total": 1000.00,
            "vat_rate": "20%",
            "vat_amount": 200.00,
            "total_with_vat": 1200.00
          }
        ],
        "totals": {
          "subtotal": 1000.00,
          "vat": 200.00,
          "total": 1200.00
        }
      }
    }
  ],
  "pages_processed": 1,
  "cost_rub": 1.0,
  "balance_rub": 299.0
}

Баланс

Получение текущего баланса аккаунта.

GET /api/v1/balance
curl https://pdfgpt.ru/api/v1/balance \
  -H "Authorization: Bearer aix_your_api_key_here"
response = requests.get(
    "https://pdfgpt.ru/api/v1/balance",
    headers={"Authorization": "Bearer aix_your_api_key_here"}
)
print(response.json())
const response = await fetch('https://pdfgpt.ru/api/v1/balance', {
  headers: { 'Authorization': 'Bearer aix_your_api_key_here' },
});
const data = await response.json();
$response = $client->get('https://pdfgpt.ru/api/v1/balance', [
    'headers' => ['Authorization' => 'Bearer aix_your_api_key_here'],
]);

Ответ

200 OK
{
  "balance_kopecks": 29900,
  "balance_rub": 299.0
}

Статистика использования

Получение статистики использования API за указанный период.

GET /api/v1/usage

Query-параметры

Параметр Тип Обязателен Описание
from string Нет Начало периода (YYYY-MM-DD). По умолчанию: начало текущего месяца
to string Нет Конец периода (YYYY-MM-DD). По умолчанию: сегодня
curl "https://pdfgpt.ru/api/v1/usage?from=2026-03-01&to=2026-03-27" \
  -H "Authorization: Bearer aix_your_api_key_here"
response = requests.get(
    "https://pdfgpt.ru/api/v1/usage",
    headers={"Authorization": "Bearer aix_your_api_key_here"},
    params={"from": "2026-03-01", "to": "2026-03-27"}
)
const params = new URLSearchParams({ from: '2026-03-01', to: '2026-03-27' });
const response = await fetch(`https://pdfgpt.ru/api/v1/usage?${params}`, {
  headers: { 'Authorization': 'Bearer aix_your_api_key_here' },
});
$response = $client->get('https://pdfgpt.ru/api/v1/usage', [
    'headers' => ['Authorization' => 'Bearer aix_your_api_key_here'],
    'query'   => ['from' => '2026-03-01', 'to' => '2026-03-27'],
]);

Ответ

200 OK
{
  "period": {
    "from": "2026-03-01",
    "to": "2026-03-27"
  },
  "total_requests": 150,
  "total_pages": 423,
  "total_cost_rub": 423.0,
  "by_status": {
    "success": 145,
    "error": 5
  }
}

Коды ошибок

API возвращает стандартные HTTP-коды статуса. В случае ошибки тело ответа содержит описание проблемы.

HTTP код Код ошибки Описание
401 INVALID_API_KEY Неверный или отсутствующий API-ключ
402 INSUFFICIENT_BALANCE Недостаточно средств на балансе
413 FILE_TOO_LARGE Файл превышает 25MB
422 VALIDATION_ERROR Неверный формат файла или отсутствуют обязательные поля
429 RATE_LIMIT_EXCEEDED Превышен лимит запросов (60/мин)
500 INTERNAL_ERROR Внутренняя ошибка сервера
502 OCR_BACKEND_ERROR Ошибка сервиса распознавания

Формат ошибки

{
  "status": "error",
  "error": "Описание ошибки",
  "code": "ERROR_CODE"
}

Rate Limits

Ограничения на количество запросов зависят от типа доступа.

Тип доступа Лимит Описание
API (с ключом) 60 запросов/мин Стандартный лимит для авторизованных запросов
Демо (без регистрации) 5 запросов/час Ограниченный доступ для тестирования

Заголовки в ответе

Каждый ответ API содержит заголовки с информацией о текущих лимитах:

Заголовок Описание
X-RateLimit-Limit Максимальное количество запросов в окне
X-RateLimit-Remaining Оставшееся количество запросов в текущем окне

Рекомендация

При получении ответа с кодом 429 подождите 60 секунд перед следующим запросом. Реализуйте экспоненциальный backoff для надёжной интеграции.

Поддерживаемые форматы

Список поддерживаемых форматов файлов и ограничения.

PDF

application/pdf

Многостраничные документы. Каждая страница = 1 единица тарификации.

JPEG / JPG

image/jpeg

Фотографии и сканы документов. 1 изображение = 1 единица.

PNG

image/png

Изображения без потери качества. 1 изображение = 1 единица.

Ограничения

  • Макс. размер файла: 25 MB
  • Макс. файлов в запросе: 10

Готовы начать?

Зарегистрируйтесь и получите бесплатные страницы для тестирования API.