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)
Основной эндпоинт для распознавания документов. Отправьте один или несколько файлов и получите структурированные данные.
/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);
Ответ
{
"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
}
Баланс
Получение текущего баланса аккаунта.
/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'],
]);
Ответ
{
"balance_kopecks": 29900,
"balance_rub": 299.0
}
Статистика использования
Получение статистики использования API за указанный период.
/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'],
]);
Ответ
{
"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 для надёжной интеграции.
Поддерживаемые форматы
Список поддерживаемых форматов файлов и ограничения.
application/pdf
Многостраничные документы. Каждая страница = 1 единица тарификации.
JPEG / JPG
image/jpeg
Фотографии и сканы документов. 1 изображение = 1 единица.
PNG
image/png
Изображения без потери качества. 1 изображение = 1 единица.
Ограничения
- Макс. размер файла: 25 MB
- Макс. файлов в запросе: 10
Готовы начать?
Зарегистрируйтесь и получите бесплатные страницы для тестирования API.