Быстрый старт
Пять шагов от нуля до первого счёта в JSON. Вам нужна учётная запись Ocost с ролью владельца или бухгалтера.
1. Зарегистрироваться
Зарегистрируйтесь на https://app.ocost.io/auth/sign-up или войдите. Файлы, которые вы отправляете через API, появляются в разделе Файлы, как любая загрузка.
2. Создать ключ
- Откройте Настройки › Разработчикам и выберите Новый ключ.
- Назовите ключ по тому, кто им пользуется, например «Odoo продакшн».
- Оставьте отмеченные права и выберите Создать ключ.
- Выберите Скопировать ключ. Ключ начинается с
ocost_sk_, и Ocost показывает его только один раз.
Сохраните его в оболочке для следующих шагов:
export OCOST_KEY="ocost_sk_…"3. Отправить PDF
Отправьте файл как multipart/form-data в поле file. external_ref — ваш собственный идентификатор, Ocost возвращает его вам.
curl -sS https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY" \
-F "file=@invoice.pdf" \
-F "external_ref=account.move,42"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()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 и начинает чтение:
{
"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 читаются меньше чем за минуту.
curl -sS https://api.ocost.io/public/v1/files/$FILE_ID \
-H "Authorization: Bearer $OCOST_KEY"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)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();
}Прочитанный файл перечисляет свои документы:
{
"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. Все причины перечислены на странице Статусы и причины.
5. Прочитать документ
Запросите первый документ файла.
curl -sS https://api.ocost.io/public/v1/files/$FILE_ID/document \
-H "Authorization: Bearer $OCOST_KEY"document = requests.get(
f"{API}/files/{file['id']}/document", headers=auth, timeout=15
).json()
print(document["number"], document["totals"]["gross"], document["currency"])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, здесь в сокращении:
{
"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 }
}Что дальше
- Отправить файл и прочитать: повторная отправка и удаление.
- Синхронизация собирает все изменения одним вызовом.
- Документ объясняет каждое поле.
- Поиск находит документы по словам и по смыслу.
- Подключить Odoo заполняет черновики счетов поставщиков.