Dokumentacija API-jev za izmenjavo dokumentov preko Zbirnega centra

Zbirni center (ZC) omogoča varno, sledljivo in standardizirano izmenjavo elektronskih dokumentov med partnerji. Ta stran opisuje REST API-je, formate, napake in najboljše prakse za integracijo.

Status

Razpoložljivost

API je operativen. Vzdrževanja se objavijo vsaj 72 ur vnaprej.

Različice

SOAP različica

Trenutna glavna različica: v1. Večje spremembe bodo objavljene kot v2 ipd.

REST različica

Temelji na standardu eSLOG 2.0.

Skladnost

Varnost & skladnost

TLS 1.2+, JWT avtorizacija ali API-dostopi, šifriranje vsebin.

Hiter začetek

Pridobite poverilnice za dostop do sistema (potrebna je registracija organizacije in nastavitev poverilnic).
Z prejetimi poverilnicami dostopate do sistema.
Pošljite testni dokument v testno okolje (sandbox).
Prejmite testni dokument iz testnega okolja (sandbox).

curl -X 'POST' \
  'https://api.zbirnicenter.si/prod/v1/documents/eslog' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/xml' \
  -d '<?xml version="1.0" encoding="UTF-8"?><PurchaseOrder xmlns="urn:eslog:2.00"> ... </PurchaseOrder>'


// ustvarimo novo instanco spletne storitve:
ZbirniCenter klient = new ZbirniCenter();

// ustvarimo podatke o dobavnicah in postavkah 
String vsebinaDobavnice = "*-STRT-*" + "12" + " 23" + "HH" + ... + "24042010" + ...

// kličemo metodo za uvoz dobavnic:
StatusOperacije status = klient.UvozDobavnic("uporabnikovo ime", "geslo", vsebinaDobavnice, '0001','0002','0002');

Avtentikacija

Podprta sta dva načina:

REST JWT žeton – pridobite access_token in ga pošiljajte v Authorization: Bearer.
SOAP Poverilnice – pridobite svoje poverilnice in jih uporabite pri klicu metod.

Okolja

Okolje	Osnovni URL	Opomba
Test	SOAP dobavnice : `https://api.zbirnicenter.si/dobaviteljitest/Dobavitelj.asmx` SOAP naročila: `https://api.zbirnicenter.si/lekarnetest/lekarna.asmx` REST: `https://api.zbirnicenter.si/test/swagger/index.html`	Izolirano, umetni podatki
Produkcija	SOAP dobavnice : `https://api.zbirnicenter.si/dobavitelji/Dobavitelj.asmx` SOAP naročila: `https://api.zbirnicenter.si/lekarne/lekarna.asmx` REST: `https://api.zbirnicenter.si/prod/swagger/index.html`	Visoka razpoložljivost

Viri (endpoints) SOAP

Dokumentacija

Naročila

Naročila - povratnice

Naročila - predlogi

Dobavnice

Viri (endpoints) REST

Pošiljanje dokumenta

POST /v1/documents/eslog – pošljanje dokumenta v ZC.

POST {env}/v1/documents/eslog
Authorization: Bearer <TOKEN>
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- eSLOG 2.0 dokument -->

Seznam dokumentov za prevzem

GET /v1/documents – vrača seznam še neprevzetih dokumentov.

GET {env}/v1/documents
Authorization: Bearer <TOKEN>

Prevzem dokumenta

GET /v1/document/{id} – vrača JSON obliko posameznega dokumenta.

GET /v1/document/eslog/{id} – vrača eSLog 2.0 obliko posameznega dokumenta.

GET /v1/document/nensi/{id} – vrača NENSI obliko posameznega dokumenta.

GET {env}/v1/document/eslog/{id}
Authorization: Bearer <TOKEN>

Posodobi status

PUT /v1/documents/conclude/{id} – zaključi prevzem dokumenta in s tem se odstrani iz seznama dokumentov za prevzem

PUT {env}/v1/documents/conclude/{id}
Authorization: Bearer <TOKEN>
accept: */*

Formati in sheme

Podprti so priloge v JSON in XML.

Primer JSON seznama dokumentov za prevzem

[
  {
    "id": "652ea98a-c6e6-4952-8758-39e9bd5f19db",
    "vrstaID": 3,
    "vrsta": "Naročilo",
    "partner": {
      "keys": [
        {
          "type": 0,
          "typeName": "ZC",
          "value": "3510"
        }
      ],
      "name": "Lekarna XY"
    },
    "datum": "2025-06-17T12:54:59.49",
    "stevilka": "2025/3"
  }]

Primer eSlog 2.0 naročila

<?xml version="1.0" encoding="utf-8"?>
  <PurchaseOrder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:eslog:2.00">
    <M_ORDERS Id="data">
      <S_UNH>
        <D_0062>2025/3</D_0062>
        <C_S009>
          <D_0065>ORDERS</D_0065>
          <D_0052>D</D_0052>
          <D_0054>01B</D_0054>
          <D_0051>UN</D_0051>
        </C_S009>
      </S_UNH>
      <S_BGM>
        <C_C002>
          <D_1001>220</D_1001>
        </C_C002>
        <C_C106>
          <D_1004>2025/3</D_1004>
        </C_C106>
        <D_1225>9</D_1225>
      </S_BGM>
      <S_DTM>
        <C_C507>
          <D_2005>137</D_2005>
          <D_2380>20250617125459</D_2380>
          <D_2379>204</D_2379>
        </C_C507>
      </S_DTM>
      <S_DTM>
        <C_C507>
          <D_2005>2</D_2005>
          <D_2380>20250826</D_2380>
          <D_2379>102</D_2379>
        </C_C507>
      </S_DTM>
      <S_FTX>
        <D_4451>DIN</D_4451>
        <C_C108>
          <D_4440 />
        </C_C108>
      </S_FTX>
      <S_FTX>
        <D_4451>AAI</D_4451>
        <C_C108>
          <D_4440>Dobavitelj</D_4440>
        </C_C108>
      </S_FTX>
      <G_SG1>
        <S_RFF>
          <C_C506>
            <D_1153>IT</D_1153>
            <D_1154>00000000-0000-0000-0000-000000000000</D_1154>
          </C_C506>
        </S_RFF>
        <S_DTM>
          <C_C507>
            <D_2005>171</D_2005>
            <D_2380>20250617</D_2380>
            <D_2379>102</D_2379>
          </C_C507>
        </S_DTM>
      </G_SG1>
      <G_SG1>
        <S_RFF>
          <C_C506>
            <D_1153>ON</D_1153>
            <D_1154>2025/3</D_1154>
          </C_C506>
        </S_RFF>
      </G_SG1>
          <G_SG2><S_NAD><D_3035>IV</D_3035><C_C080><D_3036>Lekarna</D_3036><D_3036_2>X</D_3036_2><D_3036_3>X</D_3036_3><D_3036_4>X</D_3036_4><D_3036_5>X</D_3036_5></C_C080><C_C059><D_3042>Ulica</D_3042><D_3042_2>X</D_3042_2><D_3042_3>X</D_3042_3><D_3042_4>X</D_3042_4></C_C059><D_3164>Pošta</D_3164><C_C819></C_C819><D_3251>6210</D_3251><D_3207>SI</D_3207></S_NAD><G_SG3><S_RFF><C_C506><D_1153>IT</D_1153><D_1154>5110857</D_1154></C_C506></S_RFF></G_SG3></G_SG2>
    	  <G_SG2><S_NAD><D_3035>BY</D_3035><C_C080><D_3036>Lekarna</D_3036><D_3036_2>X</D_3036_2><D_3036_3>X</D_3036_3><D_3036_4>X</D_3036_4><D_3036_5>X</D_3036_5></C_C080><C_C059><D_3042>Ulica</D_3042><D_3042_2>X</D_3042_2><D_3042_3>X</D_3042_3><D_3042_4>X</D_3042_4></C_C059><D_3164>Pošta</D_3164><C_C819></C_C819><D_3251>6210</D_3251><D_3207>SI</D_3207></S_NAD><G_SG3><S_RFF><C_C506><D_1153>IT</D_1153><D_1154>8007111</D_1154></C_C506></S_RFF></G_SG3></G_SG2>
    	  <G_SG2><S_NAD><D_3035>DP</D_3035><C_C080><D_3036>Lekarna</D_3036><D_3036_2>X</D_3036_2><D_3036_3>X</D_3036_3><D_3036_4>X</D_3036_4><D_3036_5>X</D_3036_5></C_C080><C_C059><D_3042>Ulica</D_3042><D_3042_2>X</D_3042_2><D_3042_3>X</D_3042_3><D_3042_4>X</D_3042_4></C_C059><D_3164>Pošta</D_3164><C_C819></C_C819><D_3251>6210</D_3251><D_3207>SI</D_3207></S_NAD><G_SG3><S_RFF><C_C506><D_1153>IT</D_1153><D_1154>8007111</D_1154></C_C506></S_RFF></G_SG3></G_SG2>
    	  <G_SG2><S_NAD><D_3035>SU</D_3035><C_C080><D_3036>Dobavitelj d.o.o.</D_3036><D_3036_2>X</D_3036_2><D_3036_3>X</D_3036_3><D_3036_4>X</D_3036_4><D_3036_5>X</D_3036_5></C_C080><C_C059><D_3042>Ulica</D_3042><D_3042_2>X</D_3042_2><D_3042_3>X</D_3042_3><D_3042_4>X</D_3042_4></C_C059><D_3164>Pošta</D_3164><C_C819></C_C819><D_3251>9201</D_3251><D_3207>SI</D_3207></S_NAD><G_SG3><S_RFF><C_C506><D_1153>VA</D_1153><D_1154>SI90351991</D_1154></C_C506></S_RFF></G_SG3></G_SG2>
      <G_SG7>
        <S_CUX>
          <C_C504>
            <D_6347>2</D_6347>
            <D_6345>EUR</D_6345>
          </C_C504>
        </S_CUX>
      </G_SG7>
      <G_SG28>
        <S_LIN>
          <D_1082>1</D_1082>
          <C_C212>
            <D_7140>064642069252</D_7140>
            <D_7143>SRV</D_7143>
          </C_C212>
        </S_LIN>
        <S_PIA>
          <D_4347>5</D_4347>
          <C_C212>
            <D_7140>1151340380</D_7140>
            <D_7143>SA</D_7143>
          </C_C212>
        </S_PIA>
        <S_PIA>
          <D_4347>5</D_4347>
          <C_C212>
            <D_7140>156269</D_7140>
            <D_7143>IN</D_7143>
          </C_C212>
        </S_PIA>
        <S_PIA>
          <D_4347>5</D_4347>
          <C_C212>
            <D_7140>064642069252</D_7140>
            <D_7143>SUE</D_7143>
          </C_C212>
        </S_PIA>
        <S_IMD>
          <D_7077>F</D_7077>
          <C_C273>
            <D_7008>JAMIESON BABY-D VI. D3 OTR. 11,7ML KAPLJ</D_7008>
          </C_C273>
        </S_IMD>
        <S_QTY>
          <C_C186>
            <D_6063>21</D_6063>
            <D_6060>1.0000000</D_6060>
            <D_6411>H87</D_6411>
          </C_C186>
        </S_QTY>
        <S_MOA>
          <C_C516>
            <D_5025>203</D_5025>
            <D_5004>13.98000000000</D_5004>
          </C_C516>
        </S_MOA>
        <S_MOA>
          <C_C516>
            <D_5025>52</D_5025>
            <D_5004>0</D_5004>
          </C_C516>
        </S_MOA>
        <S_FTX>
          <D_4451>AAI</D_4451>
          <C_C108>
            <D_4440>EM</D_4440>
            <D_4440_2>KOS</D_4440_2>
          </C_C108>
        </S_FTX>
        <G_SG32>
          <S_PRI>
            <C_C509>
              <D_5125>AAB</D_5125>
              <D_5118>13.9800</D_5118>
            </C_C509>
          </S_PRI>
        </G_SG32>
        <G_SG32>
          <S_PRI>
            <C_C509>
              <D_5125>AAA</D_5125>
              <D_5118>13.9800</D_5118>
            </C_C509>
          </S_PRI>
        </G_SG32>
      </G_SG28>
      <S_MOA>
        <C_C516>
          <D_5025>79</D_5025>
          <D_5004>13,98000000000</D_5004>
        </C_C516>
      </S_MOA>
    </M_ORDERS>
  </PurchaseOrder>

Napake

Koda	Pomen	Primer
`400`	Nepravilen zahtevek	`missing field: receiver`
`401`	Neavtorizirano	`invalid token`
`403`	Prepovedano	`scope too narrow`
`404`	Ni najdeno	`message not found`
`409`	Konflikt	`duplicate documentId`
`413`	Prevelik zahtevek	`payload exceeds limit`
`429`	Preveč zahtevkov	`rate limit exceeded`
`500`	Napaka strežnika	`internal error`

Pogosta vprašanja

Ali podpirate X.509 podpisane dokumente?

Da, podpira se priponka z XAdES/CAdES podpisom. Validacija je opcijska na vnosu, obvezna pri prevzemu.

Kakšna je največja velikost dokumenta?

Posamezni dokument do 10 MB v JSON/XML, do 50 MB v multipart načinu.

Ali nudite testne podatke?

Da, sandbox vsebuje generirane partnerje in primere računov.

Podpora

Za pomoč kontaktirajte zbirnicenter@orka.it. SLA: odziv v 1 delovnem dnevu, kritični incidenti v 2 urah.

Changelog

v1.0.0 – začetna javna izdaja.