Fakturoid API v3

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

Required Headers

User-Agent: YourAppName ([email protected])
Authorization: Bearer {access_token}
Content-Type: application/​json
Accept: application/​json

---

Scripts Reference

Core Scripts

Additional Scripts

---

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

Invoice Status

Expense Status

VAT Modes

VAT Price Modes

VAT Rates

Payment Methods

Languages

Subject Types

Invoice Actions

Expense Actions

OSS Modes (EU One Stop Shop)

Proforma Followup Documents

OCR Status

---

Czech-Specific Fields

---

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

---

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

---

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.