# Швидкий старт
> П’ять кроків до першого рахунку в JSON: зареєструватися, створити ключ, надіслати PDF, дочекатися прочитання, прочитати документ. curl, Python і JavaScript.

П’ять кроків від нуля до першого рахунку в JSON. Вам потрібен обліковий запис Ocost у ролі власника або бухгалтера.

## 1. Зареєструйтеся

Зареєструйтеся на `https://app.ocost.io/auth/sign-up` або увійдіть. Файли, які ви надсилаєте через API, з’являються у **Файли**, як будь-яке завантаження.

## 2. Створіть ключ

1. Відкрийте **[Налаштування › Розробникам](https://app.ocost.io/settings/api)** і виберіть **Новий ключ**.
2. Назвіть ключ за тим, хто ним користується, наприклад «Odoo продакшн».
3. Залиште дозволи, які позначено, і виберіть **Створити ключ**.
4. Виберіть **Скопіювати ключ**. Ключ починається з `ocost_sk_`, і Ocost показує його лише один раз.

Збережіть його в оболонці для наступних кроків:

```bash
export OCOST_KEY="ocost_sk_…"
```

## 3. Надішліть PDF

Надішліть файл як `multipart/form-data` у полі `file`. `external_ref` — ваш власний ідентифікатор, і Ocost повертає його вам.

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -F "file=@invoice.pdf" \
  -F "external_ref=account.move,42"
```

```python
import os

import requests

API = "https://api.ocost.io/public/v1"
auth = {"Authorization": f"Bearer {os.environ['OCOST_KEY']}"}

with open("invoice.pdf", "rb") as f:
    sent = requests.post(
        f"{API}/files",
        headers=auth,
        files={"file": ("invoice.pdf", f, "application/pdf")},
        data={"external_ref": "account.move,42"},
        timeout=30,
    )
sent.raise_for_status()
file = sent.json()
```

```javascript
import { readFile } from 'node:fs/promises';

const API = 'https://api.ocost.io/public/v1';
const auth = { Authorization: `Bearer ${process.env.OCOST_KEY}` };

const form = new FormData();
form.append(
  'file',
  new Blob([await readFile('invoice.pdf')], { type: 'application/pdf' }),
  'invoice.pdf',
);
form.append('external_ref', 'account.move,42');
const sent = await fetch(`${API}/files`, { method: 'POST', headers: auth, body: form });
let file = await sent.json();
```

Ocost відповідає `202 Accepted` і починає читати:

```json
{
  "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
  "name": "invoice.pdf",
  "status": "received",
  "reason": null,
  "external_ref": "account.move,42",
  "documents": [],
  "sha256": "0edd5593…"
}
```

## 4. Дочекайтеся, поки його прочитають

Запитуйте файл кожні кілька секунд, поки його `status` — `received` або `reading`. Більшість PDF читаються менше ніж за хвилину.

```bash
curl -sS https://api.ocost.io/public/v1/files/$FILE_ID \
  -H "Authorization: Bearer $OCOST_KEY"
```

```python
import time

for wait in [2, 2, 3, 5, 5, 10, 10, 15, 30, 30]:
    file = requests.get(f"{API}/files/{file['id']}", headers=auth, timeout=15).json()
    if file["status"] not in ("received", "reading"):
        break
    time.sleep(wait)
```

```javascript
while (file.status === 'received' || file.status === 'reading') {
  await new Promise((done) => setTimeout(done, 3000));
  file = await (await fetch(`${API}/files/${file.id}`, { headers: auth })).json();
}
```

Прочитаний файл перелічує свої документи:

```json
{
  "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
  "status": "read",
  "documents": [
    {
      "id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11",
      "kind": "invoice",
      "number": "RE-2026-1187",
      "pages": [1]
    }
  ]
}
```

Файл, що завершився статусом `not_read` або `failed`, пояснює причину в `reason`. Їх перелічує сторінка [Статуси та причини](https://ocost.io/docs/uk/statuses.md).

## 5. Прочитайте документ

Запитайте перший документ файлу.

```bash
curl -sS https://api.ocost.io/public/v1/files/$FILE_ID/document \
  -H "Authorization: Bearer $OCOST_KEY"
```

```python
document = requests.get(
    f"{API}/files/{file['id']}/document", headers=auth, timeout=15
).json()
print(document["number"], document["totals"]["gross"], document["currency"])
```

```javascript
const document = await (
  await fetch(`${API}/files/${file.id}/document`, { headers: auth })
).json();
console.log(document.number, document.totals.gross, document.currency);
```

Відповідь — рахунок у форматі `ocost.document.v1`, тут скорочено:

```json
{
  "schema": "ocost.document.v1",
  "kind": "invoice",
  "number": "RE-2026-1187",
  "issue_date": "2026-11-03",
  "due_date": "2026-12-03",
  "currency": "EUR",
  "seller": { "name": "Musterbüro Lieferant GmbH", "vat_id": "DE123456789" },
  "totals": { "net": 1068, "tax": 202.92, "gross": 1270.92 }
}
```

## Далі

- [Надіслати файл і прочитати](https://ocost.io/docs/uk/files.md) описує повторне надсилання і видалення.
- [Синхронізація](https://ocost.io/docs/uk/sync.md) збирає кожну зміну одним викликом.
- [Документ](https://ocost.io/docs/uk/document.md) пояснює кожне поле.
- [Пошук](https://ocost.io/docs/uk/search.md) знаходить документи за словами і за змістом.
- [Підключити Odoo](https://ocost.io/docs/uk/odoo.md) заповнює чернетки рахунків постачальників.

## Див. також

- [Надіслати файл і прочитати](https://ocost.io/docs/uk/files.md): Надіслати файл, безпечно надіслати його знову, дочекатися прочитання, прочитати його документи, отримати оригінал, видалити його.
- [Документ](https://ocost.io/docs/uk/document.md): Схема ocost.document.v1 у термінах EN 16931 (відображається на UBL і CII): приклад, вид і напрям, джерела, перевірки, версії, кожне поле і значення.
- [Ключі та дозволи](https://ocost.io/docs/uk/authentication.md): Ключі API: як запит їх передає, заміна ключів, їхні дозволи і відмови.
- [Підключити асистента](https://ocost.io/docs/uk/mcp.md): Підключити асистента до сервера MCP (https://api.ocost.io/public/mcp, ті самі ключі): Claude Code, Claude Desktop, Cursor, claude.ai і ChatGPT через OAuth, а також будь-який клієнт.
- На ocost.io: [API and MCP](https://ocost.io/en/product/api-and-mcp), [Pricing](https://ocost.io/en/pricing)
