majncz/fakturoid-skill

Overview

This skill integrates with the Fakturoid Czech invoicing API to create, manage, and retrieve invoices, contacts (subjects), expenses, inventory items, recurring invoices, webhooks, and invoice templates. It supports OAuth 2.0 authentication, Czech tax fields (IČO, DIČ, local VAT rules), PDF downloads, payment tracking, and OCR processing for inbox files. The skill is built for reliable compliance with Czech invoicing workflows and automated billing tasks.

How this skill works

Authenticate via OAuth 2.0 (client credentials or authorization code) and store tokens for repeated calls. Use dedicated endpoints and scripts to manage subjects, invoices, expenses, inventory, recurring generators, and webhooks; each resource supports create, read, update, delete and action operations. The integration enforces required headers, respects rate limits, handles Czech-specific fields (registration_no, vat_no, DUZP), and returns PDF files, payment records, and OCR results when requested.

When to use it

• You need to create or send Czech-compliant invoices with IČO/DIČ and VAT handling.
• You want to manage contacts (customers or suppliers) and link them to invoices or expenses.
• You need automated recurring invoices, invoice templates (generators), or inventory-linked line items.
• You must download invoice PDFs, track payments, or mark invoices as sent/paid.
• You want to process supplier invoices via OCR or record and pay expenses.
• You need webhook notifications for invoice events or account activity.

Best practices

• Set a clear User-Agent header and store OAuth tokens securely (token file recommended).
• Respect rate limits (400 requests per 60 seconds) and implement retry/backoff on 429 responses.
• Validate Czech-specific fields (registration_no/IČO, vat_no/DIČ, DUZP date) before sending requests.
• Use pagination for list endpoints (40 records per page) and filter on server-side where possible.
• Lock critical documents when performing multi-step updates to avoid race conditions.
• Check API validation errors (422) and surface the errors field to users for fast remediation.

Example use cases

• Create a new subject with IČO and DIČ, then generate and mark an invoice as sent and download the PDF.
• Record a supplier expense, attach the original number, run OCR on a scanned invoice, and mark it paid.
• Set up a monthly recurring invoice generator that customizes line names with date placeholders.
• Manage inventory items, create stock moves, and attach inventory_item_id to invoice lines.
• Subscribe to webhook events to trigger downstream accounting workflows when invoices are paid.