Откуцај API v1

Стање апликације и везе са ПФР-ом. Употребите за проверу конфигурације и за надзор.

Аутентификација

Authorization: Bearer <api-kljuc>

Параметри

нема

Одговор

200, JSON

Захтев

curl -H "Authorization: Bearer kasir_vas_kljuc" \
  https://otkucaj.com/api/v1/status

Одговор

{
  "app": "Otkucaj",
  "version": "1.2.0",
  "esirNumber": "у поступку одобравања/1.0",
  "pfr": {
    "ok": true,
    "mode": "demo",
    "uid": "DMX7K2QP",
    "message": "Демо ПФР симулатор: активан"
  },
  "time": "2026-08-19T14:00:00.000+02:00"
}

pfr.mode је demo, lpfr или vpfr, у зависности од подешавања инсталације. Када је режим Л-ПФР или В-ПФР, објекат pfr преноси и податке које врати сам процесор фискалних рачуна; ok: false са поруком значи да ПФР тренутно није доступан. esirNumber се склапа од броја и верзије ЕСИР-а из Подешавања.

• 401 unauthorized
• 429 rate_limited

Подаци о кључу којим је захтев потписан: назив, сачувани префикс, датуми, ограничење броја захтева које се стварно примењује и шта кључ сме. Корисно за проверу да интеграција користи онај кључ који мислите да користи.

Аутентификација

Authorization: Bearer <api-kljuc>

Параметри

нема

Одговор

200, JSON

Захтев

curl -H "Authorization: Bearer kasir_vas_kljuc" \
  https://otkucaj.com/api/v1/me

Одговор

{
  "key": {
    "id": 3,
    "label": "Веб продавница",
    "prefix": "kasir_7f3a",
    "active": true,
    "createdAt": "2026-08-01 09:12:44",
    "lastUsedAt": "2026-08-19 13:58:02"
  },
  "rateLimit": { "requests": 240, "windowSeconds": 60 },
  "scope": "full",
  "permissions": [
    "invoices:read", "invoices:write", "items:read", "items:write",
    "reports:read", "taxLabels:read", "categories:read"
  ],
  "note": "API keys are not scoped individually: every active key may call every route."
}

• 401 unauthorized
• 429 rate_limited

Издавање рачуна. Захтев се валидира, прослеђује ПФР-у, а рачун се уписује у базу тек када га ПФР потпише. Одговор 201 враћа цео рачун, укључујући журнал и линк за проверу.

Аутентификација

Authorization: Bearer <api-kljuc>

Тело

JSON, Content-Type: application/json

Одговор

201, цео рачун

Захтев

curl -X POST https://otkucaj.com/api/v1/invoices \
  -H "Authorization: Bearer kasir_vas_kljuc" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceType": "Normal",
    "transactionType": "Sale",
    "cashier": "Веб продавница",
    "payments": [{ "paymentType": "Card", "amount": 2400.00 }],
    "items": [
      { "name": "Мајица", "unit": "ком", "quantity": 2, "unitPrice": 1200.00,
        "label": "Ђ", "gtin": "8600000000000" }
    ]
  }'

Одговор 201

{
  "uuid": "9b2f6c1e-4d3a-4f0b-9a77-2c8e5d1f6a30",
  "invoiceType": "Normal",
  "transactionType": "Sale",
  "cashier": "Веб продавница",
  "total": 2400.0,
  "payments": [
    { "paymentType": "Card", "amount": 2400.0 }
  ],
  "items": [
    {
      "name": "Мајица",
      "unit": "ком",
      "quantity": 2.0,
      "unitPrice": 1200.0,
      "totalAmount": 2400.0,
      "label": "Ђ",
      "gtin": "8600000000000"
    }
  ],
  "taxItems": [
    { "label": "Ђ", "categoryName": "О-ПДВ", "rate": 20.0, "amount": 400.0, "total": 2400.0 }
  ],
  "buyerId": null,
  "referentDocumentNumber": null,
  "referentDocumentDT": null,
  "pfr": {
    "mode": "demo",
    "demo": true,
    "requestedBy": "DMX7K2QP",
    "signedBy": "DMX7K2QP",
    "invoiceNumber": "DMX7K2QP-DMX7K2QP-302",
    "invoiceCounter": "143/302ПП",
    "sdcDateTime": "2026-08-19 14:02:33",
    "verificationUrl": "https://otkucaj.com/verify?id=9b2f6c1e-4d3a-4f0b-9a77-2c8e5d1f6a30"
  },
  "journal": "======== ФИСКАЛНИ РАЧУН =======\n...",
  "createdAt": "2026-08-19 14:02:33"
}

Овај облик враћају и GET /invoices/{uuid}, сваки елемент листе рачуна, и путање за рефундацију и копију. Значење ПФР поља: invoiceNumber је ПФР број рачуна (облик JID-JID-N), invoiceCounter је бројач (нпр. 143/302ПП: 143. рачун врсте Промет-Продаја од укупно 302), sdcDateTime је ПФР време, verificationUrl је линк ка страници за проверу рачуна, demo каже да ли је рачун издат у демо режиму. taxItems је пореска рекапитулација по ознакама, са стопом, износом пореза и основицом; стопе долазе искључиво од ПФР-а, никада из вашег захтева.

• 400 bad_request
• 401 unauthorized
• 422 validation
• 429 rate_limited
• 502 pfr_error

На 502 рачун није издат и ништа није уписано у базу.

Листа рачуна, најновији први, до 100 по страни. Сваки елемент је цео рачун, у истом облику као одговор на POST /invoices, заједно са журналом.

Аутентификација

Authorization: Bearer <api-kljuc>

Параметри

у упитном делу адресе (query string)

Одговор

200, JSON

Захтев

curl -H "Authorization: Bearer kasir_vas_kljuc" \
  "https://otkucaj.com/api/v1/invoices?from=2026-08-01&to=2026-08-19&type=Normal&page=1"

Одговор

{
  "page": 1,
  "perPage": 100,
  "invoices": [
    { "uuid": "9b2f6c1e-4d3a-4f0b-9a77-2c8e5d1f6a30", "invoiceType": "Normal", "...": "..." }
  ]
}

Празна листа значи да за задате филтере нема рачуна. Укупан број рачуна се не враћа: страничите док не добијете мање од 100 елемената.

• 401 unauthorized
• 429 rate_limited

Један рачун по UUID-у, у пуном облику описаном код POST /invoices.

Аутентификација

Authorization: Bearer <api-kljuc>

Путања

uuid: 36 знакова, мала слова и цифре са цртицама, онако како га АПИ и врати

Одговор

200, цео рачун

Захтев

curl -H "Authorization: Bearer kasir_vas_kljuc" \
  https://otkucaj.com/api/v1/invoices/9b2f6c1e-4d3a-4f0b-9a77-2c8e5d1f6a30

Одговор

{
  "uuid": "9b2f6c1e-4d3a-4f0b-9a77-2c8e5d1f6a30",
  "invoiceType": "Normal",
  "transactionType": "Sale",
  "total": 2400.0,
  "pfr": { "invoiceNumber": "DMX7K2QP-DMX7K2QP-302", "...": "..." },
  "journal": "======== ФИСКАЛНИ РАЧУН =======\n...",
  "createdAt": "2026-08-19 14:02:33"
}

UUID који не постоји враћа 404 са кодом not_found. UUID исписан великим словима не одговара облику путање и завршава као непозната путања, такође 404: шаљите га тачно онако како вам га је АПИ вратио.

• 401 unauthorized
• 404 not_found
• 429 rate_limited

Журнал рачуна као чист текст (text/plain; charset=utf-8), 40 колона, ћирилицом, спреман за термални штампач од 58 или 80 mm. Идентичан журналу који апликација сама штампа. Ово је једини одговор који није JSON.

Аутентификација

Authorization: Bearer <api-kljuc>

Параметри

нема

Одговор

200, text/plain; charset=utf-8

Захтев

curl -H "Authorization: Bearer kasir_vas_kljuc" \
  https://otkucaj.com/api/v1/invoices/9b2f6c1e-4d3a-4f0b-9a77-2c8e5d1f6a30/journal

Одговор, скраћено

======== ФИСКАЛНИ РАЧУН =======
              106884584
           Пример д.о.о.
           Продавница 1
       Булевар ослобођења 1
              Београд
Касир:           Веб продавница
ЕСИР број: у поступку одобравања/1.0
------ ПРОМЕТ - ПРОДАЈА -------
Артикли
========================================
Назив   Цена         Кол.         Укупно
Мајица /ком (Ђ)
        1.200,00     2          2.400,00
----------------------------------------
За уплату:                      2.400,00
Платна картица:                 2.400,00
========================================
Ознака  Име      Стопа          Порез
Ђ       О-ПДВ    20,00%         400,00
----------------------------------------
Укупан износ пореза:              400,00
========================================
ПФР време:         19.08.2026. 14:02:33
ПФР број рачуна:   DMX7K2QP-DMX7K2QP-302
Бројач рачуна:               143/302ПП
======== КРАЈ ФИСКАЛНОГ РАЧУНА ========

Нефискалне врсте (Копија, Предрачун, Обука) уместо заглавља и краја фискалног рачуна носе линију „ОВО НИЈЕ ФИСКАЛНИ РАЧУН“, коју апликација при штампи увећава на двоструку величину фонта. Копија-Рефундација додатно штампа простор „Потпис купца“ за потпис при враћању новца.

• 401 unauthorized
• 404 not_found
• 429 rate_limited

Рефундација целог постојећег рачуна, једним позивом. Ставке се преузимају са оригинала, референтни број и време показују на оригинал, а нов рачун се издаје кроз исти пут као и сваки други. Ово је исто што ради дугме Рефундација у апликацији.

Аутентификација

Authorization: Bearer <api-kljuc>

Тело

опционо, JSON

Одговор

201, нов рачун рефундације

Ставке се увек узимају са оригиналног рачуна, у целости, и не могу се задати телом захтева. За делимичну рефундацију (враћа се само део ставки или мања количина) користите POST /invoices са transactionType: "Refund", где сами наводите шта се враћа.

Захтев

curl -X POST \
  https://otkucaj.com/api/v1/invoices/9b2f6c1e-4d3a-4f0b-9a77-2c8e5d1f6a30/refund \
  -H "Authorization: Bearer kasir_vas_kljuc" \
  -H "Content-Type: application/json" \
  -d '{ "buyerId": "10:123456789", "cashier": "Веб продавница" }'

Одговор 201

{
  "uuid": "1c77a0d5-9b12-4f8e-b3aa-0d5e7c9f4411",
  "invoiceType": "Normal",
  "transactionType": "Refund",
  "cashier": "Веб продавница",
  "total": 2400.0,
  "buyerId": "10:123456789",
  "referentDocumentNumber": "DMX7K2QP-DMX7K2QP-302",
  "referentDocumentDT": "2026-08-19 14:02:33",
  "pfr": {
    "invoiceNumber": "DMX7K2QP-DMX7K2QP-318",
    "invoiceCounter": "12/318РП",
    "...": "..."
  },
  "journal": "======== ФИСКАЛНИ РАЧУН =======\n...",
  "createdAt": "2026-08-19 16:41:02"
}

• 400 bad_request
• 401 unauthorized
• 404 not_found
• 422 validation
• 429 rate_limited
• 502 pfr_error

Издавање копије постојећег рачуна, кроз исти пут који користи дугме Копија у апликацији. Копија носи све ставке и плаћања оригинала, референтни број и време оригинала, и његову идентификацију купца.

Аутентификација

Authorization: Bearer <api-kljuc>

Тело

нема, шаље се празан POST

Одговор

201, нова копија

Захтев

curl -X POST \
  https://otkucaj.com/api/v1/invoices/9b2f6c1e-4d3a-4f0b-9a77-2c8e5d1f6a30/copy \
  -H "Authorization: Bearer kasir_vas_kljuc"

Одговор 201

{
  "uuid": "6d4b1f92-2a70-4c31-8f5e-7b1c0a93de84",
  "invoiceType": "Copy",
  "transactionType": "Sale",
  "total": 2400.0,
  "referentDocumentNumber": "DMX7K2QP-DMX7K2QP-302",
  "referentDocumentDT": "2026-08-19 14:02:33",
  "pfr": { "invoiceNumber": "DMX7K2QP-DMX7K2QP-319", "...": "..." },
  "journal": "ОВО НИЈЕ ФИСКАЛНИ РАЧУН\n...",
  "createdAt": "2026-08-19 16:43:20"
}

Копија није фискални рачун: у журналу нема заглавља фискалног рачуна, него линија „ОВО НИЈЕ ФИСКАЛНИ РАЧУН“. Копија рефундације додатно носи простор за потпис купца.

• 401 unauthorized
• 404 not_found
• 422 validation
• 429 rate_limited
• 502 pfr_error

Слање рачуна купцу е-поштом. Порука садржи журнал и линк за проверу рачуна, и потпуно је иста као она коју шаље дугме у апликацији, јер обе иду кроз исти код. Слање се уписује у ревизиони траг као invoice.email.

Аутентификација

Authorization: Bearer <api-kljuc>

Тело

JSON: {"to": "[email protected]"}

Одговор

200, потврда

Захтев

curl -X POST \
  https://otkucaj.com/api/v1/invoices/9b2f6c1e-4d3a-4f0b-9a77-2c8e5d1f6a30/email \
  -H "Authorization: Bearer kasir_vas_kljuc" \
  -H "Content-Type: application/json" \
  -d '{ "to": "[email protected]" }'

Одговор

{
  "ok": true,
  "uuid": "9b2f6c1e-4d3a-4f0b-9a77-2c8e5d1f6a30",
  "to": "[email protected]"
}

Ограничење слања је 30 порука на сат по кључу, независно од општег ограничења од 240 захтева у минуту. Прекорачење враћа 429 са поруком о ограничењу поште. Ако сервер поште одбије поруку, одговор је 502 са кодом mail_error: то није ни грешка ПФР-а ни грешка у захтеву, него неуспело слање, и захтев се сме поновити касније.

• 400 bad_request
• 401 unauthorized
• 404 not_found
• 422 validation
• 429 rate_limited
• 502 mail_error

Листа артикала, сортирано по називу, до 1.000 комада. Поље active разликује активне од деактивираних; деактивирани су такође у одговору.

Аутентификација

Authorization: Bearer <api-kljuc>

Параметри

нема, ни страничења ни филтера

Одговор

200, JSON

Захтев

curl -H "Authorization: Bearer kasir_vas_kljuc" \
  https://otkucaj.com/api/v1/items

Одговор

{
  "items": [
    {
      "id": 12,
      "plu": "1001",
      "name": "Мајица",
      "unit": "ком",
      "price": 1200.0,
      "label": "Ђ",
      "gtin": "8600000000000",
      "active": true
    }
  ]
}

• 401 unauthorized
• 429 rate_limited

Додавање артикла у шифарник.

Аутентификација

Authorization: Bearer <api-kljuc>

Тело

JSON

Одговор

201, ИД новог артикла

Нов артикал се увек уписује као активан. Поље category се овим позивом не поставља.

Захтев

curl -X POST https://otkucaj.com/api/v1/items \
  -H "Authorization: Bearer kasir_vas_kljuc" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Мајица", "price": 1200.00, "label": "Ђ",
        "plu": "1001", "gtin": "8600000000000", "unit": "ком" }'

Одговор 201

{ "id": 12, "ok": true }

• 400 bad_request
• 401 unauthorized
• 422 validation
• 429 rate_limited

Делимична измена артикла: шаљете само поља која мењате, остала остају нетакнута. Оба метода, PUT и PATCH, раде исто.

Аутентификација

Authorization: Bearer <api-kljuc>

Путања

id: целобројни ИД артикла

Тело

JSON, било која од поља plu, name, unit, price, label, gtin, active

Одговор

200, потврда

Захтев

curl -X PUT https://otkucaj.com/api/v1/items/12 \
  -H "Authorization: Bearer kasir_vas_kljuc" \
  -H "Content-Type: application/json" \
  -d '{ "price": 1350.00, "active": true }'

Одговор

{ "ok": true }

• 400 bad_request
• 401 unauthorized
• 404 not_found
• 429 rate_limited

Мека деактивација: артикал се не брише из базе, јер га постојећи рачуни и даље референцирају. Добија active: false и нестаје са касе. Поновно активирање је PUT са {"active": true}.

Аутентификација

Authorization: Bearer <api-kljuc>

Путања

id: целобројни ИД артикла

Одговор

200, потврда

Захтев

curl -X DELETE https://otkucaj.com/api/v1/items/12 \
  -H "Authorization: Bearer kasir_vas_kljuc"

Одговор

{ "ok": true }

• 401 unauthorized
• 429 rate_limited

Промет за период, са разрадом по пореској ознаци, начину плаћања и касиру.

Аутентификација

Authorization: Bearer <api-kljuc>

Параметри

from, to

Одговор

200, JSON

Неисправан облик датума или период у ком је from касније од to враћају 422, за разлику од листе рачуна где се датуми не проверавају.

Захтев

curl -H "Authorization: Bearer kasir_vas_kljuc" \
  "https://otkucaj.com/api/v1/reports/summary?from=2026-08-01&to=2026-08-19"

Одговор

{
  "from": "2026-08-01",
  "to": "2026-08-19",
  "totals": {
    "invoices": 142,
    "turnover": 386400.0,
    "refunds": { "count": 3, "amount": 7200.0 }
  },
  "byTaxLabel": [
    { "label": "Ђ", "name": "О-ПДВ", "rate": 20.0, "turnover": 351200.0 },
    { "label": "Е", "name": "П-ПДВ", "rate": 10.0, "turnover": 35200.0 }
  ],
  "byPaymentType": [
    { "paymentType": "Card", "amount": 244800.0 },
    { "paymentType": "Cash", "amount": 141600.0 }
  ],
  "byCashier": [
    { "cashier": "Веб продавница", "invoices": 118, "turnover": 302400.0 },
    { "cashier": "Марија", "invoices": 24, "turnover": 84000.0 }
  ],
  "rule": "Turnover counts issued Normal and Advance receipts only; refunds subtract; ProForma, Copy and Training are excluded."
}

Значење поља: totals.invoices је број рачуна у периоду, укључујући и рефундације; totals.turnover је промет умањен за рефундације; totals.refunds посебно приказује број и укупан износ рефундација, као позитиван број. У byTaxLabel су name и rate вредности null ако ознака више не постоји у шифарнику, а рачуни са њом су остали у бази. Начини плаћања се сабирају из самог рачуна, па за подељена плаћања сваки део улази у свој ред.

• 401 unauthorized
• 422 validation
• 429 rate_limited

Промет и број рачуна по данима, за исти период и по истом правилу као сабирни извештај.

Аутентификација

Authorization: Bearer <api-kljuc>

Параметри

from, to, оба подразумевано данас, строго YYYY-MM-DD

Одговор

200, JSON

Захтев

curl -H "Authorization: Bearer kasir_vas_kljuc" \
  "https://otkucaj.com/api/v1/reports/daily?from=2026-08-01&to=2026-08-05"

Одговор

{
  "from": "2026-08-01",
  "to": "2026-08-05",
  "days": [
    { "date": "2026-08-01", "invoices": 12, "turnover": 28800.0 },
    { "date": "2026-08-02", "invoices": 9, "turnover": 19400.0 },
    { "date": "2026-08-05", "invoices": 15, "turnover": 41250.0 }
  ],
  "rule": "Turnover counts issued Normal and Advance receipts only; refunds subtract; ProForma, Copy and Training are excluded."
}

Дани без промета се изостављају, тачно као у табели у апликацији. Ако вам треба непрекидан низ датума, попуните празнине на својој страни.

• 401 unauthorized
• 422 validation
• 429 rate_limited

Пореске ознаке и стопе које су тренутно на снази, из истог извора који користи и валидатор рачуна (само активни редови). Ознака коју врати овај позив је ознака коју ће POST /invoices прихватити.

Аутентификација

Authorization: Bearer <api-kljuc>

Параметри

нема

Одговор

200, JSON

Захтев

curl -H "Authorization: Bearer kasir_vas_kljuc" \
  https://otkucaj.com/api/v1/tax-labels

Одговор

{
  "taxLabels": [
    { "label": "Ђ", "name": "О-ПДВ", "rate": 20.0 },
    { "label": "Е", "name": "П-ПДВ", "rate": 10.0 },
    { "label": "Г", "name": "Без ПДВ", "rate": 0.0 }
  ]
}

• 401 unauthorized
• 429 rate_limited

Категорије активних артикала, без празних вредности, сортиране азбучно. Исти упит који каса користи за дугмад категорија.

Аутентификација

Authorization: Bearer <api-kljuc>

Параметри

нема

Одговор

200, JSON

Захтев

curl -H "Authorization: Bearer kasir_vas_kljuc" \
  https://otkucaj.com/api/v1/categories

Одговор

{ "categories": ["Пиће", "Слаткиши", "Храна"] }

Категорије се уносе уз артикал у апликацији. Артикли без категорије не праве празан унос у овој листи.

• 401 unauthorized
• 429 rate_limited