Náklady

CRUD pre náklady. POST/PATCH prijíma line_items, totals dopočíta service.

Náklady (expenses) reprezentujú prijaté faktúry, bločky a iné výdavkové doklady. Sú immutable: PATCH vytvorí novú verziu, stabilný id ostane. POST/PATCH prijíma zoznam line_items a service vypočíta totals (subtotal / VAT / total).

Endpointy

Sken prijíma JPEG, PNG, WebP alebo PDF do 25 MiB. Celý multipart má najviac 26 MiB a povinnú hlavičku Content-Length; JSON metadáta majú najviac 16 KiB. Idempotency-Key je UUID malými písmenami a musí sa rovnať client_upload_id. Kľúč uchovávame 35 dní. Prvé volanie vráti 201, opakovanie 200 s rovnakým telom a Idempotent-Replayed: true. Súbežný pokus vráti 409 IDEMPOTENCY_IN_PROGRESS s Retry-After: 5; zmenený doklad alebo volajúci vráti 409 IDEMPOTENCY_KEY_REUSED. duplicate_of iba upozorňuje na zhodnú prílohu, nový náklad vznikne. Voliteľné pole platform (ios alebo android) určuje appku, ktorá sken poslala; chýbajúce znamená ios a do hashu požiadavky nepatrí. Pri API kľúči sa ignoruje. Podpísaná relácia vyžaduje x-org-slug a oprávnenie expenses.create. Oba spôsoby prihlásenia majú spoločný limit 60 skenov za minútu na používateľa a vyžadujú zapnutý native_client.enabled. Produkčné zapnutie čaká na centrálne kvóty, guard predplatného a obnovu extrakcií.

Opätovná extrakcia zopakuje len neúspešné spracovanie: vráti 202 a zaradí nový pokus. 409 CONFLICT nesie details.reason: in_progress, keď extrakcia beží, bola zaradená pred menej než 10 minútami alebo sa jej zlyhanie ešte dopisuje (skúste neskôr), a not_retryable po dokončenej extrakcii alebo pri konečnom verdikte pre tú istú prílohu (nerozpoznaný druh dokladu, zálohový ISDOC, neprečítaný QR kód bločku). Staršie zaradenie nahradí novým pokusom. 422 nesie details.reason no_attachment, attachment_unusable alebo av_rejected. Pri vyčerpanej kvóte vráti 402 QUOTA_REACHED, pri neuhradenom alebo pozastavenom predplatnom 403 SUBSCRIPTION_INACTIVE (platí aj pre sken). Podpísaná relácia vyžaduje oprávnenie expenses.update. Opätovná extrakcia zdieľa so skenom limit 60 za minútu na používateľa a vyžaduje zapnutý native_client.enabled.

Príloha k nákladu

POST /expenses a PATCH /expenses/{id} prijmú aj multipart/form-data. Časť expense nesie rovnaké JSON telo ako pri application/json (pri POST je povinná, pri PATCH voliteľná, vtedy sa mení len príloha). Časť file je práve jedna a pri multipart povinná; typ súboru sa určuje podľa obsahu (PDF, JPEG, PNG, WebP, GIF, HEIC, HEIF, AVIF, DOCX, XLSX), nie podľa hlavičky časti. Súbor má najviac 25 MiB, celé telo najviac 30 MiB (inak 413). JSON telo s kľúčom file_id spolu so súborom vráti 422. Neplatný JSON v časti expense vráti 400 VALIDATION_ERROR, nepodporovaný alebo chýbajúci súbor 422. Pri POST sa najprv overí mesačný limit nákladov (402 QUOTA_REACHED), až potom sa súbor uloží; ak zápis nákladu zlyhá, súbor sa zahodí. PATCH s nenájdeným nákladom vráti 404 ešte pred nahraním. Odstránenie prílohy ostáva JSON PATCH s file_id: null. Existujúci súbor môžeš pripojiť aj cez JSON file_id; musí to byť aktívna príloha tvojej organizácie, ktorá nevypršala a nie je v karanténe, inak 422.

Nahranie nečaká na antivírus: attachment.scan_status začína ako pending a postupuje cez scanning na clean, infected alebo error. GET /expenses/{id}/pdf súbor vráti hneď, aj kým kontrola beží; len súbor v karanténe vráti 410 FILE_QUARANTINED. Keď antivírus súbor dá do karantény, odošle sa webhook expense.attachment_quarantined (zachytia ho aj odbery expense.*) a udalosť sa zapíše do časovej osi nákladu.

Filtre pre `GET /expenses`

search - fulltext (description, number, internal_number).
category_id - filter na konkrétnu kategóriu.
contact_id - filter na dodávateľa.
status - jeden z new, processing, manual, processed, paid, failed, partially_settled. Rovnaký vypočítaný stav je v poli status. Samostatné pole payment_status a má len hodnoty paid / unpaid.
from / to - ISO 8601 dátumový rozsah nad poľom date.
page, limit - stránkovanie (default limit=20, max 100).
sort_by, sort_order - radenie (asc / desc, default desc).

POST/api/v1/expenses/scanexpenses:write

Nahrať doklad so stabilným kľúčom opakovania. Rovnaký kľúč a obsah vrátia pôvodný náklad.

Request

curl -X POST "https://monivio.sk/api/v1/expenses/scan" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 3f6c5b17-cb47-4d16-bf26-0e65740b6b75" \
  -F 'file=@receipt.png;type=image/png' \
  -F 'metadata={"client_upload_id":"3f6c5b17-cb47-4d16-bf26-0e65740b6b75","captured_at":"2026-09-26T10:00:00Z","page_count":1,"platform":"android"}'

Response 201json

{
  "data": {
    "expense_id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
    "file_id": "fil_5wpqzx9k3rt8nmlhvyc4bfsj",
    "processing_status": "queued",
    "status": "processing",
    "duplicate_of": null,
    "created_at": "2026-09-26T10:00:00.000Z"
  }
}

POST/api/v1/expensesexpenses:write

Vytvorí náklad zo zoznamu line_items. Service vypočíta amount_without_tax, amount_tax a amount_total.

Request

curl -X POST "https://monivio.sk/api/v1/expenses" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Kancelárske potreby",
  "issue_date": "2026-06-01",
  "delivery_date": "2026-05-31",
  "due_date": "2026-06-15",
  "contact_id": "con_2hf8pq3rxn4mlkzyt9abwvve",
  "currency": "EUR",
  "line_items": [
    {
      "description": "Papier A4 (250 ks)",
      "quantity": 5,
      "unit_price": 4.5,
      "vat_rate": 23
    }
  ]
}'

Response 201json

{
  "data": {
    "id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
    "number": "FA-20260612",
    "internal_number": "DF20260001",
    "series_id": "ser_expenses",
    "date": "2026-06-01T00:00:00.000Z",
    "delivery_date": "2026-05-31T00:00:00.000Z",
    "due_date": "2026-06-15T00:00:00.000Z",
    "contact": {
      "id": "con_7tnZ8wKmRvQpXjL5BcHfYsAd",
      "name": "Office Depot"
    },
    "category": {
      "id": "cat_xfzwq2hjkbpr6ny9smtv8d4l",
      "name": "Kancelárske potreby",
      "icon": null,
      "color": null
    },
    "status": "new",
    "processing_status": null,
    "failure_reason": null,
    "source": "manual",
    "has_attachment": true,
    "file_id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
    "file_page_count": 1,
    "currency": "EUR",
    "base_currency": "EUR",
    "amount_without_tax": 22.5,
    "amount_tax": 5.18,
    "amount_tax_deductible": 5.18,
    "vat_deduction_percent": 100,
    "vat_deduction_reason": "full",
    "vat_regime": "domestic",
    "self_assessment_vat_rate": null,
    "vehicle_id": null,
    "amount_total": 27.68,
    "exchange_rate": 1,
    "exchange_rate_date": null,
    "exchange_rate_source": null,
    "amount_total_base": 27.68,
    "payment_status": "unpaid",
    "amount_offset": 0,
    "credit_note_state": null,
    "document_kind": "invoice",
    "description": "Papier A4 + tonery",
    "tag_ids": [
      "tag_xKZqL9bM7nT4vR8sCdHfWgYj"
    ],
    "created_at": "2026-06-01T11:24:00.000Z",
    "ai_extraction": null,
    "attachment": {
      "id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
      "filename": "papier-a4.png",
      "mime_type": "image/png",
      "size_bytes": 68,
      "page_count": 1,
      "scan_status": "clean"
    },
    "settlement": {
      "currencyCode": "EUR",
      "supplyAmounts": [
        {
          "amountBase": 100,
          "vatRate": 23,
          "vatAmount": 23,
          "amountTotal": 123
        }
      ],
      "prepaidAmount": 50,
      "amountDue": 73,
      "advanceReferences": [
        "2026001"
      ],
      "taxAmounts": [
        {
          "amountBase": 59.35,
          "vatRate": 23,
          "vatAmount": 13.65,
          "amountTotal": 73
        }
      ]
    },
    "version": 1,
    "received_at": "2026-06-01T11:24:00.000Z",
    "payment_reference": null,
    "internal_notes": null,
    "line_items": [
      {
        "description": "Papier A4 (250 ks)",
        "quantity": 5,
        "unit_price": 4.5,
        "vat_rate": 23,
        "amount": 27.68
      }
    ]
  }
}

POST/api/v1/expensesexpenses:write

Vytvorí náklad aj s prílohou jedným volaním. Multipart/form-data: časť `expense` nesie rovnaké JSON telo ako vyššie, časť `file` doklad. Príloha začína v stave scan_status pending.

Request

curl -X POST "https://monivio.sk/api/v1/expenses" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F 'file=@receipt.png;type=image/png' \
  -F 'expense={"description":"Kancelárske potreby","issue_date":"2026-06-01","delivery_date":"2026-05-31","due_date":"2026-06-15","contact_id":"con_2hf8pq3rxn4mlkzyt9abwvve","currency":"EUR","line_items":[{"description":"Papier A4 (250 ks)","quantity":5,"unit_price":4.5,"vat_rate":23}]};type=application/json'

Response 201json

{
  "data": {
    "id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
    "number": "FA-20260612",
    "internal_number": "DF20260001",
    "series_id": "ser_expenses",
    "date": "2026-06-01T00:00:00.000Z",
    "delivery_date": "2026-05-31T00:00:00.000Z",
    "due_date": "2026-06-15T00:00:00.000Z",
    "contact": {
      "id": "con_7tnZ8wKmRvQpXjL5BcHfYsAd",
      "name": "Office Depot"
    },
    "category": {
      "id": "cat_xfzwq2hjkbpr6ny9smtv8d4l",
      "name": "Kancelárske potreby",
      "icon": null,
      "color": null
    },
    "status": "new",
    "processing_status": null,
    "failure_reason": null,
    "source": "manual",
    "has_attachment": true,
    "file_id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
    "file_page_count": 1,
    "currency": "EUR",
    "base_currency": "EUR",
    "amount_without_tax": 22.5,
    "amount_tax": 5.18,
    "amount_tax_deductible": 5.18,
    "vat_deduction_percent": 100,
    "vat_deduction_reason": "full",
    "vat_regime": "domestic",
    "self_assessment_vat_rate": null,
    "vehicle_id": null,
    "amount_total": 27.68,
    "exchange_rate": 1,
    "exchange_rate_date": null,
    "exchange_rate_source": null,
    "amount_total_base": 27.68,
    "payment_status": "unpaid",
    "amount_offset": 0,
    "credit_note_state": null,
    "document_kind": "invoice",
    "description": "Papier A4 + tonery",
    "tag_ids": [
      "tag_xKZqL9bM7nT4vR8sCdHfWgYj"
    ],
    "created_at": "2026-06-01T11:24:00.000Z",
    "ai_extraction": null,
    "attachment": {
      "id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
      "filename": "receipt.png",
      "mime_type": "image/png",
      "size_bytes": 68,
      "page_count": 1,
      "scan_status": "pending"
    },
    "settlement": {
      "currencyCode": "EUR",
      "supplyAmounts": [
        {
          "amountBase": 100,
          "vatRate": 23,
          "vatAmount": 23,
          "amountTotal": 123
        }
      ],
      "prepaidAmount": 50,
      "amountDue": 73,
      "advanceReferences": [
        "2026001"
      ],
      "taxAmounts": [
        {
          "amountBase": 59.35,
          "vatRate": 23,
          "vatAmount": 13.65,
          "amountTotal": 73
        }
      ]
    },
    "version": 1,
    "received_at": "2026-06-01T11:24:00.000Z",
    "payment_reference": null,
    "internal_notes": null,
    "line_items": [
      {
        "description": "Papier A4 (250 ks)",
        "quantity": 5,
        "unit_price": 4.5,
        "vat_rate": 23,
        "amount": 27.68
      }
    ]
  }
}

GET/api/v1/expensesexpenses:read

Zoznam nákladov so stránkovaním a filtrami.

Request

curl "https://monivio.sk/api/v1/expenses?limit=10" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response 200json

{
  "data": [
    {
      "id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
      "number": "FA-20260612",
      "internal_number": "DF20260001",
      "series_id": "ser_expenses",
      "date": "2026-06-01T00:00:00.000Z",
      "delivery_date": "2026-05-31T00:00:00.000Z",
      "due_date": "2026-06-15T00:00:00.000Z",
      "contact": {
        "id": "con_7tnZ8wKmRvQpXjL5BcHfYsAd",
        "name": "Office Depot"
      },
      "category": {
        "id": "cat_xfzwq2hjkbpr6ny9smtv8d4l",
        "name": "Kancelárske potreby",
        "icon": null,
        "color": null
      },
      "status": "new",
      "processing_status": null,
      "failure_reason": null,
      "source": "manual",
      "has_attachment": true,
      "file_id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
      "file_page_count": 1,
      "currency": "EUR",
      "base_currency": "EUR",
      "amount_without_tax": 22.5,
      "amount_tax": 5.18,
      "amount_tax_deductible": 5.18,
      "vat_deduction_percent": 100,
      "vat_deduction_reason": "full",
      "vat_regime": "domestic",
      "self_assessment_vat_rate": null,
      "vehicle_id": null,
      "amount_total": 27.68,
      "exchange_rate": 1,
      "exchange_rate_date": null,
      "exchange_rate_source": null,
      "amount_total_base": 27.68,
      "payment_status": "unpaid",
      "amount_offset": 0,
      "credit_note_state": null,
      "document_kind": "invoice",
      "description": "Papier A4 + tonery",
      "tag_ids": [
        "tag_xKZqL9bM7nT4vR8sCdHfWgYj"
      ],
      "created_at": "2026-06-01T11:24:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "total_pages": 1
  }
}

GET/api/v1/expenses/{id}expenses:read

Detail nákladu vrátane line_items.

Request

curl "https://monivio.sk/api/v1/expenses/con_2hf8pq3rxn4mlkzyt9abwvve" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response 200json

{
  "data": {
    "id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
    "number": "FA-20260612",
    "internal_number": "DF20260001",
    "series_id": "ser_expenses",
    "date": "2026-06-01T00:00:00.000Z",
    "delivery_date": "2026-05-31T00:00:00.000Z",
    "due_date": "2026-06-15T00:00:00.000Z",
    "contact": {
      "id": "con_7tnZ8wKmRvQpXjL5BcHfYsAd",
      "name": "Office Depot"
    },
    "category": {
      "id": "cat_xfzwq2hjkbpr6ny9smtv8d4l",
      "name": "Kancelárske potreby",
      "icon": null,
      "color": null
    },
    "status": "new",
    "processing_status": null,
    "failure_reason": null,
    "source": "manual",
    "has_attachment": true,
    "file_id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
    "file_page_count": 1,
    "currency": "EUR",
    "base_currency": "EUR",
    "amount_without_tax": 22.5,
    "amount_tax": 5.18,
    "amount_tax_deductible": 5.18,
    "vat_deduction_percent": 100,
    "vat_deduction_reason": "full",
    "vat_regime": "domestic",
    "self_assessment_vat_rate": null,
    "vehicle_id": null,
    "amount_total": 27.68,
    "exchange_rate": 1,
    "exchange_rate_date": null,
    "exchange_rate_source": null,
    "amount_total_base": 27.68,
    "payment_status": "unpaid",
    "amount_offset": 0,
    "credit_note_state": null,
    "document_kind": "invoice",
    "description": "Papier A4 + tonery",
    "tag_ids": [
      "tag_xKZqL9bM7nT4vR8sCdHfWgYj"
    ],
    "created_at": "2026-06-01T11:24:00.000Z",
    "ai_extraction": null,
    "attachment": {
      "id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
      "filename": "papier-a4.png",
      "mime_type": "image/png",
      "size_bytes": 68,
      "page_count": 1,
      "scan_status": "clean"
    },
    "settlement": {
      "currencyCode": "EUR",
      "supplyAmounts": [
        {
          "amountBase": 100,
          "vatRate": 23,
          "vatAmount": 23,
          "amountTotal": 123
        }
      ],
      "prepaidAmount": 50,
      "amountDue": 73,
      "advanceReferences": [
        "2026001"
      ],
      "taxAmounts": [
        {
          "amountBase": 59.35,
          "vatRate": 23,
          "vatAmount": 13.65,
          "amountTotal": 73
        }
      ]
    },
    "version": 1,
    "received_at": "2026-06-01T11:24:00.000Z",
    "payment_reference": null,
    "internal_notes": null,
    "line_items": [
      {
        "description": "Papier A4 (250 ks)",
        "quantity": 5,
        "unit_price": 4.5,
        "vat_rate": 23,
        "amount": 27.68
      }
    ]
  }
}

PATCH/api/v1/expenses/{id}expenses:write

Vytvorí novú verziu (id zostáva, version+1). Stačí poslať polia, ktoré meníš.

Request

curl -X PATCH "https://monivio.sk/api/v1/expenses/con_2hf8pq3rxn4mlkzyt9abwvve" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "line_items": [
    {
      "description": "Papier A4 (500 ks)",
      "quantity": 10,
      "unit_price": 4.5,
      "vat_rate": 23
    }
  ]
}'

Response 200json

{
  "data": {
    "id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
    "number": "FA-20260612",
    "internal_number": "DF20260001",
    "series_id": "ser_expenses",
    "date": "2026-06-01T00:00:00.000Z",
    "delivery_date": "2026-05-31T00:00:00.000Z",
    "due_date": "2026-06-15T00:00:00.000Z",
    "contact": {
      "id": "con_7tnZ8wKmRvQpXjL5BcHfYsAd",
      "name": "Office Depot"
    },
    "category": {
      "id": "cat_xfzwq2hjkbpr6ny9smtv8d4l",
      "name": "Kancelárske potreby",
      "icon": null,
      "color": null
    },
    "status": "new",
    "processing_status": null,
    "failure_reason": null,
    "source": "manual",
    "has_attachment": true,
    "file_id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
    "file_page_count": 1,
    "currency": "EUR",
    "base_currency": "EUR",
    "amount_without_tax": 45,
    "amount_tax": 10.35,
    "amount_tax_deductible": 10.35,
    "vat_deduction_percent": 100,
    "vat_deduction_reason": "full",
    "vat_regime": "domestic",
    "self_assessment_vat_rate": null,
    "vehicle_id": null,
    "amount_total": 55.35,
    "exchange_rate": 1,
    "exchange_rate_date": null,
    "exchange_rate_source": null,
    "amount_total_base": 27.68,
    "payment_status": "unpaid",
    "amount_offset": 0,
    "credit_note_state": null,
    "document_kind": "invoice",
    "description": "Papier A4 + tonery",
    "tag_ids": [
      "tag_xKZqL9bM7nT4vR8sCdHfWgYj"
    ],
    "created_at": "2026-06-01T11:24:00.000Z",
    "ai_extraction": null,
    "attachment": {
      "id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
      "filename": "papier-a4.png",
      "mime_type": "image/png",
      "size_bytes": 68,
      "page_count": 1,
      "scan_status": "clean"
    },
    "settlement": {
      "currencyCode": "EUR",
      "supplyAmounts": [
        {
          "amountBase": 100,
          "vatRate": 23,
          "vatAmount": 23,
          "amountTotal": 123
        }
      ],
      "prepaidAmount": 50,
      "amountDue": 73,
      "advanceReferences": [
        "2026001"
      ],
      "taxAmounts": [
        {
          "amountBase": 59.35,
          "vatRate": 23,
          "vatAmount": 13.65,
          "amountTotal": 73
        }
      ]
    },
    "version": 2,
    "received_at": "2026-06-01T11:24:00.000Z",
    "payment_reference": null,
    "internal_notes": null,
    "line_items": [
      {
        "description": "Papier A4 (500 ks)",
        "quantity": 10,
        "unit_price": 4.5,
        "vat_rate": 23,
        "amount": 55.35
      }
    ]
  }
}

PATCH/api/v1/expenses/{id}expenses:write

Nahradí prílohu nákladu. Multipart/form-data len s časťou `file` (časť `expense` je pri PATCH voliteľná). Vznikne nová verzia, predchádzajúca verzia si ponechá pôvodný súbor.

Request

curl -X PATCH "https://monivio.sk/api/v1/expenses/con_2hf8pq3rxn4mlkzyt9abwvve" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F 'file=@receipt.png;type=image/png'

Response 200json

{
  "data": {
    "id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
    "number": "FA-20260612",
    "internal_number": "DF20260001",
    "series_id": "ser_expenses",
    "date": "2026-06-01T00:00:00.000Z",
    "delivery_date": "2026-05-31T00:00:00.000Z",
    "due_date": "2026-06-15T00:00:00.000Z",
    "contact": {
      "id": "con_7tnZ8wKmRvQpXjL5BcHfYsAd",
      "name": "Office Depot"
    },
    "category": {
      "id": "cat_xfzwq2hjkbpr6ny9smtv8d4l",
      "name": "Kancelárske potreby",
      "icon": null,
      "color": null
    },
    "status": "new",
    "processing_status": null,
    "failure_reason": null,
    "source": "manual",
    "has_attachment": true,
    "file_id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
    "file_page_count": 1,
    "currency": "EUR",
    "base_currency": "EUR",
    "amount_without_tax": 22.5,
    "amount_tax": 5.18,
    "amount_tax_deductible": 5.18,
    "vat_deduction_percent": 100,
    "vat_deduction_reason": "full",
    "vat_regime": "domestic",
    "self_assessment_vat_rate": null,
    "vehicle_id": null,
    "amount_total": 27.68,
    "exchange_rate": 1,
    "exchange_rate_date": null,
    "exchange_rate_source": null,
    "amount_total_base": 27.68,
    "payment_status": "unpaid",
    "amount_offset": 0,
    "credit_note_state": null,
    "document_kind": "invoice",
    "description": "Papier A4 + tonery",
    "tag_ids": [
      "tag_xKZqL9bM7nT4vR8sCdHfWgYj"
    ],
    "created_at": "2026-06-01T11:24:00.000Z",
    "ai_extraction": null,
    "attachment": {
      "id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
      "filename": "papier-a4.png",
      "mime_type": "image/png",
      "size_bytes": 68,
      "page_count": 1,
      "scan_status": "pending"
    },
    "settlement": {
      "currencyCode": "EUR",
      "supplyAmounts": [
        {
          "amountBase": 100,
          "vatRate": 23,
          "vatAmount": 23,
          "amountTotal": 123
        }
      ],
      "prepaidAmount": 50,
      "amountDue": 73,
      "advanceReferences": [
        "2026001"
      ],
      "taxAmounts": [
        {
          "amountBase": 59.35,
          "vatRate": 23,
          "vatAmount": 13.65,
          "amountTotal": 73
        }
      ]
    },
    "version": 3,
    "received_at": "2026-06-01T11:24:00.000Z",
    "payment_reference": null,
    "internal_notes": null,
    "line_items": [
      {
        "description": "Papier A4 (250 ks)",
        "quantity": 5,
        "unit_price": 4.5,
        "vat_rate": 23,
        "amount": 27.68
      }
    ]
  }
}

GET/api/v1/expenses/{id}/pdfexpenses:read

Stiahne pôvodný doklad priložený k nákladu, aj kým antivírusová kontrola beží. Súbor v karanténe vráti 410 FILE_QUARANTINED, bez priloženého súboru vracia 404.

Request

curl "https://monivio.sk/api/v1/expenses/con_2hf8pq3rxn4mlkzyt9abwvve/pdf" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

POST/api/v1/expenses/{id}/retry-extractionexpenses:write

Znova zaradí neúspešnú AI extrakciu dokladu priloženého k nákladu.

Request

curl -X POST "https://monivio.sk/api/v1/expenses/con_2hf8pq3rxn4mlkzyt9abwvve/retry-extraction" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response 202json

{
  "data": {
    "expense_id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
    "processing_status": "queued"
  }
}

DELETE/api/v1/expenses/{id}expenses:write

Vymaže náklad. Zachováva sa v histórii pre audit.

Request

curl -X DELETE "https://monivio.sk/api/v1/expenses/con_2hf8pq3rxn4mlkzyt9abwvve" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Objekt Expense (detail)

idreadonly

string

Stabilné CUID2 ID s prefixom exp_.

Príklad: exp_5wpqzx9k3rt8nmlhvyc4bfsj

versionreadonly

number

Verzia - PATCH zvyšuje. Stará verzia ostane v histórii.

number

string/ null

Číslo prijatej faktúry (ako ti ho dodávateľ pridelil). Pri POST a PATCH voliteľné.

Príklad: FA-20260612

descriptionrequired

string

Krátky popis nákladu (1-500 znakov).

Príklad: Papier A4 + tonery

issue_daterequired

string (ISO 8601)

Iba pri zápise - dátum vystavenia. V odpovedi sa vracia ako date.

Príklad: 2026-06-01

datereadonly

string (ISO 8601)

Dátum vystavenia v odpovedi (ISO 8601 datetime). Pri zápise sa posiela pod kľúčom issue_date.

Príklad: 2026-06-01T00:00:00.000Z

delivery_date

string (ISO 8601)

Dátum dodania (daňový bod). Určuje, do ktorého účtovného obdobia náklad patrí. V zápise voliteľný - ak ho neposielaš, uloží sa dátum vystavenia.

Príklad: 2026-05-31T00:00:00.000Z

due_date

string (ISO 8601)/ null

Splatnosť faktúry.

Príklad: 2026-06-15T00:00:00.000Z

received_at

string (ISO 8601)/ null

Kedy si doklad prijal (default = teraz pri POST). Voliteľné v body POST/PATCH.

contact_id

string/ null

Iba pri zápise - ID dodávateľa (kontaktu). V odpovedi sa vracia ako objekt contact.

Príklad: con_7tnZ8wKmRvQpXjL5BcHfYsAd

contactreadonly

{ id, name } | null

Dodávateľ - kontakt v tvojej databáze.

category_id

string/ null

Iba pri zápise - ID kategórie. V odpovedi sa vracia ako objekt category.

categoryreadonly

{ id, name, icon, color } | null

Kategória nákladu (z /categories?type=expense).

currency

string (ISO 4217)

Mena nákladu. 3-písmenový ISO 4217 kód. Default EUR.

Príklad: EUR

exchange_rate

number

Voliteľný ručný kurz pri zápise: počet jednotiek meny nákladu za 1 jednotku meny organizácie. Ak ho vynecháte, server použije referenčný kurz ECB/NBS. V odpovedi je použitý snapshot kurzu.

exchange_rate_datereadonly

string (YYYY-MM-DD)/ null

Dátum použitého kurzu. NULL pri náklade v mene organizácie.

exchange_rate_sourcereadonly

"ecb" | "nbs" | "manual"/ null

Zdroj uloženého kurzu. NULL pri náklade v mene organizácie.

base_currencyreadonly

string/ null

Snapshot meny organizácie, v ktorej je amount_total_base.

vat_rate_id

string/ null

Iba pri zápise - ID konkrétnej VAT rate konfigurácie (pre režimy odpočtu DPH).

is_vat_deductible

boolean

Iba pri zápise - či je DPH odpočítateľná. Staršia forma poľa vat_deduction_reason: false alebo vynechané pole znamená bez odpočtu (predvolené), true nechá odpočet na automatiku (plný, ak ho kategória ani vozidlo neobmedzujú). Keď prídu obe polia, platí vat_deduction_reason.

vat_deduction_reason

string

Režim odpočtu DPH: full (100 %), vehicle_mixed (osobné auto používané aj súkromne, 50 % podľa §85n), vehicle_exclusive (auto len na podnikanie, 100 %), business_use (podľa rozsahu použitia, §49 ods. 5, vyžaduje vat_deduction_percent), hospitality (pohostenie, 0 %), not_claimed (0 %). Pri zápise bez režimu a s is_vat_deductible: true určí odpočet automatika podľa kategórie a vozidla.

vat_deduction_percent

number

Percento odpočtu DPH, 0 až 100. Pri zápise povinné len s režimom business_use, ostatné režimy majú pevné percento.

amount_tax_deductiblereadonly

number

Odpočítateľná časť DPH, teda nárok na odpočet podľa zákona o DPH: slovenská DPH dokladu krát vat_deduction_percent, určená pri uložení. DPH zahraničného dodávateľa (IČ DPH s inou predponou ako SK) a DPH so sadzbou, ktorá ku dňu dodania nie je slovenská (napríklad české 21 %), sa neodpočítava, takže pri zahraničnom doklade je 0 aj pri 100 %. O dani z príjmov nehovorí: DPH neodpočítaná podľa §85n nie je daňový výdavok.

vat_regime

string

Režim DPH nákladu: domestic (tuzemský nákup, predvolené), reverse_charge_services (samozdanenie služby zo zahraničia). Vo výstupe môžu prísť aj ďalšie hodnoty (reverse_charge_domestic, eu_goods_acquisition, import, out_of_scope) a v budúcnosti nové, klient ich má tolerovať. Odoslaná hodnota je voľba klienta a automatika ju už neprepíše, aj keď je rovnaká ako načítaná; vynechané pole nechá režim na dodávateľa alebo doklad.

vat_regime_automatic

boolean

true vráti režim určený klientom späť automatike (predvolený režim dodávateľa, inak tuzemský nákup).

self_assessment_vat_rate

number/ null

Sadzba samozdanenia pri režime reverse_charge_services. Na novom náklade vynechaná alebo null znamená základnú sadzbu platnú v deň dodania; pri úprave vynechaná ostáva, null ju nastaví na základnú. Dobropis a ťarchopis majú sadzbu opravovaného nákladu. DPH na doklade ostáva nulová.

vehicle_id

string/ null

Vozidlo z knihy jázd, ku ktorému náklad patrí. Určuje odpočet pri režimoch auta.

amount_without_taxreadonly

number

Subtotal pred DPH (vypočítané z line_items).

amount_taxreadonly

number

Suma DPH (vypočítané z line_items).

amount_totalreadonly

number

Celková suma s DPH (vypočítané z line_items).

amount_total_basereadonly

number/ null

Celková suma prepočítaná do meny organizácie delením kurzom.

internal_numberreadonly

string/ null

Interné číslo nákladu pridelené systémom pri zaevidovaní. Oddelené od čísla dodávateľa. Pri nedokončenom skene môže byť prázdne.

series_idreadonly

string/ null

Stabilné ID nákladového číselného radu. Zoznam radov poskytuje GET /api/v1/series s typom expense.

document_kind

"invoice" | "credit_note" | "debit_note" | "receipt" | "other"

Druh prijatého dokladu. Predvolene invoice. Dobropis (credit_note) má záporné sumy a musí uvádzať, čo opravuje - buď source_expense_id, alebo corrected_number.

source_expense_id

string | null

ID opravovaného nákladu. Len pri credit_note a debit_note.

corrected_number

string | null

Číslo pôvodného dokladu, keď opravovaný náklad nie je v systéme. Nedá sa kombinovať so source_expense_id.

correction_reason

string | null

Dôvod opravy podľa § 74 ods. 4 ZoDPH.

payment_statusreadonly

"paid" | "unpaid"

Stav úhrady nezávislý od spracovania.

amount_offsetreadonly

number

Suma vyrovnaná zápočtom dobropisu, bez platby. Pri faktúre súčet zápočtov jej prijatých dobropisov, pri dobropise jeho časť započítaná s faktúrou. Inak 0.

credit_note_statereadonly

"offset" | "awaiting_refund" | "refunded" | null

Len pri prijatom dobropise, inak null. offset: celý započítaný s faktúrou, awaiting_refund: zvyšok čaká na vrátenie od dodávateľa, refunded: zvyšok bol vrátený alebo označený ako vyrovnaný.

statusreadonly

string

Vypočítaný stav nákladu. Zhoduje sa s filtrom status.

processing_statusreadonly

string | null

Stav spracovania prílohy alebo null pri ručnom náklade.

failure_reasonreadonly

"av_rejected" | "extraction_failed" | null

Dôvod zlyhania spracovania odvodený zo stavu prílohy.

sourcereadonly

string

Zdroj vytvorenia nákladu.

has_attachmentreadonly

boolean

Náklad odkazuje na aktívnu prílohu.

file_page_countreadonly

number | null

Počet strán prílohy, ak je známy.

ai_extractionreadonly

{ fields: { [field]: { confidence } } } | null

Iba detail. Dôvera extrahovaných polí 0 až 100 bez ich hodnôt.

attachmentreadonly

{ id, filename, mime_type, size_bytes, page_count, scan_status } | null

Iba detail. Príloha nákladu, null bez súboru. scan_status je pending, scanning, clean, infected alebo error.

payment_reference

string/ null

Variabilný symbol / referencia pre úhradu.

internal_notes

string/ null

Interné poznámky (max 5000 znakov).

file_id

string/ null

ID priloženého súboru (PDF/JPG/PNG). Stiahnuteľný cez /expenses/{id}/pdf.

tag_ids

string[]

Pripnuté tagy (max 20). Voliteľné pri zápise, vždy v odpovedi.

line_itemsrequired

LineItem[]

Položky: description, quantity, unit_price, vat_rate (0-100). V odpovedi sa pridáva aj amount. Min 1, max 100 položiek.

total

number

Celková suma s DPH tak, ako je vytlačená na doklade. Dodávateľ počíta DPH zhora z hrubej ceny, my zdola zo základu, a tie dve zaokrúhlenia sa vedia líšiť o cent. Keď total pošlete, platí suma z dokladu a rozdiel sa premietne do DPH, nikdy do základu ani do položiek. Tolerancia je jeden cent na každú sadzbu DPH na doklade; väčší rozdiel skončí ako 422. Vynechané: suma sa dopočíta z položiek ako doteraz.

created_atreadonly

string (ISO 8601)

Kedy bol náklad prvýkrát vytvorený.

Endpointy

Príloha k nákladu

Filtre pre GET /expenses

Objekt Expense (detail)

Filtre pre `GET /expenses`