/download-platform-invoices

name: download-platform-invoices
description: Harvest monthly SaaS billing invoices into normalized records and official PDF files.
user-invocable: true
metadata:
  hybridclaw:
    category: business
    short_description: "Monthly SaaS invoice harvesting."
    tags:
      - billing
      - invoices
      - bookkeeping
      - datev
      - automation
    related_skills:
      - stripe
      - pdf

Download Platform Invoices

Use this skill when the user wants monthly SaaS invoice PDFs collected from billing portals or billing APIs for bookkeeping handoff.

Output Contract

Each fetched invoice must produce one normalized JSON record and the original official PDF. The record shape is:

{
  "vendor": "openai",
  "invoice_no": "E-2026-03-001",
  "period": "2026-03",
  "issue_date": "2026-04-01",
  "due_date": "2026-04-15",
  "net": 123.45,
  "vat_rate": 0.19,
  "vat": 23.45,
  "gross": 146.9,
  "currency": "EUR",
  "pdf_path": "runs/2026-03/openai/E-2026-03-001.pdf",
  "source_url": "https://platform.openai.com/account/billing",
  "checksum_sha256": "64 lowercase hex characters"
}

Validate records with the colocated `schema.json` contract. Keep `pdf_path` relative to the invoice run directory.

Adapter Contract

Adapters follow this shape:

login(credentials) -> session
listInvoices(session, { since }) -> InvoiceMeta[]
download(session, invoice) -> Uint8Array

The runtime implementation is colocated with this skill:

• Stripe API adapter
• browser-driver scrape adapters for GitHub, OpenAI, Anthropic, Atlassian,

and LinkedIn

• native API adapters for Google Ads InvoiceService, AWS Invoicing, Azure

Billing invoices, and GCP Cloud Billing account authorization. Google does not expose invoice PDF listing/download in the public Cloud Billing REST API, so the GCP adapter uses the browser document driver for the Documents page after API authorization.

• DATEV Unternehmen Online handoff prefers an injected DATEV Datenservice,

Rechnungsdatenservice/Belegbilderservice, MCP, or certified API client. If no such client is configured, it falls back to browser upload through DATEV Upload online/Belege online.

• manifest-based idempotency using `(vendor, invoice_no)` and

`checksum_sha256`

• audit event emission per fetched invoice
• recorded fixture replay for every launch provider with sanitized HTTPS trace

metadata and DOM snapshots, so CI does not touch live billing portals

Credential Rules

• Store secrets in HybridClaw encrypted runtime secrets with provider-specific

uppercase names such as `STRIPE_INVOICE_API_KEY`, `OPENAI_INVOICE_PASSWORD`, or `GITHUB_INVOICE_TOTP_SECRET`.

• When advising an operator to set or update those secrets, use this order:

browser admin at the active `/admin/secrets` route, `/secret set ...` in browser `/chat` or TUI, then `hybridclaw secret set ...` in a local console.

• Resolve credentials through `resolveInvoiceCredentials`; do not inline or log

cleartext secrets.

• Keep provider credential references in invoice harvester config as

`{ "source": "store", "id": "PROVIDER_SECRET_NAME" }`. Runtime config revisions track the references, while encrypted secret values stay out of revision content.

• When a provider fails with an auth/401/403 class error, the monthly runner

asks the injected credential store to rotate the referenced secret once and rolls that revision back if the retry still fails.

• TOTP is supported when a provider driver uses a `totpSecret` credential.
• Push MFA and captchas must stop the provider run and emit

`invoice.operator_escalation_required` for F8 operator routing.

Google Ads InvoiceService

Use secret credentials plus the official Google Ads API calls.

Secret credentials:

• OAuth: `hybridclaw auth login google --scopes "https://www.googleapis.com/auth/adwords"`
• Routes:

`hybridclaw secret route add https://googleads.googleapis.com/ google-oauth Authorization Bearer` `hybridclaw secret route add https://googleads.googleapis.com/ GOOGLEADS_DEVELOPER_TOKEN developer-token none`

• Optional store values:

`GOOGLEADS_CUSTOMER_ID`, `GOOGLEADS_BILLING_SETUP`, `GOOGLEADS_LOGIN_CUSTOMER_ID`

API calls:

GET https://googleads.googleapis.com/v24/customers:listAccessibleCustomers
POST https://googleads.googleapis.com/v24/customers/<manager-customer-id>/googleAds:search
POST https://googleads.googleapis.com/v24/customers/<customer-id>/googleAds:search
GET https://googleads.googleapis.com/v24/customers/<customer-id>/invoices?billingSetup=customers/<customer-id>/billingSetups/<billing-setup-id>&issueYear=<yyyy>&issueMonth=<MONTH>
GET <invoice.pdfUrl>

Use `customer_client` to find MCC children, `billing_setup.resource_name` for `billingSetup`, and `InvoiceService` `pdfUrl` for the PDF. Never call `POST /v24/customers/<customer-id>:search`; use `/v24/customers/<customer-id>/googleAds:search`.

Run Discipline

• Process one provider at a time.
• Reuse a session-isolated browser profile per provider so cookies can persist

between monthly runs.

• Add jitter between scrape providers when running live.
• Never solve captchas silently.
• Never OCR invoices in this skill; adapters return the official PDF.

DATEV Handoff

When paired with the DATEV workflow, run invoice harvesting first, review the manifest, then pass the normalized records and PDF paths to the DATEV upload step. The composed workflow fixture is `tests/fixtures/workflows/monthly-invoice-run.workflow.yaml`.

The runtime composition helper is `runMonthlyInvoiceRun` in `harvester.cjs`. It runs configured providers one at a time, emits invoice audit events, and calls `DatevUnternehmenOnlineUploadAdapter` when the handoff is enabled and the operator provides a configured DATEV API/MCP client or upload driver/profile.