monivio
Skúsiť

Dokumenty

Faktúry, ponuky, zálohové faktúry, objednávky, dobropisy, dodacie listy a drafty. PDF + odoslanie emailom.

Univerzálny endpoint pre všetky obchodné dokumenty: faktúry, ponuky, zálohové faktúry, objednávky, dobropisy, dodacie listy a drafty. Dokumenty sú immutable - PATCH vytvorí novú verziu, history zostáva. Pri vytvorení sa automaticky priradí poradové číslo z aktívneho číselného radu.

Typy dokumentov

Field type riadi celý lifecycle a ovplyvňuje validačné pravidlá. Povolené hodnoty: invoice, quote, proforma, order, credit_note, delivery_note, draft. Detail ku každému typu nájdeš v Reference → Typy dokumentov.

Query parametre pre GET /documents

  • • type - filter na konkrétny typ (invoice / quote / proforma / order / credit_note / delivery_note / draft / advance_tax_document). Daňový doklad k prijatej platbe (advance_tax_document) sa cez API len číta.
  • • status - filter na stav dokumentu (open, sent, paid, cancelled, ...).
  • • contact_id - filter na konkrétneho kontakta.
  • • search - fulltext (number, contact name, ...).
  • • from / to - range nad issue_date (ISO 8601).
  • • sort_order - asc alebo desc nad issue_date. Default desc (najnovšie prvé).
  • • page, limit - stránkovanie (default page=1, limit=20, max limit=100).

Endpointy

GET/api/v1/documentsdocuments:read

Zoznam dokumentov so stránkovaním a filtrami.

Request
curl "https://monivio.sk/api/v1/documents?type=invoice&status=open&limit=5&sort_order=desc" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 200json
{
  "data": [
    {
      "id": "doc_4kp9mxn8tq3vyz2lwbcr5shg",
      "version": 1,
      "type": "invoice",
      "status": "open",
      "number": "FA260042",
      "contact_id": "con_2hf8pq3rxn4mlkzyt9abwvve",
      "issue_date": "2026-06-01",
      "due_date": "2026-06-15",
      "currency": "EUR",
      "amount_without_tax": 415,
      "amount_tax": 80,
      "amount_total": 495,
      "payment_reference": "260042",
      "created_at": "2026-06-01T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 5,
    "total": 1,
    "total_pages": 1
  }
}
POST/api/v1/documentsdocuments:write

Vytvorí dokument zo zoznamu line_items. Service vypočíta amount_without_tax, amount_tax a amount_total. Číslo sa pridelí z aktívnej série pre daný type.

Request
curl -X POST "https://monivio.sk/api/v1/documents" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "invoice",
  "contact_id": "con_2hf8pq3rxn4mlkzyt9abwvve",
  "issue_date": "2026-06-01",
  "tax_date": "2026-06-01",
  "due_date": "2026-06-15",
  "currency": "EUR",
  "payment_terms_days": 14,
  "line_items": [
    {
      "name": "Konzultácia",
      "quantity": 8,
      "unit": "h",
      "unit_price": 50,
      "tax_rate": 23
    },
    {
      "name": "Doprava",
      "quantity": 1,
      "unit_price": 15,
      "tax_rate": 0
    }
  ]
}'
Response 201json
{
  "data": {
    "id": "doc_4kp9mxn8tq3vyz2lwbcr5shg",
    "version": 1,
    "type": "invoice",
    "status": "open",
    "number": "FA260042",
    "contact_id": "con_2hf8pq3rxn4mlkzyt9abwvve",
    "issue_date": "2026-06-01",
    "due_date": "2026-06-15",
    "currency": "EUR",
    "amount_without_tax": 415,
    "amount_tax": 80,
    "amount_total": 495,
    "payment_reference": "260042",
    "created_at": "2026-06-01T10:00:00.000Z",
    "delivery_date": null,
    "valid_until": null,
    "exchange_rate": 1,
    "exchange_rate_date": null,
    "exchange_rate_source": null,
    "base_currency": "EUR",
    "amount_total_base": 495,
    "amount_tax_base": 80,
    "contact_snapshot": {
      "name": "ACME s.r.o.",
      "email": "info@acme.sk",
      "company_name": "ACME s.r.o.",
      "company_id": "12345678",
      "tax_id": "2023456789",
      "vat_id": "SK2023456789",
      "street": "Hlavná 12",
      "city": "Bratislava",
      "postal_code": "81101",
      "country": "SK"
    },
    "source_document_id": null,
    "public_token": "pub_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
    "tag_ids": [],
    "updated_at": "2026-06-01T10:00:00.000Z"
  }
}
GET/api/v1/documents/{id}documents:read

Detail jedného dokumentu (najnovšia verzia).

Request
curl "https://monivio.sk/api/v1/documents/con_2hf8pq3rxn4mlkzyt9abwvve" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 200json
{
  "data": {
    "id": "doc_4kp9mxn8tq3vyz2lwbcr5shg",
    "version": 1,
    "type": "invoice",
    "status": "open",
    "number": "FA260042",
    "contact_id": "con_2hf8pq3rxn4mlkzyt9abwvve",
    "issue_date": "2026-06-01",
    "due_date": "2026-06-15",
    "currency": "EUR",
    "amount_without_tax": 415,
    "amount_tax": 80,
    "amount_total": 495,
    "payment_reference": "260042",
    "created_at": "2026-06-01T10:00:00.000Z",
    "delivery_date": null,
    "valid_until": null,
    "exchange_rate": 1,
    "exchange_rate_date": null,
    "exchange_rate_source": null,
    "base_currency": "EUR",
    "amount_total_base": 495,
    "amount_tax_base": 80,
    "contact_snapshot": {
      "name": "ACME s.r.o.",
      "email": "info@acme.sk",
      "company_name": "ACME s.r.o.",
      "company_id": "12345678",
      "tax_id": "2023456789",
      "vat_id": "SK2023456789",
      "street": "Hlavná 12",
      "city": "Bratislava",
      "postal_code": "81101",
      "country": "SK"
    },
    "source_document_id": null,
    "public_token": "pub_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
    "tag_ids": [],
    "updated_at": "2026-06-01T10:00:00.000Z"
  }
}
PATCH/api/v1/documents/{id}documents:write

Vytvorí novú verziu dokumentu (id zostáva, version+1). Ak pošleš line_items, totals sa prepočítajú. Type sa nedá zmeniť.

Request
curl -X PATCH "https://monivio.sk/api/v1/documents/con_2hf8pq3rxn4mlkzyt9abwvve" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "due_date": "2026-06-30",
  "line_items": [
    {
      "name": "Konzultácia - upravená sadzba",
      "quantity": 8,
      "unit": "h",
      "unit_price": 60,
      "tax_rate": 23
    }
  ]
}'
Response 200json
{
  "data": {
    "id": "doc_4kp9mxn8tq3vyz2lwbcr5shg",
    "version": 2,
    "type": "invoice",
    "status": "open",
    "number": "FA260042",
    "contact_id": "con_2hf8pq3rxn4mlkzyt9abwvve",
    "issue_date": "2026-06-01",
    "due_date": "2026-06-30",
    "currency": "EUR",
    "amount_without_tax": 480,
    "amount_tax": 110.4,
    "amount_total": 590.4,
    "payment_reference": "260042",
    "created_at": "2026-06-01T10:00:00.000Z",
    "delivery_date": null,
    "valid_until": null,
    "exchange_rate": 1,
    "exchange_rate_date": null,
    "exchange_rate_source": null,
    "base_currency": "EUR",
    "amount_total_base": 590.4,
    "amount_tax_base": 110.4,
    "contact_snapshot": {
      "name": "ACME s.r.o.",
      "email": "info@acme.sk",
      "company_name": "ACME s.r.o.",
      "company_id": "12345678",
      "tax_id": "2023456789",
      "vat_id": "SK2023456789",
      "street": "Hlavná 12",
      "city": "Bratislava",
      "postal_code": "81101",
      "country": "SK"
    },
    "source_document_id": null,
    "public_token": "pub_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
    "tag_ids": [],
    "updated_at": "2026-06-05T08:42:11.000Z"
  }
}
GET/api/v1/documents/{id}/pdfdocuments:read

Stiahne dokument ako PDF. Ak ešte nebolo vygenerované, server ho vytvorí inline (Gotenberg). Vracia binárne PDF s Content-Disposition: attachment.

Request
curl "https://monivio.sk/api/v1/documents/con_2hf8pq3rxn4mlkzyt9abwvve/pdf" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GET/api/v1/documents/{id}/einvoice/xmldocuments:read

Stiahne e-faktúru dokumentu ako Peppol BIS Billing 3.0 UBL XML. Vytvára sa a kontroluje pri uložení faktúry alebo dobropisu pre firmu so slovenským DIČ. Hlavička X-Einvoice-Valid hovorí, či XML prešlo kontrolou pravidiel Peppol. Pre doklady, ktoré e-faktúrou nie sú, vráti 404.

Request
curl "https://monivio.sk/api/v1/documents/con_2hf8pq3rxn4mlkzyt9abwvve/einvoice/xml" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GET/api/v1/documents/{id}/einvoicedocuments:read

Stav odovzdania dokladu epoštárovi: kedy je naplánované, kedy ho epoštár prevzal a kedy sa doklad zamkol. Odpovedá pre každý doklad - ten, ktorý e-faktúrou nikdy nebude, má status not_applicable.

Request
curl "https://monivio.sk/api/v1/documents/con_2hf8pq3rxn4mlkzyt9abwvve/einvoice" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Response 200json
{
  "data": {
    "document_id": "doc_4kp9mxn8tq3vyz2lwbcr5shg",
    "status": "scheduled",
    "scheduled_at": "2026-06-03T10:00:00.000Z",
    "locked_at": null,
    "provider_code": "verteco",
    "provider_message_id": null,
    "submitted_at": null,
    "delivered_at": null,
    "accepted_at": null,
    "fs_reported_at": null,
    "error": null
  }
}
POST/api/v1/documents/{id}/einvoicedocuments:write

Odovzdá doklad epoštárovi. send: "now" preskočí čakaciu lehotu z nastavení, send: "scheduled" naplánuje odovzdanie podľa nich. Volanie je idempotentné - doklad, ktorý epoštár už má, vráti 200 s aktuálnym stavom. Dôvod odmietnutia je v error.details.reason.

Request
curl -X POST "https://monivio.sk/api/v1/documents/con_2hf8pq3rxn4mlkzyt9abwvve/einvoice" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "send": "scheduled"
}'
Response 200json
{
  "data": {
    "document_id": "doc_4kp9mxn8tq3vyz2lwbcr5shg",
    "status": "scheduled",
    "scheduled_at": "2026-06-03T10:00:00.000Z",
    "locked_at": null,
    "provider_code": "verteco",
    "provider_message_id": null,
    "submitted_at": null,
    "delivered_at": null,
    "accepted_at": null,
    "fs_reported_at": null,
    "error": null
  }
}
DELETE/api/v1/documents/{id}/einvoicedocuments:write

Zruší naplánované odovzdanie, kým doklad neodišiel. Keď ho epoštár už má, opravou je dobropis - vtedy vráti 409 s reason already_submitted.

Request
curl -X DELETE "https://monivio.sk/api/v1/documents/con_2hf8pq3rxn4mlkzyt9abwvve/einvoice" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
POST/api/v1/documents/{id}/senddocuments:write

Pošle dokument emailom (PDF v prílohe). Funguje pre invoice, proforma, credit_note, quote a delivery_note. Predmet a telo môžeš overridnúť.

Request
curl -X POST "https://monivio.sk/api/v1/documents/con_2hf8pq3rxn4mlkzyt9abwvve/send" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "to": [
    "odberatel@firma.sk"
  ],
  "cc": [
    "uctaren@nasa-firma.sk"
  ],
  "change_status": true
}'
Response 200json
{
  "data": {
    "email_log_ids": [
      "eml_8kHt3pX9bN2vRyM6sCdQfWgYjE5uZaQT"
    ],
    "status_updated": true
  }
}
DELETE/api/v1/documents/{id}documents:write

Vymaže dokument. Faktúry označené ako sent/paid zostávajú v daňovej histórii.

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

Objekt Document

idreadonly
string
Stabilné CUID2 ID s prefixom doc_.
Príklad: doc_4kp9mxn8tq3vyz2lwbcr5shg
versionreadonly
number
Verzia dokumentu. Pri každom PATCH-i sa zvýši o 1, pôvodná verzia ostáva v histórii.
typerequired
"invoice" | "quote" | "proforma" | "order" | "credit_note" | "delivery_note" | "draft"
Typ dokumentu. Povinný pri vytváraní (POST), nemení sa pri PATCH.
statusreadonly
"open" | "completed" | "confirmed" | "sent" | "partially_paid" | "paid" | "cancelled" | "uncollectible" | "approved" | "rejected" | "expired" | "delivered" | "converted"
Aktuálny stav dokumentu. Riadi sa lifecyklom - API ho meníš cez samostatné akcie (send, mark-paid, ...). Pozri Reference → Statusy.
Príklad: open
numberreadonly
string/ null
Poradové číslo z aktívnej série (napr. FA260042). Drafty môžu mať null.
contact_id
string/ null
ID existujúceho kontaktu. Snapshot kontaktu sa odfotí pri vytvorení a nemení sa s úpravami kontaktu.
contact
object
Iba pri zápise - snapshot kontaktu poslaný v body, ktorý sa odfotí na dokument. Polia: name (povinné), email, company_name, company_id, tax_id, vat_id, street, city, postal_code, country (ISO 3166-1 alpha-2). Použi keď nechceš ukladať kontakt do CRM.
contact_snapshotreadonly
object/ null
Statická kópia kontaktu zachytená pri vytvorení dokumentu (rovnaké polia ako contact pri zápise). Aj keď zmeníš zdrojový kontakt, snapshot na dokumente ostáva pôvodný.
series_id
string/ null
Iba pri zápise - voliteľné ID konkrétnej číselnej série. Bez neho sa použije aktívna séria pre daný type.
issue_date
string (YYYY-MM-DD)/ null
Dátum vystavenia.
due_date
string (YYYY-MM-DD)/ null
Dátum splatnosti. Pri faktúrach povinný; ak ho nepošleš, vyrátame z payment_terms_days.
delivery_date
string (YYYY-MM-DD)/ null
DUZP / dátum dodania.
valid_until
string (YYYY-MM-DD)/ null
Platnosť ponuky - relevantné pre type=quote.
currency
string (ISO 4217)
Mena dokumentu (EUR, USD, ...). Default EUR.
exchange_rate
number/ null
Voliteľný ručný kurz pri zápise a použitý kurz pri čítaní. Udáva počet jednotiek meny dokumentu za 1 jednotku meny organizácie. Použije sa na výpočet amount_total_base.
exchange_rate_datereadonly
string (YYYY-MM-DD)/ null
Dátum uloženého referenčného alebo ručného kurzu.
exchange_rate_sourcereadonly
string/ null
Zdroj uloženého kurzu: ecb, nbs alebo manual.
language
string (2 znaky)
Iba pri zápise - jazyk PDF a šablóny emailu (sk, en, de, ...). Default sk.
amount_without_taxreadonly
number
Subtotal pred DPH (vypočíta service z line_items).
amount_taxreadonly
number
Súčet DPH naprieč všetkými line_items.
amount_totalreadonly
number
Celková suma s DPH.
base_currencyreadonly
string (ISO 4217)/ null
Mena uložených základných súm. Pri historických dokladoch môže byť neznáma.
amount_total_basereadonly
number/ null
amount_total prerátaný do meny organizácie delením cez exchange_rate.
amount_tax_basereadonly
number/ null
amount_tax prerátaný do meny organizácie delením cez exchange_rate.
payment_reference
string/ null
Variabilný symbol. Pri zápise voliteľný - ak ho nepošleš, použije sa number.
specific_symbol
string/ null
Iba pri zápise - špecifický symbol pre slovenské/české bankové platby.
payment_terms_days
number/ null
Iba pri zápise - počet dní splatnosti (0-365). Použije sa na výpočet due_date ak nie je explicitne poslaný.
bank_account_ids
string[]
Iba pri zápise - pole ID bankových účtov (max 10), ktoré sa odfotia na dokument ako platobné údaje na PDF.
note_before_items
string/ null
Iba pri zápise - poznámka pred zoznamom položiek (max 2000 znakov), tlačí sa na PDF.
note_after_items
string/ null
Iba pri zápise - poznámka pod zoznamom položiek (max 2000 znakov), tlačí sa na PDF (typicky text "Ďakujeme za nákup" alebo platobné inštrukcie).
tag_ids
string[]
Pripnuté tagy (max 20). Pri zápise pošleš ID tagov, v odpovedi sa vrátia v poli tag_ids.
source_document_id
string/ null
ID zdrojového dokumentu pri konverzii (napr. invoice vznikol z proforma alebo quote). Slúži na sledovanie reťazca.
public_tokenreadonly
string/ null
Token pre verejný link na dokument (pub_...). Generuje sa pri vytvorení.
line_items
object[]
Iba pri zápise - pole položiek (1-200). Každá obsahuje name (povinné), quantity, unit_price, tax_rate a voliteľne description, unit, discount, catalog_item_id.
created_atreadonly
string (ISO 8601)
Kedy bol dokument prvýkrát vytvorený.
updated_atreadonly
string (ISO 8601)
Posledná zmena - pri PATCH-i sa updatne.