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

> PrestaShop moduli se zakače na hook-ove porudžbine, pa je fiskalizacija jedan modul koji na izabranom statusu pozove BokaPOS API. BokaPOS nema gotov PrestaShop modul; developer ga napravi oko API-ja, obično za dan.

Izvor: https://bokapos.rs/integracije/prestashop

Za PrestaShop prodavnice u Srbiji važe ista pravila kao za svaki web shop: odobren ESIR, V-PFR Poreske uprave, elektronska dostava računa kupcu. Pregled pravila: [ESIR za web shop](https://bokapos.rs/vodic/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](https://bokapos.rs/api).

**Ukratko**

- Modul na hook-u promene statusa porudžbine poziva BokaPOS API.
- Poreska pravila PrestaShopa se mapiraju na oznake sa `GET /v1/tax-rates`.
- PFR broj i verifikacioni link se čuvaju uz porudžbinu i prikazuju u adminu.
- Povraćaj iz PrestaShopa postaje fiskalna refundacija sa identifikacijom kupca.
- Sandbox besplatan, produkcija posle aktivacije bezbednosnog elementa.

## Gde se integracija zakači

Modul registruje hook koji PrestaShop poziva posle promene statusa porudžbine (i, po potrebi, hook validacije porudžbine za plaćanja koja stižu odmah). Na izabranom statusu modul sastavi zahtev iz stavki, popusta, dostave i plaćanja, pozove BokaPOS i sačuva odgovor u sopstvenoj tabeli vezanoj za porudžbinu. Povraćaj (order slip) pokreće fiskalnu refundaciju uz obaveznu identifikaciju kupca.

## Koraci integracije

1. **Nalog i sandbox.** Zatražite BokaPOS pristup: sandbox pristupni podaci i probni bezbednosni element su besplatni.
2. **Konfiguracija modula.** Client id i tajna, obveznik i poslovni prostor, status koji pokreće fiskalizaciju, mapiranje poreskih pravila na oznake sa `GET /v1/tax-rates`, mapiranje načina plaćanja na sedam zvaničnih vrsta.
3. **Hook na statusu.** Na statusu pošaljite `POST /v1/fiscal-documents` sa idempotentnim ključem iz reference porudžbine. Prikažite PFR broj i link u admin panelu porudžbine.
4. **Račun kupcu.** Priložite PDF iz `/representations/` uz PrestaShop e-poštu ili uključite BokaPOS modul E-mail.
5. **Povraćaj i produkcija.** Order slip šalje fiskalnu refundaciju sa referencom i identifikacijom kupca. Posle testova obveznik aktivira bezbednosni element i prelazite na produkciju.

Obim posla: Tipično jedan dan rada developera koji poznaje PrestaShop module, plus testiranje refundacije.

## Isti poziv za svaku platformu

```bash
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"
  }
}'
```

## Česta pitanja

**Da li BokaPOS ima gotov PrestaShop modul?**

Trenutno ne. API je dokumentovan sa primerima u PHP-u, sandbox je besplatan, pa developer modul napravi za dan.

**Koji status da izaberem za fiskalizaciju?**

Onaj koji odgovara izvršenom prometu: za kartično plaćanje status plaćeno, za pouzeće isporučeno. Za uplate unapred pre isporuke koristite avansni račun.

**Kako se mapiraju poreska pravila?**

Svako poresko pravilo PrestaShopa dobija oznaku pročitanu sa `GET /v1/tax-rates` (u produkciji Ђ 20%, Е 10%, Г 0%, А 0%). Oznake se čitaju uživo, ne ukodiraju.

**Šta ako V-PFR ne odgovori?**

Modul ne sme da ponovi zahtev naslepo. BokaPOS vraća jasan status nepoznatog ishoda; modul ga prikaže i sačeka proveru pre bilo kakvog novog izdavanja.