# Instrumente MCP
> Fiecare instrument al serverului MCP, după drept: ce face, argumentele sale și un exemplu de apel.
>
> Înainte: [Conectați un asistent](https://ocost.io/docs/ro/mcp.md)

Fiecare instrument al serverului MCP, scris din propriile definiții. [Conectați un asistent](https://ocost.io/docs/ro/mcp.md) configurează serverul. Un asistent citește descrierea completă a fiecărui instrument în `tools/list`. Descrierile argumentelor sunt acolo în engleză, ca aici.

## `documents:read`

### `get_document`

Citește un document ca `ocost.document.v1`, la fel ca `GET /public/v1/documents/{document_id}`.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `document_id` | uuid, obligatoriu | An id Ocost gave (a UUID) |

```json
{
  "name": "get_document",
  "arguments": {
    "document_id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11"
  }
}
```

### `get_file`

Returnează starea, motivul și documentele unui fișier, la fel ca `GET /public/v1/files/{file_id}`.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `file_id` | uuid, obligatoriu | An id Ocost gave (a UUID) |

```json
{
  "name": "get_file",
  "arguments": {
    "file_id": "01a1b08c-6e3a-7562-8f4a-7924722667b1"
  }
}
```

### `list_files`

Listează fișierele după ultima modificare, cele mai vechi primele, la fel ca `GET /public/v1/files`.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `status` | listă de `received`, `reading`, `read`, `not_read`, `failed`, `needs_company` | Only files in these statuses |
| `updated_since` | date-time | Files changed at or after this time (ISO 8601) |
| `external_ref` | string | Only the files carrying this id of yours among their external_refs |
| `cursor` | string | `next_cursor` of the page before |
| `limit` | integer 1–100, implicit `50` | Fișiere pe pagină. |

```json
{
  "name": "list_files",
  "arguments": {
    "status": ["read", "not_read", "failed"],
    "updated_since": "2026-11-09T08:00:00Z"
  }
}
```

### `read_document`

Citește paginile unui document ca text, până la 4 pagini și 12.000 de caractere.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `document_id` | uuid, obligatoriu | Id-ul unui document. |
| `pages` | listă de integer | Numerele paginilor din fișier de citit. |

```json
{
  "name": "read_document",
  "arguments": {
    "document_id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11",
    "pages": [1, 2]
  }
}
```

### `find_documents`

Listează documentele, cele mai noi primele, după tip, familie sau companie.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `kind` | `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (valori: 82) | Un tip de document, așa cum îl listează `kind_detail` în [Valori](https://ocost.io/docs/ro/document.md#valori). |
| `company_id` | uuid | Id-ul unei companii, din `find_company`. |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | Un grup de tipuri, precum `invoices` sau `contracts`. |

```json
{
  "name": "find_documents",
  "arguments": {
    "kind": "credit_note",
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `find_contracts`

Listează contractele cu durata, preavizul și sumele recurente.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `company_id` | uuid | Id-ul unei companii, din `find_company`. |

```json
{
  "name": "find_contracts",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `find_company`

Găsește furnizori și clienți după nume, cu id-urile lor.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `name` | string, implicit `""` | O parte din nume. Fără el, se listează toate. |
| `country` | string | Doar companiile cu adresa principală în această țară (ISO 3166-1 alpha-2, `DE`). |
| `relation` | `supplier`, `customer` | Doar furnizori sau doar clienți. |

```json
{
  "name": "find_company",
  "arguments": {
    "name": "Musterbüro"
  }
}
```

### `find_project`

Găsește proiecte după nume, cu id-urile lor.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `name` | string, implicit `""` | O parte din nume. Fără el, se listează toate. |

```json
{
  "name": "find_project",
  "arguments": {
    "name": "Neubau"
  }
}
```

### `company_documents`

Listează documentele unei companii în ambele direcții, până la 30.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `company_id` | uuid, obligatoriu | Id-ul unei companii, din `find_company`. |

```json
{
  "name": "company_documents",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `invoice_detail`

Arată o factură așa cum o arată pagina ei din Ocost: sume, scadență, discount, comandă și istoric.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `invoice_id` | uuid, obligatoriu | Id-ul unei facturi. |

```json
{
  "name": "invoice_detail",
  "arguments": {
    "invoice_id": "01a1b08c-8c3d-7f41-a2b5-3e4f5a6b7c8d"
  }
}
```

### `open_decisions`

Listează deciziile deschise ale persoanei conectate, cele scadente primele.

Doar printr-o conexiune OAuth, ca persoana care a permis-o.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `company_id` | uuid | Id-ul unei companii, din `find_company`. |
| `project_id` | uuid | Id-ul unui proiect, din `find_project`. |

```json
{
  "name": "open_decisions",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `check_invoice`

Verifică facturile de furnizor față de § 14 UStG și dacă fiecare este o factură electronică.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `document_ids` | listă de uuid | Facturile de verificat, după id-urile lor. |
| `company_id` | uuid | Id-ul unei companii, din `find_company`. |
| `issued_since` | date | Data emiterii, de la. |
| `issued_until` | date | Data emiterii, până la. |
| `only_missing` | boolean, implicit `false` | Doar facturile cărora le lipsește ceva. |
| `title` | string | Titlul tabelului. |

```json
{
  "name": "check_invoice",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c",
    "issued_since": "2026-01-01",
    "only_missing": true
  }
}
```

## `documents:write`

### `send_file`

Trimite un fișier ca base64, la fel ca `POST /public/v1/files`.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `filename` | string, obligatoriu | Its name, e.g. bill.pdf |
| `content_base64` | string, obligatoriu | The file's bytes in base64: a PDF, an image (JPEG, PNG, TIFF, WebP), a Word file (.docx, .doc) or an e-invoice's XML (XRechnung, UBL, CII), at most 25 MB |
| `external_ref` | string | Your own id for it, e.g. an Odoo bill's 'account.move,42'; kept and given back, beside the ones sent with the same bytes before |

```json
{
  "name": "send_file",
  "arguments": {
    "filename": "invoice.pdf",
    "content_base64": "JVBERi0xLjcK…",
    "external_ref": "account.move,42"
  }
}
```

## `search:read`

### `search_documents`

Caută în ce spun documentele, după textul exact, cuvinte-cheie, sens sau ambele.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `query` | string, obligatoriu | Ce se caută. |
| `match` | `exact`, `keywords`, `meaning`, `hybrid`, implicit `"hybrid"` | `exact` așa cum este scris, `keywords` după cuvinte, `meaning` după sens, `hybrid` ambele. |
| `document_id` | uuid | Căutați doar în acest document. |
| `kinds` | listă de `acceptance_protocol`, `agreement`, `bonus_payment_notification`, … (valori: 82) | Doar aceste tipuri de documente, așa cum le listează `kind_detail` în [Valori](https://ocost.io/docs/ro/document.md#valori). |
| `family` | `invoices`, `payments`, `buying`, `contracts`, `reports`, `people`, `other` | Un grup de tipuri, precum `invoices` sau `contracts`. |
| `company_id` | uuid | Id-ul unei companii, din `find_company`. |
| `project_id` | uuid | Id-ul unui proiect, din `find_project`. |
| `site_id` | uuid | Id-ul unei locații. |
| `issued_since` | date | Data emiterii, de la. |
| `issued_until` | date | Data emiterii, până la. |
| `due_since` | date | Data scadenței unei facturi, de la. |
| `due_until` | date | Data scadenței unei facturi, până la. |
| `gross_min` | zecimal | Suma brută de la, în moneda firmei. |
| `gross_max` | zecimal | Suma brută până la, în moneda firmei. |
| `direction` | `incoming`, `outgoing` | `incoming` de la furnizori, `outgoing` către clienți. |
| `status` | `open`, `paid` | Al unei facturi: `open` sau `paid`. |
| `category` | string | Un cod ECLASS de orice nivel, din `find_category`. |
| `limit` | integer | Câte rânduri cel mult. |
| `title` | string | Titlul tabelului. |

```json
{
  "name": "search_documents",
  "arguments": {
    "query": "Bürostuhl",
    "match": "hybrid",
    "kinds": ["invoice"],
    "issued_since": "2026-01-01"
  }
}
```

### `search`

Caută documente pentru deep research și cunoștințele companiei din ChatGPT.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `query` | string, obligatoriu | What to find |

```json
{
  "name": "search",
  "arguments": {
    "query": "Wartungsvertrag Aufzug"
  }
}
```

### `fetch`

Aduce un rezultat `search` întreg: primele patru pagini, până la 12.000 de caractere.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `id` | string, obligatoriu | A result's id |

```json
{
  "name": "fetch",
  "arguments": {
    "id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11"
  }
}
```

## `figures:read`

### `find_category`

Transformă cuvinte din oricare dintre limbile Ocost în coduri ECLASS.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `words` | string, obligatoriu | Cuvinte pentru o categorie, în oricare dintre limbile Ocost. |

```json
{
  "name": "find_category",
  "arguments": {
    "words": "Büromaterial"
  }
}
```

### `company_profile`

Rezumă ultimele 12 luni ale unei companii: cumpărat, vândut, condiții, sume deschise și termene de plată.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `company_id` | uuid, obligatoriu | Id-ul unei companii, din `find_company`. |

```json
{
  "name": "company_profile",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

### `project_overview`

Compară planul unui proiect cu ce s-a cheltuit și angajat, pe furnizor și lună.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `project_id` | uuid, obligatoriu | Id-ul unui proiect, din `find_project`. |

```json
{
  "name": "project_overview",
  "arguments": {
    "project_id": "01a1b08c-4b1c-7d20-9a4b-2c3d4e5f6a7b"
  }
}
```

### `query_figures`

Adună înregistrări pentru un grafic, o comparație sau o numărătoare.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `source` | `documents`, `lines`, `invoices`, … (valori: 11), obligatoriu | Ce se adună, precum `invoices` sau `lines`. |
| `group_by` | listă de obiect (`field`, `bucket`, `level`), obligatoriu | Unul sau două câmpuri: rândurile, apoi coloanele. |
| `measure` | obiect (`agg`, `field`, `signed`) | Ce se adună: o numărătoare sau suma, media, minimul ori maximul unui câmp. |
| `filters` | listă de obiect (`field`, `values`, `since`, `until`, `min`, `max`) | Condiții pe câmpurile sursei. |
| `year` | integer | Un an de adunat. `period` îl înlocuiește. |
| `compare` | `previous_period`, `previous_year` | Comparați cu perioada anterioară sau cu aceeași perioadă de acum un an. |
| `top_n` | integer | Doar cele mai mari grupuri. |
| `matching` | obiect (`query`, `match`) | Doar documentele găsite de o căutare. |
| `title` | string | Titlul tabelului. |
| `period` | string | Cuvinte simple, precum `2025`, `Q3 2025` sau `last year`. |

```json
{
  "name": "query_figures",
  "arguments": {
    "source": "invoices",
    "measure": {"agg": "sum", "field": "net"},
    "group_by": [{"field": "company"}],
    "filters": [{"field": "direction", "values": ["incoming"]}],
    "period": "2025",
    "top_n": 10
  }
}
```

### `top_companies`

Clasează principalii furnizori sau clienți după suma netă dintr-o perioadă.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `side` | `suppliers`, `customers`, implicit `"suppliers"` | Furnizori (implicit) sau clienți. |
| `period` | string | Cuvinte simple, precum `2025`, `Q3 2025` sau `last year`. |
| `since` | date | De la această dată. |
| `until` | date | Până la această dată. |
| `category` | string | Un cod ECLASS sau cuvinte. |
| `n` | integer, implicit `10` | Câte să fie listate. |
| `title` | string | Titlul tabelului. |

```json
{
  "name": "top_companies",
  "arguments": {
    "side": "suppliers",
    "period": "2025",
    "n": 10
  }
}
```

### `spend_over_time`

Dă suma netă pe lună, trimestru sau an, pe companie sau categorie dacă se cere.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `period` | string | Cuvinte simple, precum `2025`, `Q3 2025` sau `last year`. |
| `bucket` | `month`, `quarter`, `year`, implicit `"month"` | Lună (implicit), trimestru sau an. |
| `by` | `company`, `category` | O coloană pe companie sau pe segment ECLASS. |
| `side` | `suppliers`, `customers`, implicit `"suppliers"` | Furnizori (implicit) sau clienți. |
| `since` | date | De la această dată. |
| `until` | date | Până la această dată. |
| `title` | string | Titlul tabelului. |

```json
{
  "name": "spend_over_time",
  "arguments": {
    "period": "last 12 months",
    "bucket": "month",
    "by": "company"
  }
}
```

### `largest_documents`

Listează cele mai mari documente după suma brută dintr-o perioadă.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `kind` | string | Un alt tip decât facturile de plătit, precum `credit_note`. |
| `side` | `suppliers`, `customers`, implicit `"suppliers"` | Furnizori (implicit) sau clienți. |
| `period` | string | Cuvinte simple, precum `2025`, `Q3 2025` sau `last year`. |
| `since` | date | De la această dată. |
| `until` | date | Până la această dată. |
| `n` | integer, implicit `10` | Câte să fie listate. |
| `title` | string | Titlul tabelului. |

```json
{
  "name": "largest_documents",
  "arguments": {
    "period": "Q3 2025",
    "n": 10
  }
}
```

### `payables_due`

Listează facturile de furnizor neplătite scadente într-un interval, întâi termenele de Skonto.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `window` | `this_week`, `next_7_days`, `next_14_days`, `next_30_days`, `this_month` | Când sunt scadente facturile. |
| `since` | date | De la această dată. |
| `until` | date | Până la această dată. |
| `company_id` | uuid | Id-ul unei companii, din `find_company`. |
| `title` | string | Titlul tabelului. |

```json
{
  "name": "payables_due",
  "arguments": {
    "window": "next_14_days"
  }
}
```

### `vat_preview`

Previzualizează o USt-Voranmeldung pe Kennzahl, ca s-o verifice consultantul fiscal.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `period` | string | O lună (`2026-10`) sau un trimestru (`2026-Q4`). |
| `kz` | string | O Kennzahl, ca să-i listați facturile. |
| `title` | string | Titlul tabelului. |

```json
{
  "name": "vat_preview",
  "arguments": {
    "period": "2026-10"
  }
}
```

### `find_anomalies`

Semnalează facturi duplicate, conturi bancare schimbate și prețuri peste comandă.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `since` | date | De la această dată. |
| `until` | date | Până la această dată. |
| `kinds` | listă de `duplicate`, `bank_changed`, `price_above_order` | Doar aceste semnalări. |
| `title` | string | Titlul tabelului. |

```json
{
  "name": "find_anomalies",
  "arguments": {
    "since": "2026-08-01",
    "until": "2026-10-31",
    "kinds": ["bank_changed"]
  }
}
```

### `supplier_profile`

Rezumă un furnizor într-un singur apel: cheltuieli, condiții, viteza de plată, sume deschise și prețuri.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `company_id` | uuid, obligatoriu | Id-ul unei companii, din `find_company`. |

```json
{
  "name": "supplier_profile",
  "arguments": {
    "company_id": "01a1b08c-5c2d-7e10-8b3a-1d2e3f4a5b6c"
  }
}
```

## `exports:write`

### `export_table`

Exportă ca Excel sau CSV un tabel returnat de alt instrument, printr-un link valabil 30 de minute.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `query` | obiect (`tool`, `args`), obligatoriu | `query`-ul unui tabel, neschimbat, așa cum l-a returnat un instrument. |
| `title` | string, implicit `"Ocost"` | Titlul tabelului. |
| `format` | `xlsx`, `csv`, implicit `"xlsx"` | Excel (`xlsx`, implicit) sau CSV. |

```json
{
  "name": "export_table",
  "arguments": {
    "query": {"tool": "top_companies", "args": {"period": "2025"}},
    "title": "Top suppliers 2025",
    "format": "xlsx"
  }
}
```

### `make_datev_export`

Creează exportul DATEV al unei perioade ca un singur ZIP, printr-un link semnat.

Doar printr-o conexiune OAuth, ca persoana care a permis-o.

| Argument | Tip | Semnificație |
| --- | --- | --- |
| `starts_on` | date, obligatoriu | Prima zi a perioadei. |
| `ends_on` | date, obligatoriu | Ultima zi a perioadei, în același an fiscal. |

```json
{
  "name": "make_datev_export",
  "arguments": {
    "starts_on": "2026-10-01",
    "ends_on": "2026-10-31"
  }
}
```

## Vezi și

- [Conectați un asistent](https://ocost.io/docs/ro/mcp.md): Conectați un asistent la serverul MCP (https://api.ocost.io/public/mcp, aceleași chei): Claude Code, Claude Desktop, Cursor, claude.ai și ChatGPT prin OAuth, și orice client.
- [Chei și drepturi](https://ocost.io/docs/ro/authentication.md): Chei API: cum le poartă o cerere, înlocuirea lor, drepturile lor și refuzurile.
- [Documentul](https://ocost.io/docs/ro/document.md): Schema ocost.document.v1 în termenii EN 16931 (se mapează pe UBL și CII): un exemplu, tip și direcție, surse, verificări, versiuni și fiecare câmp și valoare.
- Pe ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp)
