fakturoid-skill

内容来源：SKILL.md（标准 Skill 格式） · 原始地址 · 查看安装指南

原始内容

---
name: fakturoid
description: Czech invoicing API integration for Fakturoid. Use when the user needs to create, manage, or retrieve invoices, contacts/subjects, or expenses from Fakturoid. Supports OAuth 2.0 authentication, invoice creation with Czech tax compliance (IČO, DIČ, VAT), PDF downloads, payment tracking, expense management, inventory, recurring invoices, webhooks, and invoice templates (generators). Triggers on mentions of Fakturoid, Czech invoicing, IČO/DIČ, or invoice management tasks.
---

# Fakturoid API v3

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

## Quick Start

### Environment Setup
```bash
export FAKTUROID_CLIENT_ID="your-client-id"
export FAKTUROID_CLIENT_SECRET="your-client-secret"
export FAKTUROID_ACCOUNT_SLUG="your-account-slug"
```

### Authenticate
```bash
python scripts/auth.py credentials --save
```

### Create Invoice
```bash
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

```http
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
```bash
# 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
```bash
# 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
```bash
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
```bash
# 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

```json
{
  "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](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/api-reference.md) - Complete endpoint catalog
- [authentication.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/authentication.md) - OAuth 2.0 guide with code examples
- [error-handling.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/error-handling.md) - Error codes and handling

### Resource Documentation
- [invoices.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/invoices.md) - Invoice management
- [invoice-payments.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/invoice-payments.md) - Payment operations
- [invoice-messages.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/invoice-messages.md) - Email sending
- [subjects.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/subjects.md) - Contact management
- [expenses.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/expenses.md) - Expense tracking
- [expense-payments.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/expense-payments.md) - Expense payments
- [generators.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/generators.md) - Invoice templates
- [recurring-generators.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/recurring-generators.md) - Automated invoicing
- [inventory.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/inventory.md) - Stock management
- [webhooks.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/webhooks.md) - Event notifications

### Additional Resources
- [users.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/users.md) - User and account info
- [account.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/account.md) - Account settings
- [bank-accounts.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/bank-accounts.md) - Bank accounts
- [number-formats.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/number-formats.md) - Invoice numbering
- [inbox-files.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/inbox-files.md) - OCR processing
- [events.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/events.md) - Activity log
- [todos.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/todos.md) - Task management
- [czech-invoicing.md](https://github.com/majncz/fakturoid-skill/blob/HEAD/references/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

```bash
# 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:
```http
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.

name: fakturoid description: Czech invoicing API integration for Fakturoid. Use when the user needs to create, manage, or retrieve invoices, contacts/subjects, or expenses from Fakturoid. Supports OAuth 2.0 authentication, invoice creation with Czech tax compliance (IČO, DIČ, VAT), PDF downloads, payment tracking, expense management, inventory, recurring invoices, webhooks, and invoice templates (generators). Triggers on mentions of Fakturoid, Czech invoicing, IČO/DIČ, or invoice management tasks.

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.