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.