Программное заполнение PDF форм: автоматизация через API на Python, JavaScript и cURL

Зачем автоматизировать заполнение PDF форм

Интерактивные PDF формы повсюду: налоговые декларации, банковские анкеты, заявления в госорганы, формы статистической отчётности, опросники для клиентов. Когда таких документов десятки или сотни — ручное заполнение становится узким местом в любом рабочем процессе.

Типичные сценарии, где нужна автоматизация заполнения PDF формы:

CRM и ERP-системы — автоматическая генерация заявлений, договоров и актов по данным клиента.
Порталы самообслуживания — пользователь вводит данные в веб-форму, а на выходе получает готовый PDF.
Интеграции с госсервисами — периодическая отправка форм отчётности с актуальными данными.
HR-автоматизация — массовое формирование трудовых договоров, заявлений и приказов.

В каждом из этих случаев программное заполнение PDF формы через API экономит часы ручного труда и исключает ошибки.

Обзор существующих решений

Python-библиотеки: PyPDF2, pdfrw, pypdf, reportlab

Библиотеки вроде pypdf или pdfrw позволяют работать с PDF на низком уровне прямо в Python-коде. Звучит удобно, но на практике возникают серьёзные проблемы:

Хрупкость. PDF — сложный бинарный формат. Каждая библиотека поддерживает лишь подмножество спецификации, и конкретный файл может обрабатываться некорректно.
Проблемы с кодировками. Кириллица в полях форм — частая головная боль. Нестандартные шрифты или нестандартное кодирование поля могут сломать результат.
Отсутствие гарантий воспроизводимости. Заполненная форма может выглядеть иначе при открытии в разных PDF-ридерах.
Нет готовой инфраструктуры. Хранение файлов, очереди задач, мониторинг — всё нужно строить самостоятельно.

Adobe Acrobat / платные десктопные инструменты

Профессиональные инструменты Adobe решают задачу качественно, но совершенно не приспособлены для программной интеграции в веб-приложение или CI/CD-пайплайн.

Self-hosted решения (LibreOffice, PDFtk)

Можно развернуть LibreOffice в headless-режиме или использовать PDFtk Server. Это бесплатно, но требует администрирования сервера, регулярных обновлений и не масштабируется без дополнительной работы.

Вывод

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

Что предлагает Bulldoc

Bulldoc — это специализированный SaaS-сервис для генерации и обработки печатных документов, разработанный с прицелом на разработчиков.

Простое и удобное REST API

Весь функционал доступен через стандартное RESTful API с поддержкой спецификации OpenAPI. Это означает:

Можно сгенерировать клиентскую библиотеку для любого языка программирования с помощью OpenAPI Generator.
Поддержка синхронных и асинхронных запросов (подробнее ниже).

Гибкое ценообразование

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

Программное заполнению PDF форм через API

Шаг 1. Регистрация в сервисе

Зарегистрируйтесь в сервисе и создайте аккаунт. Для начала работы достаточно email и пароля.

Шаг 2. Создание API-ключа

В личном кабинете перейдите в раздел настроек и создайте новый API-ключ. Сохраните его — он понадобится для аутентификации всех запросов к API.

API-ключ передаётся в заголовке каждого запроса:

Authorization: Bearer <ваш_api_ключ>

Шаг 3. Загрузка файла формы через веб-интерфейс

Прежде чем заполнять форму через API, её нужно загрузить в сервис. Bulldoc принимает интерактивные PDF формы (с заполняемыми полями):

В личном кабинете перейдите в раздел «Формы».
Загрузите ваш PDF-файл с интерактивными полями.
После загрузки сервис покажет formId — уникальный идентификатор формы. Запишите его, он используется в API-запросах.

Совет: Убедитесь, что в вашем PDF действительно есть интерактивные поля (AcroForm). Если форма представляет собой просто отсканированный документ без полей, её нужно предварительно подготовить в Adobe Acrobat или аналогичном инструменте.

Шаг 4. Синхронные и асинхронные запросы

Bulldoc API поддерживает два режима обработки:

Асинхронный (по умолчанию, sync: false) — запрос возвращается немедленно с taskId. Документ обрабатывается в фоне. Статус задачи можно:

опрашивать через GET /v1/tasks/{id},
получать через вебхук, когда задача завершится.

Этот режим подходит для массовой генерации документов или когда не нужен мгновенный ответ.

Синхронный (sync: true) — соединение удерживается до завершения обработки, и в ответе сразу возвращается готовый документ с URL для скачивания. Удобен для интерактивных сценариев, когда пользователь ждёт результата в режиме реального времени.

Шаг 5. Примеры запросов для заполнения PDF формы

Эндпоинт для заполнения форм: POST https://api.bulldoc.dev/v1/pdf/fill

Тело запроса:

formId — идентификатор загруженной формы
data — объект с данными для заполнения полей (ключи соответствуют именам полей в форме)
sync — true для синхронного режима (опционально)

cURL

curl -X POST https://api.bulldoc.dev/v1/pdf/fill \
  -H "Authorization: Bearer <ваш_api_ключ>" \
  -H "Content-Type: application/json" \
  -d '{
    "formId": "ваш_form_id",
    "sync": true,
    "description": "Анкета клиента Иванов",
    "data": {
      "full_name": "Иванов Иван Иванович",
      "birth_date": "01.01.1990",
      "passport_series": "4510",
      "passport_number": "123456",
      "address": "г. Москва, ул. Примерная, д. 1, кв. 10",
      "phone": "+7 (999) 123-45-67",
      "agree": true
    }
  }'

В синхронном режиме ответ придёт сразу и будет содержать URL для скачивания заполненного PDF.

Python — заполнить PDF форму

import requests

API_KEY = "ваш_api_ключ"
FORM_ID = "ваш_form_id"

url = "https://api.bulldoc.dev/v1/pdf/fill"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
payload = {
    "formId": FORM_ID,
    "sync": True,
    "description": "Анкета клиента",
    "data": {
        "full_name": "Иванов Иван Иванович",
        "birth_date": "01.01.1990",
        "passport_series": "4510",
        "passport_number": "123456",
        "address": "г. Москва, ул. Примерная, д. 1, кв. 10",
        "phone": "+7 (999) 123-45-67",
        "agree": True,
    },
}

response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()

task = response.json()

# В синхронном режиме документ уже готов
document_url = task["documents"][0]["url"]
print(f"Документ готов: {document_url}")

# Скачиваем файл
pdf_response = requests.get(document_url)
with open("filled_form.pdf", "wb") as f:
    f.write(pdf_response.content)
print("Файл сохранён: filled_form.pdf")

Для асинхронного заполнения PDF формы на Python — опустите sync или установите sync: False, затем опрашивайте статус:

import time

payload["sync"] = False
response = requests.post(url, json=payload, headers=headers)
task = response.json()
task_id = task["id"]

# Ожидаем завершения
while True:
    status_response = requests.get(
        f"https://api.bulldoc.dev/v1/tasks/{task_id}",
        headers=headers,
    )
    task = status_response.json()
    if task["status"] == "finished":
        document_url = task["documents"][0]["url"]
        print(f"Готово: {document_url}")
        break
    elif task["status"] == "failed":
        print(f"Ошибка: {task.get('errorMessage')}")
        break
    time.sleep(1)

JavaScript / Node.js — заполнить PDF форму

// Требуется: Node.js 18+ (встроенный fetch) или установите node-fetch

const API_KEY = "ваш_api_ключ";
const FORM_ID = "ваш_form_id";

async function fillPdfForm(formData) {
  const response = await fetch("https://api.bulldoc.dev/v1/pdf/fill", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      formId: FORM_ID,
      sync: true,
      description: "Анкета клиента",
      data: formData,
    }),
  });

  if (!response.ok) {
    throw new Error(`Ошибка API: ${response.status} ${response.statusText}`);
  }

  const task = await response.json();
  // В синхронном режиме документ уже готов
  const documentUrl = task.documents[0].url;
  console.log("Документ готов:", documentUrl);
  return documentUrl;
}

// Пример использования
fillPdfForm({
  full_name: "Иванов Иван Иванович",
  birth_date: "01.01.1990",
  passport_series: "4510",
  passport_number: "123456",
  address: "г. Москва, ул. Примерная, д. 1, кв. 10",
  phone: "+7 (999) 123-45-67",
  agree: true,
}).catch(console.error);

Для асинхронного режима на Node.js — полезно использовать вебхуки. Настройте вебхук в личном кабинете или через API (POST /v1/webhooks), и Bulldoc пришлёт уведомление на ваш URL, когда документ будет готов.

Итог

Программное заполнение PDF форм через Bulldoc API — это простой и надёжный способ автоматизировать рутинные задачи с документами. Ключевые преимущества:

Нет необходимости разбираться в низкоуровневой структуре PDF.
Работает с любым языком программирования через стандартный REST API.
Гибкий выбор между синхронной и асинхронной обработкой.
Прозрачная тарификация без обязательных подписок.

Зарегистрируйтесь на bulldoc.dev, загрузите вашу форму и сделайте первый API-запрос — это займёт не больше 10 минут.