Реализация Invoicing (генерация счетов) для SaaS-приложения

Типичная ситуация: B2B SaaS-продукт растет на 20% в месяц, но выставление счетов всё ещё происходит вручную. Менеджеры тратят до 15 минут на каждый счет — копируют данные, вставляют в Word, теряют суммы, ошибаются в ИНН. Клиенты жалуются на задержки в 2-3 дня, бухгалтерия тратит часы на сверку. Автоматизация инвойсинга сокращает этот процесс до 30 секунд — в 30 раз быстрее, экономя до 10 000 долларов в год для компании с 500 счетами ежемесячно. Мы реализуем полный цикл: от настройки Stripe до генерации кастомных PDF с хранением в S3 и синхронизацией с 1С.

В SaaS-бизнесе с сотнями клиентов и подписок в разных валютах ручное выставление счетов становится узким местом. Каждая ошибка в реквизитах или налогах может стоить тысяч долларов. Мы видели проекты, где 15% счетов содержали ошибки — после автоматизации этот показатель упал до 0.5%. «Автоматизация инвойсинга сэкономила нам 40 часов в месяц и сократила просрочки на 30%» — финансовый директор одного из клиентов. Правильная настройка Stripe Invoicing и генерация собственных PDF позволяют не только ускорить процесс, но и повысить доверие клиентов: счета выглядят профессионально и содержат корректные данные.

Наша команда реализовала инвойсинг для 30+ SaaS-проектов: от стартапов до enterprise. Мы знаем все подводные камни: от tax ID до временных зон. Если вы столкнулись с ростом объема счетов — получите консультацию инженера.

Почему автоматизация инвойсинга критична для SaaS?

С каждым новым клиентом растет нагрузка на бухгалтерию. Ошибки в реквизитах, налогах и валютах приводят к задержкам оплат и потере доверия. Автоматизированный инвойсинг исключает человеческие ошибки при формировании счетов, ускоряет выставление до секунд после оплаты подписки, поддерживает разные валюты (USD, EUR, RUB) и налоговые режимы (НДС, VAT, US sales tax), а также генерирует PDF-счета с кастомным брендингом для каждого клиента. Интеграция с бухгалтерией позволяет автоматически синхронизировать данные с 1С и другими системами.

Проблемы, которые решаем

1. Налоговая неоднозначность — Stripe поддерживает tax ID (ИНН для RU, VAT для EU), но требует правильной конфигурации. Мы настраиваем автоматическое определение tax rate по стране клиента.
2. Кастомный брендинг — стандартные счета Stripe редко устраивают клиентов. Мы создаем собственные PDF-шаблоны через @react-pdf/renderer, полностью контролируя дизайн и расположение полей.
3. Хранение и доставка — PDF-счета должны быть доступны из личного кабинета и отправляться на email. Используем S3 с предподписанными URL и SendGrid для отправки.
4. Синхронизация с бухгалтерией — через webhook Stripe или собственную генерацию передаем данные в 1С и другие системы.

Как гарантировать точность налогов в инвойсах?

Налоговые правила различаются по странам и штатам. Stripe позволяет задавать tax rates глобально, но для сложных сценариев (например, EU Intra-community VAT) требуется дополнительная логика. Мы используем Stripe Tax API для автоматического расчета налогов на основе адреса клиента и типа продукта. В случае собственных PDF, налоги вычисляются на стороне сервера с использованием проверенных библиотек. Тестирование на реальных сценариях (песочница Stripe) гарантирует, что каждая транзакция пройдет без блокировок.

Как мы реализовали инвойсинг для SaaS-стартапа?

Клиент — американский SaaS для управления фрилансерами. Требовалось выставлять счета в USD и EUR, с логотипом клиента, сроками оплаты 15/30 дней, и автоматически сохранять PDF в S3. Выбрали гибрид: подписки через Stripe Invoicing, а генерацию PDF — через React PDF с собственным компонентом.

// Настройка Customer с реквизитами для инвойсов
const customer = await stripe.customers.create({
  email: '[email protected]',
  name: 'Acme Corp',
  address: {
    line1: 'ул. Ленина, 1',
    city: 'Москва',
    country: 'RU',
    postal_code: '101000',
  },
  tax_ids: [{
    type: 'ru_inn',
    value: '7727563778',
  }],
  metadata: { tenantId },
});

// Кастомный брендинг через Stripe Dashboard:
// Settings → Branding → Logo, colors, footer text

// Обновление реквизитов клиентом
export async function updateBillingDetails(
  tenantId: string,
  data: BillingDetailsInput
): Promise<void> {
  const subscription = await db.subscription.findUnique({
    where: { tenantId }
  });

  await stripe.customers.update(subscription!.stripeCustomerId, {
    name: data.companyName,
    email: data.billingEmail,
    address: {
      line1: data.address,
      city: data.city,
      country: data.country,
      postal_code: data.postalCode,
    },
  });

  // Tax ID (ИНН для RU, VAT для EU)
  if (data.taxId) {
    // Сначала удаляем старые tax IDs
    const existingCustomer = await stripe.customers.retrieve(
      subscription!.stripeCustomerId,
      { expand: ['tax_ids'] }
    ) as Stripe.Customer;

    for (const taxId of (existingCustomer.tax_ids as Stripe.ApiList<Stripe.TaxId>).data) {
      await stripe.customers.deleteTaxId(subscription!.stripeCustomerId, taxId.id);
    }

    // Добавляем новый
    await stripe.customers.createTaxId(subscription!.stripeCustomerId, {
      type: data.taxIdType as Stripe.TaxIdCreateParams.Type,
      value: data.taxId,
    });
  }
}

Генерация PDF через React PDF с кэшированием в S3: первый запрос генерирует и сохраняет, последующие — отдают готовый файл. Это снижает нагрузку и ускоряет отдачу.

// npm install @react-pdf/renderer
import { pdf } from '@react-pdf/renderer';
import { InvoicePDF } from '@/components/pdf/InvoicePDF';

export async function generateInvoicePDF(invoiceId: string): Promise<Buffer> {
  const invoice = await db.invoice.findUnique({
    where: { id: invoiceId },
    include: {
      tenant: { include: { branding: true } },
      lineItems: true,
    }
  });

  const pdfStream = await pdf(
    <InvoicePDF invoice={invoice!} />
  ).toBuffer();

  return pdfStream;
}

// Сохраняем в S3 и возвращаем URL
export async function getInvoicePdfUrl(invoiceId: string): Promise<string> {
  const key = `invoices/${invoiceId}.pdf`;

  // Проверяем, уже создан ли
  try {
    await s3.headObject({ Bucket: process.env.AWS_BUCKET!, Key: key }).promise();
    return `https://${process.env.AWS_BUCKET}.s3.amazonaws.com/${key}`;
  } catch {
    // Не найден — генерируем
  }

  const pdfBuffer = await generateInvoicePDF(invoiceId);
  await s3.putObject({
    Bucket: process.env.AWS_BUCKET!,
    Key: key,
    Body: pdfBuffer,
    ContentType: 'application/pdf',
    ContentDisposition: `attachment; filename="invoice-${invoiceId}.pdf"`,
  }).promise();

  return `https://${process.env.AWS_BUCKET}.s3.amazonaws.com/${key}`;
}

Компонент счета детально проработан: таблица с описанием, количеством, ценой, суммой; блоки «От» и «Кому»; статус оплаты. Все данные берутся из БД, что гарантирует актуальность.

// components/pdf/InvoicePDF.tsx
import {
  Document, Page, Text, View, Image, StyleSheet
} from '@react-pdf/renderer';

const styles = StyleSheet.create({
  page: { padding: 40, fontSize: 11, fontFamily: 'Helvetica' },
  header: { flexDirection: 'row', justifyContent: 'space-between', marginBottom: 40 },
  title: { fontSize: 24, fontWeight: 'bold' },
  table: { marginTop: 20 },
  tableRow: { flexDirection: 'row', borderBottom: '1px solid #eee', padding: '8px 0' },
  tableHeader: { backgroundColor: '#f5f5f5', fontWeight: 'bold' },
});

export function InvoicePDF({ invoice }: { invoice: Invoice }) {
  return (
    <Document>
      <Page size="A4" style={styles.page}>
        <View style={styles.header}>
          <View>
            {invoice.tenant.branding?.logoUrl && (
              <Image src={invoice.tenant.branding.logoUrl} style={{ height: 40 }} />
            )}
            <Text style={styles.title}>СЧЁТ-ФАКТУРА</Text>
            <Text>№ {invoice.number}</Text>
            <Text>от {invoice.createdAt.toLocaleDateString('ru-RU')}</Text>
          </View>
          <View style={{ alignItems: 'flex-end' }}>
            <Text style={{ fontSize: 18, color: '#6366f1' }}>
              {formatCurrency(invoice.total, invoice.currency)}
            </Text>
            <Text style={{ color: invoice.status === 'paid' ? '#22c55e' : '#f59e0b' }}>
              {invoice.status === 'paid' ? 'Оплачен' : 'Ожидает оплаты'}
            </Text>
          </View>
        </View>

        {/* Детали компании */}
        <View style={{ flexDirection: 'row', gap: 40, marginBottom: 30 }}>
          <View>
            <Text style={{ fontWeight: 'bold', marginBottom: 4 }}>От:</Text>
            <Text>{process.env.COMPANY_NAME}</Text>
            <Text>ИНН: {process.env.COMPANY_INN}</Text>
          </View>
          <View>
            <Text style={{ fontWeight: 'bold', marginBottom: 4 }}>Кому:</Text>
            <Text>{invoice.customerName}</Text>
            {invoice.taxId && <Text>ИНН: {invoice.taxId}</Text>}
          </View>
        </View>

        {/* Строки инвойса */}
        <View style={styles.table}>
          <View style={[styles.tableRow, styles.tableHeader]}>
            <Text style={{ flex: 3 }}>Описание</Text>
            <Text style={{ flex: 1, textAlign: 'right' }}>Кол-во</Text>
            <Text style={{ flex: 1, textAlign: 'right' }}>Цена</Text>
            <Text style={{ flex: 1, textAlign: 'right' }}>Сумма</Text>
          </View>
          {invoice.lineItems.map((item) => (
            <View key={item.id} style={styles.tableRow}>
              <Text style={{ flex: 3 }}>{item.description}</Text>
              <Text style={{ flex: 1, textAlign: 'right' }}>{item.quantity}</Text>
              <Text style={{ flex: 1, textAlign: 'right' }}>
                {formatCurrency(item.unitAmount, invoice.currency)}
              </Text>
              <Text style={{ flex: 1, textAlign: 'right' }}>
                {formatCurrency(item.amount, invoice.currency)}
              </Text>
            </View>
          ))}
        </View>

        {/* Итого */}
        <View style={{ alignItems: 'flex-end', marginTop: 20 }}>
          <Text style={{ fontSize: 14, fontWeight: 'bold' }}>
            Итого: {formatCurrency(invoice.total, invoice.currency)}
          </Text>
        </View>
      </Page>
    </Document>
  );
}

Как работает синхронизация через webhook?

Webhook invoice.finalized присылает данные о новом счете. Мы upsert-им запись в своей БД и сохраняем ссылку на PDF от Stripe. Для собственных счетов — генерируем PDF и загружаем в S3. Это позволяет клиенту видеть счета в реальном времени.

case 'invoice.finalized': {
  const stripeInvoice = event.data.object as Stripe.Invoice;

  await db.invoice.upsert({
    where: { stripeInvoiceId: stripeInvoice.id },
    create: {
      stripeInvoiceId: stripeInvoice.id,
      tenantId: stripeInvoice.metadata.tenantId,
      number: stripeInvoice.number!,
      total: stripeInvoice.amount_due,
      currency: stripeInvoice.currency,
      status: 'open',
      pdfUrl: stripeInvoice.invoice_pdf,
      periodStart: new Date(stripeInvoice.period_start * 1000),
      periodEnd: new Date(stripeInvoice.period_end * 1000),
    },
    update: { status: 'open' }
  });
  break;
}

Что входит в работу

Типовые сложности и их устранение

Сроки ориентировочно

• Базовая настройка Stripe Invoicing — от 3 до 5 дней (без кастомных PDF).
• Собственная генерация PDF с S3 и webhook — от 7 до 10 дней.
• Полный цикл с интеграцией 1С — от 10 до 14 дней.

Стоимость рассчитывается индивидуально после аудита — напишите нам для консультации.

Наш опыт — 5+ лет в SaaS-разработке, более 30 успешных проектов с инвойсингом. Гарантируем корректную настройку и поддержку. Свяжитесь с нами, чтобы обсудить ваш проект и получить бесплатную консультацию.

Разработка SaaS-платформ

Мы знаем эту боль наизусть. Запускаешь MVP с авторизацией и подпиской, а через полгода упираешься в архитектурные решения, которые нельзя откатить без переписывания половины кода. Multi-tenancy, биллинг, аудит логов, feature flags — каждый блок требует предварительного проектирования, иначе цена ошибки при масштабировании уходит в десятки человеко-месяцев, а в деньгах — от 3–5 млн ₽ на рефакторинг.

За 8 лет работы над SaaS-продуктами мы проверили на практике, какие решения работают, а какие превращают поддержку в ад. Ниже — архитектурные подходы, которые используем сами и рекомендуем клиентам.

Как мы строим multi-tenancy: изоляция без оверхеда

Первое, что решаем — схема разделения данных. Shared schema (tenant_id на каждой таблице) — наш стандартный выбор для большинства проектов. Все арендаторы в одной базе, миграции применяются разом, операционная сложность минимальна. В Laravel реализуем через Global Scope:

protected static function booted(): void
{
    static::addGlobalScope('tenant', function (Builder $builder) {
        $builder->where('tenant_id', TenantContext::current()->id);
    });
}

Глобальный скоуп — только первый уровень защиты. Обязательно добавляем Row-Level Security в PostgreSQL — она сработает, если приложение пропустит WHERE tenant_id = ?:

ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON orders
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

Для enterprise-клиентов, которым нужна физическая изоляция, выделяем отдельную базу. Такой гибридный подход (shared + dedicated) используется в 80% зрелых SaaS: базовый продукт на shared schema, премиум — на отдельной инстанции. Мы внедряем его с первого спринта, чтобы не переписывать логику позже.

Модель multi-tenancy описана в Wikipedia: Multitenancy — рекомендуем ознакомиться для понимания trade-off'ов.

Почему биллинг — самый недооценённый блок

Upgrade посреди расчётного периода, downgrade с отложенным вступлением, истёкший trial, failed payment с grace period — Stripe Billing закрывает 90% сценариев из коробки. Обязательно обрабатываем вебхуки (customer.subscription.updated, invoice.payment_failed) с идемпотентным ключом — без него retry на клиенте приведёт к двойному списанию.

Для рынка СНГ — ЮKassa или Tinkoff recurring. API менее удобны, но покрывают требования 54-ФЗ.

Сравнение: переход с самописного биллинга на Stripe сокращает время разработки подписочной логики на 60%, а количество багов — на 80% (данные наших проектов). Экономия в деньгах для проекта среднего размера — до 2–3 млн ₽ на этапе разработки.

Onboarding: как не потерять пользователя до aha-moment

Технически onboarding — это wizard с persistent состоянием, который нельзя случайно пропустить. Таблица onboarding_steps с чек-листом, middleware редиректит на незавершённый шаг. После завершения — флаг в user settings, middleware отключается.

Критический нюанс: показывайте прогресс реального продукта, не абстрактные шаги. «Создайте первый отчёт» вместо «Завершите шаг 3 из 5». Мы используем drip-кампании через Customer.io или собственную очередь с отложенными jobs — если пользователь выполнил ключевое действие, следующее письмо не отправляется.

Feature flags и управление доступом

SaaS с тарифами требует гранулярного контроля. Не делайте if ($user->plan === 'pro') по всему коду — через месяц он станет неподдерживаемым. Вместо этого:

• Backend: Gate + Policy с проверкой через таблицу features, связанную с планами.
• Frontend: контекст с флагами, загружаемый при инициализации приложения.
• Open-source инструменты: Unleash или Growthbook — UI для A/B-тестов и rollout.

Как защитить API от агрессивных клиентов

Rate limiting — must-have для публичного API. Один клиент может положить всех остальных. В Laravel используем Redis с sliding window counter:

Каждый ответ содержит X-RateLimit-Remaining и X-RateLimit-Reset — клиенты рассчитывают на эти заголовки.

Аудит-логи и мониторинг: что, кто и когда

Без аудит-лога невозможно узнать, кто удалил проект или когда изменились настройки биллинга. Таблица audit_logs с индексами по (tenant_id, created_at) и (subject_type, subject_id). В Laravel — Observer'ы на ключевых моделях.

class OrderObserver
{
    public function created(Order $order): void
    {
        AuditLog::create([
            'tenant_id' => $order->tenant_id,
            'user_id' => auth()->id(),
            'action' => 'created',
            'subject_type' => Order::class,
            'subject_id' => $order->id,
        ]);
    }
}

Мониторинг: Sentry для exception tracking, Grafana + Prometheus для метрик. Алерты на error rate > 5% и response time p95 > 2s.

Опыт нашей команды и гарантии

Над SaaS-платформами работают инженеры с 8+ летним опытом, за плечами — 50+ проектов, от стартапов до enterprise с миллионными нагрузками. Мы даём гарантию на архитектурные решения: если выбранный подход не масштабируется — перепроектируем за свой счёт.

Deliverables и гарантии

• Документация архитектуры: схемы, ERD, sequence diagrams.
• Настройка CI/CD (GitHub Actions / GitLab CI).
• Доступы к репозиторию, стейджингу и продакшену.
• Обучение команды: 2–3 сессии по код-ревью и runbook.
• Post-launch поддержка 1 месяц.
• Гарантия на архитектуру: бесплатный рефакторинг, если решение не проходит по нагрузке.

Процесс работы

1. Discovery (1–2 недели) — аудит текущей архитектуры, скоуп MVP, приоритеты фич.
2. Проектирование (1 неделя) — выбор стека, схема multi-tenancy, план биллинга.
3. Разработка (4–12 недель) — спринты по 2 недели, демо после каждого.
4. Тестирование (1 неделя) — нагрузочные тесты под target нагрузки, security audit.
5. Деплой и обучение (1 неделя) — rollout, настройка мониторинга, передача документации.

Ориентиры по срокам

Стоимость рассчитывается индивидуально — свяжитесь с нами, мы оценим проект за 2 дня. Закажите разработку под ключ: от проектирования до деплоя с гарантией архитектуры. Получите консультацию по архитектуре вашего продукта — первый час бесплатно.