Invoices

Auto-generated by go run ./​cmd/​gen-skills. Do not edit manually.

Invoices

PREREQUISITE: Read fakturownia-shared first.

Use This Skill When

• The task is about reading or mutating invoices, sending invoice emails, sending invoices to KSeF through the API-native gov flow, printing fiscally, or attaching files.
• You need to discover invoice output fields such as number, status, token, gov_status, or nested paths like positions[].name.
• You need to inspect request_body_schema before constructing invoice create or invoice update payloads.

Covered Commands

• fakturownia invoice list — List invoices
• fakturownia invoice get — Fetch a single invoice by ID
• fakturownia invoice create — Create an invoice
• fakturownia invoice update — Update an invoice
• fakturownia invoice delete — Delete an invoice
• fakturownia invoice send-email — Send an invoice by email
• fakturownia invoice send-gov — Queue an existing invoice for KSeF submission
• fakturownia invoice change-status — Change an invoice status
• fakturownia invoice cancel — Cancel an invoice
• fakturownia invoice public-link — Derive public invoice and PDF links from the invoice token
• fakturownia invoice add-attachment — Upload and attach a file to an invoice
• fakturownia invoice download-attachment — Download a single invoice attachment by kind
• fakturownia invoice download-attachments — Download all invoice attachments as a ZIP archive
• fakturownia invoice fiscal-print — Trigger a fiscal printer job for one or more invoices
• fakturownia invoice download — Download a single invoice PDF

Notable Flags

• --page (default 1): Requested result page
• --per-page (default 25): Requested result count per page
• --period (enum last_12_months, this_month, last_30_days, last_month, this_year, last_year, all, more): Date period filter
• --date-from: Lower date bound for period=more
• --date-to: Upper date bound for period=more
• --include-positions (default false): Include invoice positions
• --client-id: Filter by client ID
• --invoice-ids: Filter by specific invoice IDs
• --number: Filter by invoice number
• --kind: Filter by invoice kind; one value uses kind= and repeated values use kinds[]
• --search-date-type (enum issue_date, paid_date, transaction_date): Date field to search by
• --order: Sort order
• --income (enum yes, no): Income selector
• --id (required): Invoice ID
• --include: Request upstream invoice includes such as descriptions
• --additional-field: Request additional upstream invoice fields such as cancel_reason, corrected_content_before, corrected_content_after, or connected_payments
• --correction-positions: Request correction position details such as full
• --input (required): Invoice JSON input as inline JSON, @file, or - for stdin
• --identify-oss (default false): Validate OSS eligibility before marking the invoice as OSS
• --fill-default-descriptions (default false): Include default account descriptions on the created invoice
• --gov-save-and-send (default false): Save the invoice and immediately queue it for KSeF submission
• --yes (required, default false): Confirm invoice deletion
• --email-to: Override recipients for the invoice email
• --email-cc: Override CC recipients for the invoice email
• --email-pdf (default false): Attach the invoice PDF
• --update-buyer-email (default false): Update the invoice buyer or recipient email when email-to is provided
• --print-option (enum original, copy, original_and_copy, duplicate): PDF print option
• --status (required): Target invoice status
• --reason: Optional cancellation reason
• --file (required): Attachment file path or - for stdin
• --name: Attachment file name; required when --file - is used
• --path: Explicit output file path
• --dir: Output directory for the downloaded attachment
• --invoice-id (required): Invoice ID to send to fiscal print
• --printer: Fiscal printer name

Environment

• FAKTUROWNIA_PROFILE: Select a profile unless --profile is provided
• FAKTUROWNIA_URL: Override the base account URL from any profile
• FAKTUROWNIA_API_TOKEN: Override the API token from any profile

Output and Request Discovery

• Use fakturownia schema invoice list --json and fakturownia schema invoice get --json before building selectors.
• Read output.known_fields to discover invoice field names curated from the main README plus KSeF.md.
• Nested selectors use dot_bracket paths such as positions[].name.
• Use fakturownia schema invoice create --json and fakturownia schema invoice update --json before building invoice payloads.
• Invoice schemas also cite the bank-account addendum for fields such as bank_account_id, buyer_mass_payment_code, and embedded bank_accounts[] entries.
• The API uses gov field names for KSeF integration. In practice, gov_status, gov_id, and attachment kinds such as gov / gov_upo are the KSeF fields to inspect.
• Use fakturownia invoice send-gov --id ... --json to queue an existing invoice for KSeF and fakturownia invoice download-attachment --id ... --kind gov|gov_upo --json to fetch KSeF XML documents.
• --gov-save-and-send is a top-level companion flag for invoice create and invoice update, outside the inner invoice object.
• output.known_fields is curated, not exhaustive, so valid undocumented paths may still work.

Recipes

• fakturownia-invoice-minimal: Create a minimal invoice when you already know the client and product IDs.
• fakturownia-invoice-copy: Create a new invoice by copying another invoice, order, or proforma with copy_invoice_from.
• fakturownia-invoice-correction: Create and inspect correction invoices, including before/​after correction fields.
• fakturownia-invoice-oss: Create an OSS invoice and ask the API to validate the OSS conditions before marking it.
• fakturownia-invoice-ksef-create-send: Create an invoice with the API-native gov companion flag that queues the document for KSeF submission right away.
• fakturownia-invoice-ksef-send-status: Queue an already-created invoice for KSeF submission and read the gov_* status fields that the API returns.
• fakturownia-invoice-ksef-download-documents: Download KSeF XML documents through the generic invoice attachment endpoint using API-native gov kinds.
• fakturownia-invoice-ksef-tax-id-kinds: Prepare buyer and seller tax identifier fields for KSeF-aware invoice payloads, including foreign buyers.
• fakturownia-invoice-ksef-recipients-issuers: Build recipient and issuer payloads with KSeF-specific roles, tax identifier kinds, and participation fields.
• fakturownia-invoice-ksef-correction-to-zero: Model KSeF correction workflows, including gov_corrected_invoice_number and the practical correction-to-zero pattern.
• fakturownia-invoice-send-email: Send an invoice email, optionally overriding recipients and attaching the PDF.
• fakturownia-invoice-cancel: Cancel an invoice and optionally store a cancellation reason.
• fakturownia-invoice-recipients-issuers: Create or update invoice recipients and issuers through the generic invoice payload.
• fakturownia-invoice-attachment: Upload a file through the attachment credentials flow and bind it to an invoice.
• fakturownia-invoice-fiscal-print: Submit one or more invoices to the fiscal print endpoint, optionally targeting a printer by name.
• fakturownia-invoice-receipt-link: Link a receipt to an existing invoice or create a new invoice from a receipt using the README-backed payload fields.

Examples

fakturownia invoice list --json
fakturownia invoice list --period this_month --columns id,number,buyer_name,price_gross
fakturownia invoice list --include-positions --fields number,positions[].name --json
fakturownia invoice list --page 2 --per-page 25 --raw
fakturownia invoice get --id 123
fakturownia invoice get --id 123 --additional-field cancel_reason --json
fakturownia invoice get --id 123 --include descriptions --fields descriptions[].content --json
fakturownia invoice get --id 123 --correction-positions full --json
fakturownia invoice get --id 123 --fields id,number,status --json
fakturownia invoice get --id 123 --fields id,number,bank_accounts[].bank_account_number --json
fakturownia invoice get --id 123 --fields number,positions[].name --json
fakturownia invoice get --id 123 --raw
fakturownia invoice create --input '{"kind":"vat","client_id":1,"positions":[{"product_id":1,"quantity":2}]}' --json
fakturownia invoice create --input '{"kind":"vat","buyer_name":"Klient ABC","bank_account_id":100,"buyer_mass_payment_code":"ABC-123","positions":[{"name":"Usługa","quantity":1,"total_price_gross":1230,"tax":23}]}' --json
fakturownia invoice create --input '{"copy_invoice_from":42,"kind":"vat"}' --json
fakturownia invoice create --gov-save-and-send --input '{"kind":"vat","buyer_company":true,"seller_tax_no":"5252445767","seller_street":"ul. Przykładowa 10","seller_post_code":"00-001","seller_city":"Warszawa","buyer_name":"Klient ABC Sp. z o.o.","buyer_tax_no":"9876543210","positions":[{"name":"Usługa","quantity":1,"total_price_gross":1230,"tax":23}]}' --json
fakturownia invoice create --input '{"kind":"vat","seller_country":"PL","buyer_country":"FR","use_oss":true,"positions":[{"name":"Produkt","tax":20,"total_price_gross":50,"quantity":1}]}' --identify-oss --json
fakturownia invoice create --input '{"kind":"vat","positions":[{"name":"towar","quantity":1,"total_price_gross":123}]}' --fill-default-descriptions --dry-run --json
fakturownia invoice update --id 111 --input '{"buyer_name":"Nowa nazwa klienta Sp. z o.o."}' --json
fakturownia invoice update --id 111 --input '{"positions":[{"id":32649087,"name":"test"}]}' --json
fakturownia invoice update --id 111 --input '{"positions":[{"id":32649087,"_destroy":1}]}' --json
fakturownia invoice update --id 111 --gov-save-and-send --input '{"buyer_company":true,"buyer_tax_no_kind":"nip_ue","buyer_tax_no":"DE123456789"}' --json
printf '%s\n' '{"show_attachments":true}' | fakturownia invoice update --id 111 --input - --dry-run --json
fakturownia invoice delete --id 111 --yes --json
fakturownia invoice delete --id 111 --yes --dry-run --json
fakturownia invoice send-email --id 100 --json
fakturownia invoice send-email --id 100 --email-to [email protected] --email-pdf --json
fakturownia invoice send-email --id 100 --email-to [email protected] --update-buyer-email --print-option original --dry-run --json
fakturownia invoice send-gov --id 100 --json
fakturownia invoice send-gov --id 100 --raw
fakturownia invoice send-gov --id 100 --dry-run --json
fakturownia invoice change-status --id 111 --status sent --json
fakturownia invoice change-status --id 111 --status paid --dry-run --json
fakturownia invoice cancel --id 111 --yes --json
fakturownia invoice cancel --id 111 --yes --reason 'Powód anulowania' --dry-run --json
fakturownia invoice public-link --id 100 --json
fakturownia invoice add-attachment --id 111 --file ./​scan.pdf --json
cat ./​scan.pdf | fakturownia invoice add-attachment --id 111 --file - --name scan.pdf --dry-run --json
fakturownia invoice download-attachment --id 111 --kind gov
fakturownia invoice download-attachment --id 111 --kind gov_upo --dir ./​attachments --json
fakturownia invoice download-attachment --id 111 --kind custom --path ./​attachment.bin --json
fakturownia invoice download-attachments --id 111 --dir ./​attachments
fakturownia invoice download-attachments --id 111 --path ./​invoice-111-attachments.zip --json
fakturownia invoice fiscal-print --invoice-id 111 --invoice-id 112 --json
fakturownia invoice fiscal-print --invoice-id 111 --printer DRUKARKA --dry-run --json
fakturownia invoice download --id 123 --dir ./​invoices
fakturownia invoice download --id 123 --path ./​invoice-123.pdf --json

Related Skills

• fakturownia-shared
• fakturownia-products
• fakturownia-bank-accounts
• fakturownia-price-lists
• fakturownia-recurrings
• fakturownia-schema
• fakturownia-doctor