> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://kb.fyzion.cz/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Synchronizace plateb (dokladů) z Fyzion API do externích systémů

# Synchronizace plateb z Fyzion API
Jak stahovat doklady (paragony, faktury, opravné daňové doklady) a držet je v synchronizaci s externím systémem. Kompletní seznam endpointů a schémat je ve Swagger (OpenAPI) specifikaci.

||| Účet, pod kterým integrace běží, musí mít oprávnění get\_receipt\_for\_colleague – jinak vidí jen doklady, které sám vlastní.

## Endpointy

* `GET /v1/receipts/` – seznam, hlavní zdroj pro sync
* `GET /v1/receipts/{id}` – detail; jediná cesta k položkám dokladu, adresním údajům a `created_at`
* `POST /v1/receipts/export` – pro sync nepoužívat, běží asynchronně a ZIP chodí e-mailem uživateli, který export vyvolal

Stránkování:
```
GET /v1/receipts/?limit=200&offset=0
→ { "items": [ ... ], "count": 1234 }

```

řazení je fixní od nejnovějších

## Filtry seznamu

| **Filtr** | **Chování** |
| ---- |
| `invoiced_from` / `invoiced_to` | `invoiced_at >= / <= X` |
| `payment_status` | `PAID` / `UNPAID` / `ALL` |
| `cancelled` | `true` = jen stornované; ignoruje se, pokud je poslán `payment_status` |
| `payment_types` | `cash`, `bank_transfer`, `card`, `ticket`, `subscription`, `webpay` |
| `invoice_types` | `receipt`, `invoice`, `corrective_tax_document_receipt`, `corrective_tax_document_invoice` |
| `user_id` | vlastník dokladu (terapeut) |
| `visit_id` | doklady navázané na návštěvu |
| `location_id` | pobočka |
| `searching` | fulltext přes jméno/adresu/e-mail/IČO/DIČ odběratele; přebíjí řazení |

## Identifikátory

* klíč pro sync je `id` (UUID)
* `public_id` nikdy jako klíč – je to pořadové číslo v číselné řadě (zvlášť paragony a faktury, zvlášť fyzická osoba a firma) a po smazání posledního dokladu v řadě se recykluje
* `items` / `stock_items` dostávají při `PUT` nová ID → přepisujte je celé
* `is_paid` / `paid_at` = reálná platba, `is_invoice_paid` je jen příznak pro tisk PDF

## Postup

Prvotní naplnění – po měsíčních oknech:
```
GET /v1/receipts/?invoiced_from=2024-01-01&invoiced_to=2024-01-31&limit=200&offset=0

```
Průběžný sync –  každých 15–60 minut:
```
GET /v1/receipts/?invoiced_from=<dnes-14dní>&limit=200&offset=0

```
Zpětné změny – denně:
```
GET /v1/receipts/?payment_status=UNPAID&invoiced_from=<dnes-12měsíců>

```
Rekonciliace – denně, za uzavřené období (např. 90 dní, stejné filtry jako běžný sync). Porovnejte `id` i příznaky (`is_paid`, `price`, `invoice_price`):
* chybí ve Fyzionu → ověřte přes detail
* chybí u vás → doplňte
* liší se → přepište podle Fyzionu

## Úprava dokladů z integrace

* zaplacení: `PATCH {"is_paid": true}` – podle nastavení firmy zároveň vygeneruje a odešle PDF, potlačíte `{"send_email": false}`
* `PUT` přepíše všechny položky dokladu
* `DELETE` maže doklad natrvalo a posouvá číselnou řadu