mojKonto.si API

mojKonto.si za razvijalce

Isti API model kot produkcija, ločen sandbox račun, ločeni API ključi, webhooks in testni podatki. Obstoječe produkcijsko okolje ostane nedotaknjeno.

1. Prijava

Razvijalec se prijavi ali registrira v ločenem sandbox okolju. Brez prijave ne more dobiti svojega ključa.

2. Testni podjetji

Ob registraciji dobi dve mojKonto.si sandbox podjetji: DDV zavezanec in brez DDV.

3. API ključ

V istem modulu API dostop ustvari ključ, ki velja samo za sandbox in se pošlje v headerju X-API-Key.

4. Testni računi

Račune lahko vpiše v mojKonto.si UI ali prek API-ja. Oblika dokumenta je ista kot produkcija, samo testna.

Okolja

Production

https://mojkonto.si/api/api/v1

Sandbox

https://sandbox.mojkonto.si/api/v1

Integracija se razvije enkrat, za produkcijo pa se zamenjata base URL in API ključ.

Primer klica

curl https://sandbox.mojkonto.si/api/v1/racuni \
  -H "X-API-Key: fk_sandbox_xxxxx" \
  -H "Content-Type: application/json"

ločeno okolje isti endpointi testni dokumenti webhooks brez produkcijskih podatkov

Kaj lahko kličete

Dokumenti in šifranti

/v1/racuni, /v1/dobavnice, /v1/prejeti-racuni, /v1/narocila, /v1/prejeta-narocila, /v1/artikli, /v1/stranke, /v1/konti … — branje, ustvarjanje, urejanje; izdaja z POST /v1/racuni/{id}/izdaj (razknjiži tudi zalogo; premajhna zaloga → 409 NEGATIVE_STOCK, v minus z dovoliNegativnoZalogo).

PDF in popravki izdanih računov

PDF izpis: POST /v1/racuni/{id}/izpis vrne časovno omejeno povezavo do izpisa, enakega kot v aplikaciji (predloga, QR, noga, jezik). Vsebinski popravek izdanega računa: PUT /v1/racuni/{id} z "vsebinskiPopravek": true — številka ostane, temeljnica in zaloga se uskladita (ne v zaključenem poslovnem letu). Storno: dobropis z vezo na račun (status: cancelled → 409 USE_CREDIT_NOTE).

Zaloga

POST /v1/zaloge/premiki (prejem / izdaja / prenos med skladišči, idempotentno z zunanjiKljuc), POST /v1/zaloge/premiki/{id}/storno, promet GET /v1/zaloge/gibanja, stanje po skladiščih GET /v1/zaloge/stanje. Več premikov naenkrat: POST /v1/zaloge/premiki/paket (do 200, odgovor po vrsticah). Izdaja iz skladišča brez zaloge → 400 INVALID_WAREHOUSE; storitve (tipArtikla: "Storitev") so brez zaloge. Pri 503 upoštevajte Retry-After.

Analitike (projekti)

Šifrant /v1/analitike; polje analitika na računih, prejetih računih (po vrsticah kontiranja), naročilih in premikih zaloge se prenese v knjigo. Izkaz po projektih: GET /v1/analitike/promet.

Sinhronizacija in webhooki

Na seznamih ?posodobljenOd= (UTC, ISO 8601) za sprotno uskladitev. Webhooki: POST JSON {event, data, timestamp, webhookId}, podpis X-Webhook-Signature: sha256=HMAC(telo, skrivnost). Naročila: order.confirmed / order.delivered / order.cancelled ob spremembi statusa. Vse napake vsebujejo traceId.

Celotna, vedno ažurna dokumentacija (polja, obvezne vrednosti, primeri, posebni endpointi, oblika napak): GET /v1 in GET /v1/{entiteta}/polja, v aplikaciji pa Sistem → API dostop → Dokumentacija.

Kaj se ne podvaja?

Model računa, API controllerji, validacije, pravila postavk in webhooks ostanejo isti. Sandbox doda samo ločeno okolje, ločen ključ in varovalke za zunanje servise.