Откуцај API v1

REST АПИ за издавање фискалних рачуна, рефундације и копије, слање рачуна е-поштом, извештаје о промету и рад са артиклима. Све што ради каса у прегледачу може и ваш софтвер: веб продавница, ERP, наплатни систем.

Увод и базна адреса

Базна адреса свих позива:

https://otkucaj.com/api/v1

Сви захтеви и одговори су JSON у UTF-8 кодирању, осим журнала који се враћа као чист текст (text/plain). Комуникација иде искључиво преко HTTPS-а. Износи у JSON-у користе тачку као децимални знак (2400.00), јер је то JSON стандард; на самом рачуну и у журналу износи су у српском формату (2.400,00).

Версионисање. Верзија АПИ-ја је део путање: /api/v1. Постојећа поља и понашање се унутар v1 не мењају уназад некомпатибилно; нове могућности се додају као нова, опциона поља. Ако икада буде потребан прекид уговора, он ће живети на путањи /api/v2, а v1 ће наставити да ради.

Завршна коса црта се игнорише: /api/v1/items/ и /api/v1/items су иста путања. Непозната путања враћа 404 са кодом not_found.

Брзи почетак

Од кључа до првог рачуна у три корака.

1. Проверите везу и стање ПФР-а.

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

2. Издајте први рачун.

   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": "Мајица", "quantity": 2, "unitPrice": 1200.00, "label": "Ђ" }
       ]
     }'

   Одговор је 201 са целим рачуном: запамтите uuid и pfr.invoiceNumber. Пун облик одговора је код POST /invoices.

3. Преузмите журнал (текст рачуна спреман за штампу на 40 колона):

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

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"
}

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

Сваки захтев мора да носи заглавље:

Authorization: Bearer <api-kljuc>

Кључеве генерише администратор у апликацији, у одељку Подешавања · АПИ кључеви. Кључ се приказује само једном, у тренутку генерисања: у бази се чува искључиво његов SHA-256 отисак, па изгубљен кључ није могуће поново прочитати, већ се опозива и генерише нов. Опозив је тренутан: сваки следећи захтев са опозваним кључем добија 401.

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

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."
}

Ограничења и понашање

Прозор ограничења је фиксан, не клизни: први захтев отвара прозор од 60 секунди и броји до 240; кад прозор истекне, бројач креће испочетка. Прекорачење враћа HTTP 429:

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded (240 requests/minute)." } }

Када добијете 429, сачекајте до истека текућег прозора па наставите. За уобичајен рад продавнице (један рачун по поруџбини) ово ограничење се у пракси не досеже. Ограничење које се примењује и оно које пријављује GET /me долазе из истог места у коду, па не могу да се разиђу.

Окружења: тест и продукција

Свака инсталација Откуцаја има два одвојена окружења, и у сваком тренутку једно је активно. АПИ увек ради у активном окружењу, а које је то види се у одговору GET /status и у свакој листи и извештају.

Два окружења имају различит безбедносни елемент, различит ПАК и различит ЕСИР број. Апликација одбија да у оба постави исти сертификат и одбија да продукцију усмери на тест адресу Пореске управе (и обрнуто).

Подаци су потпуно раздвојени. Рачун носи ознаку окружења у коме је издат, па GET /invoices, GET /reports/summary и GET /reports/daily враћају само оно што припада активном окружењу. Тест рачун не може да уђе у продукцијски промет.

GET /api/v1/status

{
  "app": "Otkucaj",
  "version": "1.3.0",
  "esirNumber": "123456/1.0",
  "environment": "sandbox",     // sandbox | production
  "fiscal": false,              // true само у продукцији уз прави ПФР
  "ready": true,                // да ли се уопште може издати рачун
  "problems": [],               // ако није спремно, разлози редом
  "pfr": { "ok": true, "mode": "demo", "env": "sandbox" },
  "company": { "name": "…", "tin": "…", "location": "…" },
  "time": "2026-08-20T14:00:00.000+02:00"
}

Пре него што почнете да шаљете стварне рачуне, проверите environment и fiscal. Ако је fiscal: false, оно што издајете није фискални рачун, ма шта писало на журналу.

Свака издата ставка носи исту информацију:

"pfr": {
  "mode": "vpfr",
  "environment": "production",
  "fiscal": true,
  "invoiceNumber": "…",
  "verificationUrl": "https://suf.purs.gov.rs/v/?vl=…",
  "verificationQRCode": "R0lGODlh…"   // base64 GIF који је нацртао сам ПФР
}

Када verificationQRCode постоји, то је QR који припада рачуну: Пореска управа га црта по сопственим параметрима. Не цртајте свој преко њега. У демо режиму тог поља нема, па се QR прави из verificationUrl.

Идемпотентност: како да не издате два пута исти рачун

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

Зато сваки POST /invoices сме да носи кључ захтева. Пошаљите га на један од два начина:

POST /api/v1/invoices
Authorization: Bearer <api-kljuc>
Idempotency-Key: order-2026-08-20-4711
Content-Type: application/json

{ "items": [ … ] }

или у самом телу:

{ "clientRequestId": "order-2026-08-20-4711", "items": [ … ] }

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

• Кључ сме имати 8 до 64 знака: слова, бројеви и . _ : -. Све друго враћа 422.
• Кључ се резервише пре него што се позове ПФР, па два истовремена понављања не могу оба да прођу.
• Понављање са истим кључем враћа 201 и исти рачун, са истим uuid-ом и истим ПФР бројем. Нови се не издаје.
• Ако ПФР одбије захтев, кључ се ослобађа, па прави покушај поново ради.

Најбоље је узети нешто што већ имате и што је јединствено, на пример број поруџбине из свог система. Тако и мрежни прекид и ваш сопствени ретрај воде истом рачуну.

Позивање из прегледача (CORS)

АПИ дозвољава позиве са било ког порекла (Access-Control-Allow-Origin: *) и одговара на OPTIONS проверу. Аутентификација иде искључиво заглављем Authorization, никада колачићем, а Access-Control-Allow-Credentials се намерно не шаље.

То значи: страни сајт без вашег кључа не може ништа. Али то значи и да кључ не сме да стоји у JavaScript-у јавне странице, јер је тамо видљив свакоме. Из прегледача зовите свој сервер, а свој сервер нека зове Откуцај.

Рачуни

Седам путања око рачуна: издавање, листа, детаљ, журнал, рефундација, копија и слање е-поштом.

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" }
    ]
  }'

{
  "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"
}

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", "...": "..." }
  ]
}

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"
}

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ПП
======== КРАЈ ФИСКАЛНОГ РАЧУНА ========

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": "Веб продавница" }'

{
  "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"
}

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

{
  "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"
}

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]"
}

Токови: продаја, рефундација, копија, предрачун

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

Промет-продаја, са подељеним плаћањем

Најчешћи рачун. На једном рачуну сме више начина плаћања; збир мора одговарати збиру ставки.

{
  "invoiceType": "Normal",
  "transactionType": "Sale",
  "cashier": "Веб продавница",
  "payments": [
    { "paymentType": "Cash", "amount": 1000.00 },
    { "paymentType": "Card", "amount": 1400.00 }
  ],
  "items": [
    { "name": "Мајица", "quantity": 2, "unitPrice": 1200.00, "label": "Ђ" }
  ]
}

Рефундација

Ако враћате цео рачун, најједноставније је позвати POST /invoices/{uuid}/refund. Ручна рефундација кроз POST /invoices мора да носи referentDocumentNumber (ПФР број оригиналног рачуна) и buyerId (идентификацију купца). Без било ког од та два поља захтев се одбија са 422. Ставке и износи су они који се враћају, дакле могу бити и део оригиналног рачуна.

{
  "invoiceType": "Normal",
  "transactionType": "Refund",
  "cashier": "Веб продавница",
  "buyerId": "10:123456789",
  "referentDocumentNumber": "DMX7K2QP-DMX7K2QP-302",
  "referentDocumentDT": "2026-08-19 14:02:33",
  "payments": [{ "paymentType": "Card", "amount": 1200.00 }],
  "items": [
    { "name": "Мајица", "quantity": 1, "unitPrice": 1200.00, "label": "Ђ" }
  ]
}

Рефундације умањују промет у извештајима. Купцу који прима готовину издаје се и Копија-Рефундација са простором за потпис.

Поништавање сопственог рачуна

Погрешно издат рачун се поништава рефундацијом целог износа, при чему продавац као идентификацију купца уноси свој ПИБ, у облику 10:СВОЈПИБ.

{
  "invoiceType": "Normal",
  "transactionType": "Refund",
  "buyerId": "10:106884584",
  "referentDocumentNumber": "DMX7K2QP-DMX7K2QP-302",
  "referentDocumentDT": "2026-08-19 14:02:33",
  "payments": [{ "paymentType": "Card", "amount": 2400.00 }],
  "items": [{ "name": "Мајица", "quantity": 2, "unitPrice": 1200.00, "label": "Ђ" }]
}

Копија

Копија постојећег рачуна се најлакше издаје кроз POST /invoices/{uuid}/copy. Ручно, кроз POST /invoices, копија мора да носи referentDocumentNumber, иначе 422.

{
  "invoiceType": "Copy",
  "transactionType": "Sale",
  "referentDocumentNumber": "DMX7K2QP-DMX7K2QP-302",
  "referentDocumentDT": "2026-08-19 14:02:33",
  "payments": [{ "paymentType": "Card", "amount": 2400.00 }],
  "items": [{ "name": "Мајица", "quantity": 2, "unitPrice": 1200.00, "label": "Ђ" }]
}

Предрачун, па фискални рачун

Предрачун (ProForma) није фискални рачун: служи као понуда. Када купац плати, издаје се прави Промет-Продаја са референцом на предрачун.

Корак 1, предрачун:
{
  "invoiceType": "ProForma",
  "transactionType": "Sale",
  "payments": [{ "paymentType": "WireTransfer", "amount": 12000.00 }],
  "items": [{ "name": "Услуга одржавања", "unit": "мес", "quantity": 1, "unitPrice": 12000.00, "label": "Ђ" }]
}

Корак 2, по уплати, фискални рачун са референцом на предрачун:
{
  "invoiceType": "Normal",
  "transactionType": "Sale",
  "referentDocumentNumber": "DMX7K2QP-DMX7K2QP-310",
  "referentDocumentDT": "2026-08-19 09:15:00",
  "payments": [{ "paymentType": "WireTransfer", "amount": 12000.00 }],
  "items": [{ "name": "Услуга одржавања", "unit": "мес", "quantity": 1, "unitPrice": 12000.00, "label": "Ђ" }]
}

У самој апликацији дугме „Издај фискални рачун“ на предрачуну ради тачно ово: препуни касу и сама постави референцу.

Авансни ток, од прве уплате до коначног рачуна

Авансна ставка носи прописан назив по пореској ознаци: 10: Аванс (Ђ), 11: Аванс (Е), 12: Аванс (Г) или 13: Аванс (А). Количина је увек 1, а цена је износ примљеног аванса. Ток има три врсте докумената: авансни рачун (АП) за сваку уплату, аванс-рефундација (АР) која затвара збир свих аванса, и коначни Промет-Продаја.

1. Први авансни рачун (АП). Уплата од 5.000,00 стигла преносом на рачун 18.08, а књижи се 19.08: зато dateAndTimeOfIssue носи стварно време уплате (штампа се као „ЕСИР време“).

   {
     "invoiceType": "Advance",
     "transactionType": "Sale",
     "dateAndTimeOfIssue": "2026-08-18 11:30:00",
     "payments": [{ "paymentType": "WireTransfer", "amount": 5000.00 }],
     "items": [{ "name": "10: Аванс (Ђ)", "quantity": 1, "unitPrice": 5000.00, "label": "Ђ" }]
   }

   ПФР врати нпр. invoiceNumber: "DMX7K2QP-DMX7K2QP-311".

2. Додатни авансни рачуни за сваку следећу уплату, сваки са референцом на претходни АП:

   {
     "invoiceType": "Advance",
     "transactionType": "Sale",
     "referentDocumentNumber": "DMX7K2QP-DMX7K2QP-311",
     "referentDocumentDT": "2026-08-18 11:30:00",
     "payments": [{ "paymentType": "WireTransfer", "amount": 3000.00 }],
     "items": [{ "name": "10: Аванс (Ђ)", "quantity": 1, "unitPrice": 3000.00, "label": "Ђ" }]
   }

   ПФР врати нпр. invoiceNumber: "DMX7K2QP-DMX7K2QP-312".

3. Затварање: аванс-рефундација (АР) на цео примљени износ, са референцом на последњи АП и обавезним buyerId, јер је реч о рефундацији:

   {
     "invoiceType": "Advance",
     "transactionType": "Refund",
     "buyerId": "10:123456789",
     "referentDocumentNumber": "DMX7K2QP-DMX7K2QP-312",
     "referentDocumentDT": "2026-08-19 10:00:00",
     "payments": [{ "paymentType": "WireTransfer", "amount": 8000.00 }],
     "items": [{ "name": "10: Аванс (Ђ)", "quantity": 1, "unitPrice": 8000.00, "label": "Ђ" }]
   }

   ПФР врати нпр. invoiceNumber: "DMX7K2QP-DMX7K2QP-313".

4. Коначни Промет-Продаја са стварним ставкама испоруке, референцом на АР и рекламним текстом који носи број и датум последњег авансног рачуна:

   {
     "invoiceType": "Normal",
     "transactionType": "Sale",
     "referentDocumentNumber": "DMX7K2QP-DMX7K2QP-313",
     "referentDocumentDT": "2026-08-19 10:05:00",
     "adText": "Аванс: DMX7K2QP-DMX7K2QP-312 од 19.08.2026.",
     "payments": [{ "paymentType": "WireTransfer", "amount": 8000.00 }],
     "items": [{ "name": "Ормар по мери", "quantity": 1, "unitPrice": 8000.00, "label": "Ђ" }]
   }

У апликацији дугме „Затвори аванс“ на авансном рачуну само одради кораке 3 и 4: издаје АР на цео износ и препуни касу за коначни рачун са постављеном референцом и рекламним текстом.

Режим по чл. 6 ст. 2 Правилника

Инсталација може да ради у режиму у ком су начини плаћања Card, Check и MobileMoney искључени, а такве наплате се евидентирају као готовина. Једна инсталација ради у тачно једном режиму, који бира администратор у Подешавањима. Када је режим укључен, захтев са неким од искључених начина враћа:

422 { "error": { "code": "validation",
  "message": "Начин плаћања „Card“ је искључен подешавањем (режим по чл. 6 ст. 2 Правилника). Унесите као готовину." } }

Интеграција тада шаље {"paymentType": "Cash"} за те наплате.

Артикли

Шифарник артикала који каса нуди на додир. Артикли нису услов за издавање рачуна: POST /invoices прима ставке слободно, са називом и ценом из вашег система.

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
    }
  ]
}

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": "ком" }'

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

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 }

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

{ "ok": true }

Извештаји

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

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."
}

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."
}

Шифарници

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

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 }
  ]
}

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

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

Грешке

Свака грешка има исти JSON облик, без обзира на путању:

{ "error": { "code": "validation", "message": "Рефундација мора имати референтни број оригиналног рачуна (referentDocumentNumber)." } }

WooCommerce и интеграције

Готов додатак повезује WooCommerce продавницу без иједне линије кода: otkucaj-fiskalizacija.zip.

1. У WordPress администрацији отворите Додаци · Додај нови · Отпреми додатак, изаберите преузети zip и активирајте додатак.
2. У Откуцају (Подешавања · АПИ кључеви) генеришите кључ и одмах га ископирајте: приказује се само једном.
3. Отворите Подешавања · Откуцај фискализација у WordPress-у и унесите: адресу (https://otkucaj.com), АПИ кључ, статус поруџбине који окида издавање рачуна (нпр. „Завршено“ или „У обради“) и мапирање WooCommerce начина плаћања на фискалне (нпр. картице на Card, поузеће на Cash, вирман на WireTransfer).
4. Готово. Када поруџбина пређе у изабрани статус, додатак издаје рачун, тачно једном по поруџбини, и у саму поруџбину уписује ПФР број рачуна и линк за проверу, видљиве и вама и купцу.

Пореска ознака по производу: додатку се за појединачни производ може задати мета поље otkucaj_label (вредност из GET /tax-labels); производи без њега користе подразумевану ознаку из подешавања додатка.

Пример: чист PHP

function otkucaj_izdaj_racun(string $apiKey, array $body): array
{
    $ch = curl_init('https://otkucaj.com/api/v1/invoices');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Content-Type: application/json; charset=utf-8',
        ],
        CURLOPT_POSTFIELDS => json_encode($body, JSON_UNESCAPED_UNICODE),
    ]);
    $raw  = curl_exec($ch);
    $err  = curl_error($ch);
    $http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    if ($raw === false) {
        throw new RuntimeException("Мрежна грешка: $err");   // рачун можда јесте издат, проверити пре понављања
    }
    $json = json_decode($raw, true);
    if ($http === 201) {
        return $json;                                        // цео рачун: uuid, pfr, journal...
    }
    $code = $json['error']['code'] ?? 'unknown';
    $msg  = $json['error']['message'] ?? $raw;
    if ($http === 422) {
        throw new InvalidArgumentException("Неисправан захтев ($code): $msg"); // не понављати
    }
    throw new RuntimeException("Откуцај HTTP $http ($code): $msg");            // 429/502: поновити касније
}

$racun = otkucaj_izdaj_racun($apiKey, [
    'invoiceType' => 'Normal',
    'transactionType' => 'Sale',
    'cashier' => 'Веб продавница',
    'payments' => [['paymentType' => 'Card', 'amount' => 2400.00]],
    'items' => [['name' => 'Мајица', 'quantity' => 2, 'unitPrice' => 1200.00, 'label' => 'Ђ']],
]);
// сачувати уз поруџбину:
// $racun['uuid'], $racun['pfr']['invoiceNumber'], $racun['pfr']['verificationUrl']

Пример: Node.js

async function izdajRacun(apiKey, body) {
  const res = await fetch('https://otkucaj.com/api/v1/invoices', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json; charset=utf-8',
    },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(30000),
  });
  const json = await res.json();
  if (res.status === 201) return json;
  const { code, message } = json.error ?? {};
  const e = new Error(`Откуцај HTTP ${res.status} (${code}): ${message}`);
  e.retryable = res.status === 429 || res.status === 502; // 422 се никад не понавља
  throw e;
}

const racun = await izdajRacun(process.env.OTKUCAJ_KEY, {
  invoiceType: 'Normal',
  transactionType: 'Sale',
  cashier: 'Веб продавница',
  payments: [{ paymentType: 'Card', amount: 2400.00 }],
  items: [{ name: 'Мајица', quantity: 2, unitPrice: 1200.00, label: 'Ђ' }],
});
console.log(racun.pfr.invoiceNumber, racun.pfr.verificationUrl);

Пример: Python

import requests

def izdaj_racun(api_key: str, body: dict) -> dict:
    r = requests.post(
        'https://otkucaj.com/api/v1/invoices',
        json=body,
        headers={'Authorization': f'Bearer {api_key}'},
        timeout=30,
    )
    if r.status_code == 201:
        return r.json()
    err = r.json().get('error', {})
    if r.status_code == 422:
        raise ValueError(f"Неисправан захтев: {err.get('message')}")  # не понављати
    raise RuntimeError(f"Откуцај HTTP {r.status_code} ({err.get('code')}): {err.get('message')}")

racun = izdaj_racun(API_KEY, {
    'invoiceType': 'Normal',
    'transactionType': 'Sale',
    'cashier': 'Веб продавница',
    'payments': [{'paymentType': 'Card', 'amount': 2400.00}],
    'items': [{'name': 'Мајица', 'quantity': 2, 'unitPrice': 1200.00, 'label': 'Ђ'}],
})
print(racun['pfr']['invoiceNumber'], racun['pfr']['verificationUrl'])

Добра пракса

• Издајте рачун тек по наплати. Фискални рачун прати новац; поруџбина која није плаћена нема шта да фискализује.
• Чувајте uuid и pfr.invoiceNumber уз поруџбину. Без њих не можете касније да издате копију, рефундацију, да пошаљете рачун е-поштом нити да преузмете журнал.
• Читајте шифарнике, не преписујте их. Пореске ознаке узмите са GET /tax-labels при подешавању интеграције, јер се списак разликује од инсталације до инсталације.
• Поставите временско ограничење од 30 секунди, да позив ка АПИ-ју не блокира вашу апликацију унедоглед.
• Никада не позивајте АПИ из прегледача купца ни из мобилне апликације: кључ би био јаван. Сав саобраћај иде са вашег сервера.
• Не шаљите дупле захтеве. Уз сваку поруџбину чувајте свој идемпотентни кључ (нпр. број поруџбине) и пре слања проверите да ли је за њу рачун већ издат. Мрежни прекид после успешног издавања је најчешћи узрок дуплог рачуна: пре понављања проверите GET /invoices за тај дан.
• Развијте и тестирајте у демо режиму. Прелазак на Л-ПФР или В-ПФР је измена подешавања у Откуцају, без иједне измене у вашем коду.

Промене

Уговор АПИ-ја v1 је стабилан кроз све наведене верзије апликације: додаване су нове могућности, постојећа поља се нису мењала.

Питања и помоћ при интеграцији: [email protected]. Упутство за рад у самој апликацији: Упутство (PDF).