Fakturoid API v3

Czech invoicing service API integration - comprehensive reference for building integrations.

Quick Start

Environment Setup

export FAKTUROID_CLIENT_ID="your-client-id"
export FAKTUROID_CLIENT_SECRET="your-client-secret"
export FAKTUROID_ACCOUNT_SLUG="your-account-slug"

Authenticate

python scripts/auth.py credentials --save

Create Invoice

python scripts/invoice.py create --subject-id 123 --lines '[
  {"name": "Consulting", "quantity": 8, "unit_name": "hours", "unit_price": 2000, "vat_rate": 21}
]'

---

API Basics

Setting	Value
Base URL	https://app.fakturoid.cz/api/v3
Account URL	https://app.fakturoid.cz/api/v3/accounts/{slug}
Auth	OAuth 2.0 (Client Credentials or Authorization Code)
Pagination	40 records per page
Rate Limit	400 requests per 60 seconds

Required Headers

User-Agent: YourAppName (your@email.com)
Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

---

Scripts Reference

Core Scripts

Script	Commands	Description
auth.py	credentials, refresh, revoke, status	OAuth token management
subject.py	list, get, search, create, update, delete, lookup-ico	Contact management
invoice.py	list, get, search, create, update, delete, action, pdf, pay, pay-delete	Invoice operations
expense.py	list, get, search, create, update, delete, action, pay, pay-delete	Expense tracking
generator.py	list, get, create, update, delete	Invoice templates

Additional Scripts

Script	Commands	Description
user.py	get, list	User and account info
bank_account.py	list	Bank account listing
inventory.py	list-items, get-item, create-item, list-moves, create-move	Inventory management
recurring.py	list, get, create, update, delete, pause, activate	Recurring invoices
inbox.py	list, upload, send-to-ocr, download, delete	OCR file processing
event.py	list, list-paid	Activity log
todo.py	list, toggle	Task management
message.py	send	Send invoice emails
webhook.py	list, get, create, update, delete	Webhook management

---

Common Workflows

Create Invoice for New Customer

# 1. Create subject
python scripts/subject.py create --name "Acme s.r.o." --ico 12345678 --dic CZ12345678

# 2. Create invoice (use returned subject ID)
python scripts/invoice.py create --subject-id 456 --lines '[
  {"name": "Web development", "quantity": 40, "unit_name": "hours", "unit_price": 1500, "vat_rate": 21}
]'

# 3. Mark as sent and download PDF
python scripts/invoice.py action 789 mark_as_sent
python scripts/invoice.py pdf 789 --output invoice.pdf

Record Expense from Supplier

# 1. Ensure supplier exists
python scripts/subject.py create --name "Supplier Ltd" --type supplier --ico 87654321

# 2. Create expense
python scripts/expense.py create --subject-id 321 --original-number "FV-2024-0456" --lines '[
  {"name": "Office supplies", "quantity": 10, "unit_name": "ks", "unit_price": 450, "vat_rate": 21}
]'

Setup Monthly Recurring Invoice

python scripts/recurring.py create --name "Monthly Hosting" --subject-id 123 \
  --start-date 2024-02-01 --months-period 1 --send-email \
  --lines '[{"name": "Web hosting - {MMMM} {YYYY}", "unit_price": 500, "vat_rate": 21}]'

Process Inbox File with OCR

# Upload and send to OCR
python scripts/inbox.py upload invoice.pdf --send-to-ocr

# Check status
python scripts/inbox.py list

---

Enums Reference

Document Types

Value	Czech	Description
invoice	Faktura	Standard invoice
proforma	Zálohová faktura	Advance payment request
partial_proforma	Částečná záloha	Legacy partial advance
correction	Dobropis	Credit note
tax_document	Daňový doklad	Tax receipt for proforma payment
final_invoice	Vyúčtovací faktura	Final invoice from tax documents

Invoice Status

Value	Description
open	New, unpaid, not sent
sent	Sent to client, not overdue
overdue	Past due date
paid	Fully paid
cancelled	Cancelled (VAT payers only)
uncollectible	Marked as bad debt

Expense Status

Value	Description
open	Received, not paid
overdue	Past due date
paid	Fully paid

VAT Modes

Value	Czech	Description
vat_payer	Plátce DPH	Standard VAT payer
non_vat_payer	Neplátce DPH	Non-VAT payer
identified_person	Identifikovaná osoba	EU VAT identified person

VAT Price Modes

Value	Description
without_vat	Prices entered without VAT
from_total_with_vat	Calculate VAT from total with VAT

VAT Rates

Value	Rate	Description
standard	21%	Standard rate
reduced	12%	First reduced rate
reduced2	10%	Second reduced rate
zero	0%	Zero VAT

Payment Methods

Value	Description
bank	Bank transfer
cash	Cash payment
cod	Cash on delivery
card	Card payment
paypal	PayPal
custom	Custom (see custom_payment_method)

Languages

Value	Language
cz	Czech
sk	Slovak
en	English
de	German
fr	French
it	Italian
es	Spanish
ru	Russian
pl	Polish
hu	Hungarian
ro	Romanian

Subject Types

Value	Description
customer	Customer only
supplier	Supplier only
both	Both customer and supplier

Invoice Actions

Action	Description
mark_as_sent	Mark invoice as sent
cancel	Cancel invoice
undo_cancel	Revert cancellation
lock	Lock from editing
unlock	Unlock for editing
mark_as_uncollectible	Mark as bad debt
undo_uncollectible	Revert uncollectible

Expense Actions

Action	Description
lock	Lock from editing
unlock	Unlock for editing

OSS Modes (EU One Stop Shop)

Value	Description
disabled	OSS disabled
service	OSS for services
goods	OSS for goods

Proforma Followup Documents

Value	Description
final_invoice_paid	Auto-create paid invoice
final_invoice	Manual invoice creation
tax_document	Auto-create tax document
none	No followup document

OCR Status

Value	Description
created	OCR requested
processing	OCR in progress
processing_failed	OCR failed
processing_rejected	File rejected
processed	Successfully processed

---

Czech-Specific Fields

API Field	Czech	Example
registration_no	IČO	12345678
vat_no	DIČ	CZ12345678
local_vat_no	SK DIČ	1234567890
taxable_fulfillment_due	DUZP	2024-01-15
transferred_tax_liability	Přenesená daňová povinnost	true
supply_code	Kód předmětu plnění	4

---

Line Item Structure

{
  "name": "Service description",
  "quantity": 10,
  "unit_name": "hours",
  "unit_price": 1500,
  "vat_rate": 21,
  "inventory_item_id": 123,
  "sku": "PROD-001"
}

Line Operations

Operation	Method
Add line	Omit id
Update line	Include id
Delete line	Include id and _destroy: true

---

References

Core Documentation

• api-reference.md - Complete endpoint catalog
• authentication.md - OAuth 2.0 guide with code examples
• error-handling.md - Error codes and handling

Resource Documentation

• invoices.md - Invoice management
• invoice-payments.md - Payment operations
• invoice-messages.md - Email sending
• subjects.md - Contact management
• expenses.md - Expense tracking
• expense-payments.md - Expense payments
• generators.md - Invoice templates
• recurring-generators.md - Automated invoicing
• inventory.md - Stock management
• webhooks.md - Event notifications

Additional Resources

• users.md - User and account info
• account.md - Account settings
• bank-accounts.md - Bank accounts
• number-formats.md - Invoice numbering
• inbox-files.md - OCR processing
• events.md - Activity log
• todos.md - Task management
• czech-invoicing.md - Czech tax compliance

---

Error Handling

Status	Meaning	Action
400	Bad Request	Check date formats, User-Agent header
401	Unauthorized	Refresh OAuth token
402	Payment Required	Fakturoid account blocked
403	Forbidden	Permission denied, resource limits
404	Not Found	Resource doesn't exist
422	Validation Error	Check errors field for details
429	Rate Limited	Wait for X-RateLimit reset
503	Unavailable	Maintenance, retry later

---

Token Management

# Get new token
python scripts/auth.py credentials --save

# Check token status
python scripts/auth.py status

# Refresh expired token (Authorization Code flow)
python scripts/auth.py refresh

# Revoke token
python scripts/auth.py revoke

Token file: ~/.fakturoid/token.json

---

Rate Limiting

Headers on every response:

X-RateLimit-Policy: default;q=400;w=60
X-RateLimit: default;r=398;t=55

• q=400: Max 400 requests
• w=60: Per 60 seconds window
• r=398: Remaining requests
• t=55: Seconds until reset

When exceeded: 429 Too Many Requests - wait for reset.