Брз почеток со REST API

REST API му ги дава на вашиот софтвер истите записи со кои работите во апликацијата: клиенти, документи (фактури и другите типови документи), артикли, трошоци, договори и статистики. Со овој брз почеток за неколку минути од нов клуч стигнувате до нацрт фактура. Целосната референца со сите адреси и полиња е на јавната страница со API документација.

Пред да почнете#

• API клуч. Создадете го во Поставки > Интеграции под REST API (видете API клучеви). Додека градите, користете тест клуч (blf_test_), за да не допрете ништо вистинско.
• Основна адреса, прикажана во истиот дел со копче за копирање. Завршува на /api/v1. Постои една адреса и за продукција и за тест околината; клучот одлучува до кој работен простор стигнувате.

Примерите подолу користат две променливи во командната линија:

export BILIFY_URL="https://<вашата Bilify адреса>/api/v1"   # копирајте ја Основна адреса од Поставки > Интеграции
export BILIFY_KEY="blf_test_..."                             # вашиот клуч

Автентикација#

Клучот се праќа како bearer токен во секое барање:

Authorization: Bearer blf_test_...

Клучот дејствува како лицето што го создало, со дозволите на неговата улога во работниот простор. Повик за кој тоа лице нема дозвола враќа 403 forbidden, исто како што копчето не би постоело во апликацијата.

Чекор 1: излистајте ги клиентите#

curl -s "$BILIFY_URL/clients?per_page=5" \
  -H "Authorization: Bearer $BILIFY_KEY" \
  -H "Accept: application/json"

Одговорот ги става редовите во data и додава блок meta:

{
  "data": [
    { "reference": "01J9Z...", "name": "Алфа Трејд ДООЕЛ", "type": "business",
      "tax_number": "4030...", "email": "office@alfa.mk", "city": "Скопје",
      "default_currency": "MKD" }
  ],
  "meta": { "page": 1, "per_page": 5, "total": 42, "last_page": 9 }
}

Секој запис се адресира со својот reference (ULID), никогаш со бројчен id. Клиентите може да ги филтрирате со search (име, даночен број или е-пошта) и type.

Чекор 2: креирајте нацрт фактура#

Документите се креираат како нацрти: без број, слободно се менуваат и клиентот не ги гледа. Типовите документи и даночните стапки се адресираат со клуч, на пример mk.faktura (Фактура) и mk.vat.standard (ДДВ 18%) за македонски работен простор.

curl -s -X POST "$BILIFY_URL/documents" \
  -H "Authorization: Bearer $BILIFY_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: order-10045" \
  -d '{
    "document_type": "mk.faktura",
    "client": "01J9Z...",
    "currency": "MKD",
    "due_date": "2026-10-20",
    "lines": [
      { "description": "Веб дизајн", "quantity": 1, "unit_price": 12000, "tax_rate": "mk.vat.standard" }
    ]
  }'

Успешен повик враќа 201 со нацртот во data, вклучувајќи го неговиот reference. Цените се во основна единица (денари, евра). Ако не наведете currency, се зема валутата на клиентот, а ако ја нема, валутата на работниот простор. За валутата мора да постои активен начин на плаќање во Поставки, инаку добивате грешка validation_failed за currency.

Чекор 3: издадете ја (по желба)#

Издавањето е посебен, намерен повик:

curl -s -X POST "$BILIFY_URL/documents/01JA0.../issue" \
  -H "Authorization: Bearer $BILIFY_KEY" \
  -H "Accept: application/json"

Преглед на адресите#

Договорите креирани преку API секогаш се пишувани договори. Прикачување PDF договор е можно само во апликацијата.

Договорени правила#

• Износите доаѓаат двапати: како децимален текст, на пример "1250.00", и како цел број во најмала единица, на пример 125000, во соодветното поле _cents. Пресметувајте со вредноста _cents.
• Датумите се YYYY-MM-DD; времињата се ISO 8601.
• Страничење: адресите за листи примаат page и per_page (стандардно 25, најмногу 100) и враќаат meta.page, meta.per_page, meta.total и meta.last_page.

Лимит на барања#

Секој клуч смее да прати 120 барања во минута. Одговорите ги содржат X-RateLimit-Limit и X-RateLimit-Remaining. Над лимитот добивате 429 rate_limited со заглавие Retry-After што кажува колку секунди да почекате.

Безбедно повторување со Idempotency-Key#

POST адресите што креираат или менуваат нешто (клиенти, документи, издавање, плаќања, артикли, трошоци, договори, испраќање, поништување, повторна испорака) примаат заглавие Idempotency-Key. Користете вредност што е единствена за операцијата, на пример бројот на вашата нарачка.

• Првиот успешен (2xx) одговор за тој клуч се чува 24 часа. Ако го повторите истото барање со истиот клуч, го добивате зачуваниот одговор со заглавие Idempotency-Replayed: true и ништо не се креира двапати.
• Ако истиот клуч го користите со друга содржина, добивате 409 idempotency_conflict.
• Неуспешните одговори не се чуваат, па откако ќе ја поправите грешката при валидација, може да повторите со истиот клуч.
• Без заглавието, барањето едноставно се извршува.

PATCH и DELETE не користат клуч за идемпотентност.

Грешки#

Секоја грешка го има истиот облик:

{
  "error": {
    "code": "validation_failed",
    "message": "Податоците во барањето се невалидни.",
    "errors": { "lines.0.unit_price": ["..."] }
  }
}

code е стабилен и на него може да се потпрете во кодот; message е текст за луѓе и може да се смени. errors се појавува само кај грешки при валидација.

Следни чекори#

• Наместо постојано да проверувате, добивајте известувања: Webhooks.
• Градете врз тест податоци: Тест околина.
• Сите полиња и одговори: API документација. Таму се и целосниот список адреси и OpenAPI датотеката, кои се отвораат кога сте најавени.