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

> Magento ima sve što treba za čistu integraciju: događaje porudžbine, modul koji ih sluša i konfiguraciju za mapiranje poreskih klasa. BokaPOS nema gotov Magento modul; vaš developer ga napravi oko BokaPOS API-ja, obično za dan ili dva.

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

Magento prodavnice u Srbiji često prodaju i B2B kupcima. Tu je važno da se na fiskalni račun za firmu upiše PIB kupca kao identifikacija; BokaPOS to podržava u istom pozivu. Šta račun mora da sadrži: [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**

- Magento modul sluša događaj promene statusa porudžbine i poziva BokaPOS API.
- Poreske klase Magenta se mapiraju na oznake pročitane sa `GET /v1/tax-rates`.
- PIB firme kupca ide kao identifikacija kupca na račun.
- Fiskalna refundacija se pravi iz Magento credit memo-a, uz identifikaciju kupca.
- Sandbox besplatan; produkcija posle aktivacije bezbednosnog elementa obveznika.

## Gde se integracija zakači

Sopstveni modul registruje observer na događaj koji Magento emituje pri čuvanju porudžbine ili promeni statusa. Kada porudžbina pređe u status koji ste izabrali (na primer plaćeno ili isporučeno), observer sastavi zahtev iz stavki, popusta, dostave i plaćanja, pozove BokaPOS i sačuva PFR broj, verifikacioni link i status u atributima porudžbine. Credit memo pokreće fiskalnu refundaciju.

## Koraci integracije

1. **Nalog i sandbox.** Zatražite BokaPOS pristup i dobijate sandbox pristupne podatke i probni bezbednosni element, besplatno.
2. **Konfiguracija modula.** U admin konfiguraciji čuvajte client id i tajnu, izbor obveznika i poslovnog prostora, status koji pokreće fiskalizaciju i mapiranje poreskih klasa na oznake sa `GET /v1/tax-rates`.
3. **Observer na statusu.** Na izabranom statusu pošaljite `POST /v1/fiscal-documents` sa idempotentnim ključem iz increment id-a porudžbine. Sačuvajte odgovor uz porudžbinu i prikažite ga u adminu.
4. **Račun kupcu.** Priložite PDF iz `/representations/` uz Magento e-poštu o porudžbini ili uključite BokaPOS modul E-mail.
5. **Credit memo i produkcija.** Credit memo šalje fiskalnu refundaciju sa referencom i identifikacijom kupca. Posle testova obveznik aktivira bezbednosni element i prelazite na produkcione pristupne podatke.

Obim posla: Tipično dva dana rada developera koji poznaje Magento module, uključujući credit memo i testiranje u sandboxu.

## 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 Magento modul?**

Trenutno ne. Postoji dokumentovan API, primeri u PHP-u i besplatan sandbox, pa developer modul napravi za dan ili dva.

**Kako se fiskalizuje prodaja firmi u Magentu?**

Isto kao fizičkom licu, uz identifikaciju kupca: PIB firme se šalje u polju kupca i štampa se na računu kao ID kupca.

**Šta sa delimičnim isporukama?**

Fiskalni račun prati promet. Ako isporučujete u delovima, dogovorite sa knjigovođom da li izdajete račun po isporuci ili avansni račun pri uplati; BokaPOS podržava oba toka.

**Mogu li da testiram bez sertifikata obveznika?**

Da. Sandbox koristi probni bezbednosni element koji BokaPOS dodeljuje, pa integraciju testirate pre nego što obveznik dobije svoj element od Poreske uprave.