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.