Jak zautomatyzować pobieranie faktur (KSeF + email)

KSeF (Krajowy System e-Faktur) — Ministerstwo Finansów. Production endpoint: https://ksef.mf.gov.pl/api/. Wymaga autoryzacji przez token (profile zaufany lub kwalifikowany certyfikat).

// ksef/client.ts
import { z } from 'zod';

const KsefInvoice = z.object({
  ksefReferenceNumber: z.string(),
  invoiceNumber: z.string(),
  issueDate: z.string(),
  sellerNip: z.string(),
  sellerName: z.string(),
  totalGross: z.number(),
  totalNet: z.number(),
  vat: z.number(),
});

export async function fetchKsefInvoices(since: Date) {
  const session = await ksefAuth(); // SessionToken
  
  const res = await fetch(`${KSEF_URL}/online/Invoice/Query`, {
    method: 'POST',
    headers: {
      'SessionToken': session.token,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      queryCriteria: {
        subjectType: 'subject1',
        type: 'incremental',
        invoicingDateRange: {
          from: since.toISOString(),
          to: new Date().toISOString(),
        },
      },
    }),
  });
  
  const data = await res.json();
  return data.invoiceHeaderList.map(h => KsefInvoice.parse(h));
}

Orange, Tauron, T-Mobile — każdy ma własny portal z fakturami. Standardowy flow: login → faktury → download PDF.

// portals/orange.ts
export async function downloadOrangeInvoices(creds) {
  const browser = await chromium.launch({ headless: true });
  const context = await browser.newContext();
  const page = await context.newPage();
  
  // Login
  await page.goto('https://www.orange.pl/zaloguj');
  await page.locator('#login').fill(creds.login);
  await page.locator('#password').fill(creds.password);
  await page.locator('button[type=submit]').click();
  await page.waitForURL('**/portfel');
  
  // Invoices section
  await page.goto('https://www.orange.pl/portfel/faktury');
  await page.waitForLoadState('networkidle');
  
  // Get PDF URLs
  const invoices = await page.$$eval('[data-test="invoice-row"]', rows =>
    rows.map(r => ({
      date: r.querySelector('.date')?.textContent,
      amount: r.querySelector('.amount')?.textContent,
      downloadUrl: r.querySelector('a.download')?.href,
    }))
  );
  
  // Download each PDF
  for (const inv of invoices) {
    const downloadPromise = page.waitForEvent('download');
    await page.goto(inv.downloadUrl);
    const download = await downloadPromise;
    const path = `./invoices/orange-${inv.date}.pdf`;
    await download.saveAs(path);
    inv.localPath = path;
  }
  
  await browser.close();
  return invoices;
}

Save storageState żeby nie logować się ciągle.

Najbardziej chaotyczne źródło. IMAP filter na "faktura" w title + załączony PDF:

import { ImapFlow } from 'imapflow';
import pdfParse from 'pdf-parse';

const client = new ImapFlow({
  host: 'imap.gmail.com',
  port: 993, secure: true,
  auth: { user: 'ksiegowa@firma.pl', pass: process.env.IMAP_PASS },
});

async function fetchEmailInvoices() {
  await client.connect();
  await client.mailboxOpen('INBOX');
  
  const messages = client.fetch(
    { since: new Date(Date.now() - 7*24*3600*1000) }, // last 7 days
    { source: true, envelope: true, bodyStructure: true }
  );
  
  for await (const msg of messages) {
    const subject = msg.envelope.subject.toLowerCase();
    if (!/faktura|invoice|fv/.test(subject)) continue;
    
    // Find PDF attachments
    const pdfParts = findPdfAttachments(msg.bodyStructure);
    for (const part of pdfParts) {
      const att = await client.download(msg.uid, part.part, { uid: true });
      const pdfBuffer = att.content;
      const parsed = await pdfParse(pdfBuffer);
      // ... extract data from parsed.text
    }
  }
  
  await client.logout();
}

Faktury PDF mają różne layouty. Regex działa dla 60-70% — reszta wymaga AI:

import Anthropic from '@anthropic-ai/sdk';
const claude = new Anthropic();

const InvoiceData = z.object({
  invoiceNumber: z.string(),
  issueDate: z.string(),
  sellerVatId: z.string(),
  sellerName: z.string(),
  totalNet: z.number(),
  totalGross: z.number(),
  vat: z.number(),
  currency: z.enum(['PLN', 'EUR', 'USD']),
  dueDate: z.string().optional(),
});

async function extractInvoiceData(pdfText: string) {
  const res = await claude.messages.create({
    model: 'claude-3-5-sonnet-latest',
    max_tokens: 1024,
    messages: [{
      role: 'user',
      content: `Extract structured data from this invoice. Return ONLY JSON matching schema:
        { invoiceNumber, issueDate (YYYY-MM-DD), sellerVatId, sellerName, totalNet, totalGross, vat, currency, dueDate }
        
        Invoice text:
        ${pdfText}`,
    }],
  });
  
  const json = JSON.parse(res.content[0].text);
  return InvoiceData.parse(json); // validate
}

Cost: ~$0.005 per invoice z Claude Sonnet. 200 faktur/mies = $1. Marginalne.

iFirma ma REST API. Każda zewn. faktura kosztowa: POST /invoices.

async function pushToIFirma(invoice, pdfPath) {
  const formData = new FormData();
  formData.append('invoice', JSON.stringify({
    nazwa: invoice.sellerName,
    nip_sprzedawcy: invoice.sellerVatId,
    data_wystawienia: invoice.issueDate,
    netto: invoice.totalNet,
    vat: invoice.vat,
    brutto: invoice.totalGross,
    waluta: invoice.currency,
    numer_dokumentu: invoice.invoiceNumber,
  }));
  formData.append('pdf', await fs.readFile(pdfPath));
  
  const res = await fetch('https://api.ifirma.pl/iapi/invoices.json', {
    method: 'POST',
    headers: {
      'Authentication': `IAPIS user=${process.env.IFIRMA_USER}, hmac-sha1=${signature}`,
    },
    body: formData,
  });
  
  return res.json();
}

Po każdym sukcesie: mark invoice jako "uploaded", store reference ID, log dla audytu.