Pređi na sadržaj

Shopify · preko API-ja

Shopify fiskalizacija u Srbiji: fiskalni račun preko BokaPOS API-ja

Shopify ne dozvoljava serverski kod unutar prodavnice, pa fiskalizacija ide iz sopstvene aplikacije ili male serverske funkcije koja sluša plaćene porudžbine i poziva BokaPOS API. BokaPOS trenutno nema gotovu Shopify aplikaciju; integraciju radi vaš developer ili agencija, tipično za dan ili dva.

Zatražite probni pristupAPI dokumentacija

Zakon ne pravi razliku između platformi: Shopify prodavnica koja prodaje kupcima u Srbiji je obveznik fiskalizacije kao i svaki drugi web shop. Račun mora da izda odobren ESIR preko V-PFR-a Poreske uprave, a kupac ga dobija elektronski. Kako to izgleda uopšte: ESIR za web shop.

Primer ispod je isti poziv koji radi za svaku platformu: token, pa jedan POST /v1/fiscal-documents sa idempotentnim ključem porudžbine. Kompletna dokumentacija sa primerima u pet jezika je na stranici API.

Gde se integracija zakači

Sopstvena Shopify aplikacija (ili serverska funkcija na vašem hostingu) pretplati se na webhook za plaćenu porudžbinu. Kad webhook stigne, aplikacija pročita stavke, iznose i način plaćanja, pozove BokaPOS i sačuva PFR broj i verifikacioni link uz porudžbinu (napomena ili metapolje). Za refundaciju sluša webhook refundacije i pita operatera za identifikaciju kupca, jer je ona obavezna.

Koraci integracije

Obim posla
Tipično jedan do dva dana rada developera, uključujući testiranje refundacije u sandboxu.

  1. Nalog i sandbox

    Zatražite BokaPOS pristup. Dobijate organizaciju, probni bezbednosni element i client id i tajnu za sandbox, sve besplatno.

  2. Poreske oznake

    Pre svakog izdavanja pročitajte oznake sa GET /v1/tax-rates i mapirajte Shopify poreske stope na njih. Ništa ne ukodirajte: sandbox ima probne oznake, produkcija zvanične.

  3. Webhook plaćene porudžbine

    Na webhook pošaljite POST /v1/fiscal-documents sa stavkama, plaćanjem i idempotentnim ključem izvedenim iz broja porudžbine. Isti ključ dva puta vraća isti račun, nikad dva.

  4. Račun kupcu

    Preuzmite PDF ili sliku sa /representations/ i pošaljite kupcu, ili uključite BokaPOS modul E-mail da ga pošalje umesto vas.

  5. Refundacija i produkcija

    Na refundaciju pošaljite fiskalnu refundaciju sa referencom na original i identifikacijom kupca. Kad testovi prođu, obveznik aktivira bezbednosni element i dobijate produkcione pristupne podatke.

Isti poziv za svaku platformu

curl -X POST "https://auth.bokapos.rs/realms/boka/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$BOKAPOS_CLIENT_ID" \
  -d "client_secret=$BOKAPOS_CLIENT_SECRET"

curl -X POST "https://api.bokapos.rs/v1/fiscal-documents" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-4127-sale-1" \
  -H "Content-Type: application/json" \
  -d '{
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127",
  "invoiceType": "NORMAL",
  "transactionType": "SALE",
  "cashier": {
    "id": "web-shop",
    "displayName": "Web shop"
  },
  "items": [
    {
      "name": "Bluetooth slušalice",
      "unitOfMeasure": "kom",
      "quantity": 1,
      "unitPrice": 8990,
      "gtin": "8606012345678",
      "taxLabels": [
        "F"
      ]
    }
  ],
  "payments": [
    {
      "type": "CARD",
      "amount": 8990
    }
  ],
  "metadata": {
    "orderId": "4127",
    "channel": "web"
  }
}'

API dokumentacija

Česta pitanja

Da li Shopify ima ugrađenu fiskalizaciju za Srbiju?

Ne. Shopify ne izdaje fiskalne račune Poreske uprave; potreban je odobren ESIR. Integracija se radi iz sopstvene Shopify aplikacije ili serverske funkcije koja poziva BokaPOS API.

Da li BokaPOS ima gotovu Shopify aplikaciju?

Trenutno ne. Postoji dokumentovan API sa primerima, besplatan sandbox i AI paket dokumentacije, pa developer integraciju napravi za dan ili dva.

Kako kupac dobija račun?

Elektronski: PDF ili slika u e-pošti, ili link. QR kod se u elektronskom dokumentu zamenjuje verifikacionim linkom Poreske uprave.

Šta sa porudžbinama koje se plaćaju pouzećem?

Pouzeće je gotovina; račun se izdaje kada je promet izvršen, u praksi pri isporuci. Vaša aplikacija bira trenutak (na primer status isporučeno) i tada poziva BokaPOS.

Platforme

Izaberite platformu na kojoj radi vaša prodavnica.

Spremni da fiskalizujeteiz sopstvenog sistema?

Probno okruženje je besplatno, a prvi račun izdajete isti dan.

Zatražite demoPogledajte dokumentaciju