Partner API (#19245)¶

Piletis #19245 rakendatud/laiendatud softera API otspunktide dokumentatsioon: partnerorganisatsiooni loomine, organisatsioonide otsing, LOCCAT kataloogikohtade CRUD, organisatsiooni GLN-i muutmine.

Üldine¶

1. Baas-URL: https://api-test.docura.net/ap1/partner/api/
2. Autentimine: päis X-Authorization: <api_key> (kasutaja token, api_key väli tabelis users).
3. Päist X-App-Key kliendid ei kasuta — taustaprogrammis ei ole see kontroll praegu ühegi filtriketiga ühendatud (surnud kood alates 2023), seega võib selle ära jätta.
4. Formaat — JSON (välja arvatud juhul, kui on selgesõnaliselt teisiti märgitud).
5. Rollid (autoriteet): SYSTEM_ADMIN, SYSTEM_SUPPORT, CLIENT_ADMIN, CLIENT_EDITOR, PROVIDER_ADMIN — lubatud rollide kohta vaata iga lõpp-punkti kirjeldust.

---

1. Partnerorganisatsiooni loomine¶

POST /user/organization¶

Loob uue organisatsiooni ja lisab kutsuva kasutaja sinna CLIENT_ADMIN rolli (eraldi, varasema sammu kaudu loomise protsessis).

Õigused: rollipiirangud puuduvad — kättesaadav igale autenditud kasutajale. Õigused ei väljendu kutsuja rolli kaudu, vaid läbi selle, millisesse organisatsiooni kutsuja ise kuulub (vt operatorId loogikat allpool).

Päringu keha:

Väli	Tüüp	Nõutav	Piirangud
taxId	string	jah	2–20 märki
registrationNumber	string	jah	2–50 märki
name	string	jah	2–50 märki
countryCode	string	jah	2 märki
locale	string	jah	2 märki, peab eksisteerima lokaalide viiteloendis
errorEmail	string	ei	kuni 250 märki, e-posti formaat
notes	string	ei	kuni 255 märki
phones	string	ei	kuni 50 märki
email	string	ei	kuni 150 märki, e-posti formaat

Väli integrationProfileType, mis esines selle funktsiooni varasemates iteratsioonides sama pileti raames, eemaldati lõplikust versioonist — klient ei saa profiili/connectionType selgesõnaliselt valida (vt allpool).

Vastus (200): sama väljade komplekt + id (Long), iln (organisatsiooni genereeritud GLN).

Vead:

1. 409 Conflict (organization.create.conflict.tax_id) — organisatsioon selle taxId-ga on juba olemas.
2. 400 — sobimatud päringu keha väljad (bean validation) või lokaati ei leitud (not.exists.specified.organization.locale).

Loogika uue organisatsiooni operaatori (operatorId) määramiseks¶

See arvutatakse KUTSUVA kasutaja enda organisatsioonist (callerIln – seansi praeguse organisatsiooni ILN), ilma selgete parameetriteta päringus:

1. Kui kutsuja organisatsioon on softera ise (profile.softeraOrganizationIln) → uue organisatsiooni operaator = softera ise. Lisaks lisatakse sel juhul uude organisatsiooni vaikimisi softera kasutaja (profile.softeraDefaultUserId, kui määratud) kui CLIENT_ADMIN.
2. Kui kutsuja organisatsioon on teenusepakkuja (role='P', kuid mitte softera) → operaator = kutsuja oma organisatsioon.
3. Muul juhul (ei softera ega teenusepakkuja) → operaator = organisatsioon profile.defaultOperatorOrganizationIln-st (varuvariandiks "vaikimisi operaator").
4. Kui ei kutsuja organisatsiooni ega varuorganisatsiooni ei leita ILN-i järgi – 500 (IllegalStateException, ei tohiks tavaliselt juhtuda).

Uue organisatsiooni connectionType loogika¶

1. Helistaja on Softera → alati Payment (kõvasti kodeeritud, olenemata millestki).
2. Vastasel juhul → connectionType = operaatori organisatsiooni connectionType (see, mis arvutati ülal – teenusepakkuja või varuorganisatsioon). Klient ei saa connectionType/integratsiooniprofiili selgesõnaliselt määrata.

---

2. Organisatsioonide otsimine¶

GET /organizations/search?query=<string>¶

Õigused: SYSTEM_ADMIN, SYSTEM_SUPPORT, PROVIDER_ADMIN. operatorId järgi piirangut ei ole — pakkuja näeb tulemusi kogu organisatsioonide andmebaasist, mitte ainult oma klientide kohta (teadlik otsus, mis tehti selle pileti raames).

Parameetrid:

Parameeter	Tüüp	Nõutav	Kirjeldus
query	string	jah	Otsingustring. Tühi/puuduv string → tühi nimekiri ilma veata.

Otsinguloogika andmebaasis — üks OR üle organisatsiooni:

1. täpne vaste id-le (tekstina);
2. täpne vaste iln (GLN)-le;
3. täpne vaste regNr -le (tõstutundetu);
4. täpne vaste vatNr -le (tõstutundetu);
5. alamstring (ILIKE) organisatsiooni name-s;
6. alamstring (ILIKE) mis tahes selle LOCCAT asukoha name-s.

Vastus (200): massiiv, iga element on pakendatud organization objekti:

[
  {
    "organization": {
      "id": 100099815,
      "name": "New brand sof",
      "iln": "2000005810008",
      "taxId": "...",
      "registrationNumber": "...",
      "countryCode": "EE",
      "locations": [ { "id": ..., "iln": "...", "name": "...", "formattedAddress": "...", ... } ]
    }
  }
]

Oluline nüanss: locations[] sisaldab ainult neid asukohti, mille enda nimi vastas otsingustringile – mitte kõiki leitud organisatsiooni asukohti. Kui organisatsioon leiti id/iln/regNr/vatNr/nime, mitte asukoha nime järgi, on locations tühi massiiv. See on teadlik käitumine, mitte viga.

---

3. Organisatsiooni asukohtade LOCCAT kataloog¶

Algtee: /organization/{gln}/locations, kus {gln} on organisatsiooni GLN (mitte numbriline ID).

Õigused (ühised kõigile kolmele alltoodud meetodile):

1. SYSTEM_ADMIN / SYSTEM_SUPPORT — piiranguid pole.
2. PROVIDER_ADMIN — ainult juhul, kui kutsuja organisatsioon = sihtorganisatsiooni operatorId (teenusepakkuja haldab ise hallatavate organisatsioonide asukohti).
3. Muud rollid — 403 (not.have.access).
4. Organisatsiooni ei leitud GLN-i järgi → 400 (organization.not.exists).

3.1 POST /organization/{gln}/locations — asukoha loomine/värskendamine¶

Uuendamisloogika:

1. Kui kehas on edastatud id – olemasoleva asukoha selgesõnaline uuendamine selle sisemise ID järgi (see peab kuuluma määratud organisatsioonile, vastasel juhul 404).
2. Kui id-d ei edastata, aga iln on edastatud – otsitakse organisatsiooni olemasolevat asukohta selle iln alusel; kui leitakse, siis seda uuendatakse, kui mitte, luuakse uus.
3. Kui iln-i samuti ei edastata (või see on "tühi" vastavalt IlnHelper.isEmpty-le) – asukoha GLN genereeritakse automaatselt (vt allpool).

Päringu keha (LoccatLocationWithIdData — LoccatLocationData + valikuline id):

Väli	Tüüp	Nõutud	Piirangud
id	Long	ei	selgesõnaliseks uuendamiseks
iln	string	ei	kuni 13 märki; puudumisel – genereeritakse automaatselt
codeBySender	string	jah	kuni 70 märki
codeByReceiver	string	ei	kuni 70 märki
name	string	jah	kuni 175 märki
legal	boolean	ei	"juriidilise aadressi" lipp
formattedAddress	string	ei	kuni 300 märki
streetAndNumber	string	ei	kuni 140 märki
streetAndNumber2	string	ei	kuni 140 märki
city	string	ei	kuni 175 märki
state	string	ei	kuni 175 märki
postalCode	string	ei	kuni 9 märki
countryCode	string	ei	kuni 2 märki
latitude / longitude	double	ei
remarks	string	ei	kuni 350 märki
phoneNumber	string	ei	kuni 175 märki
email	string	ei	kuni 350 märki, e-posti formaat
web	string	ei	kuni 175 märki

Vastus (200): sama keha + loodud/uuendatud asukoha id.

Asukoha GLN-i automaatne genereerimine (kui iln-i pole edastatud)¶

See kasutab pärandalgoritmi UserWebController.getNextLocalizationCatalogGln (tuum):

1. Kui organisatsioonil on juba asukohad (maxIln leitud) → järgmine GLN = viimati genereeritud GLN-i keha + 1.
2. Kui asukohti pole ja organisatsioon on testorganisatsioon (isTest) → GLN ehitatakse organisatsiooni glnPrefix-ist, mis on täidetud nullidega.
3. Kui asukohti pole, organisatsioon ei ole testorganisatsioon ja "legaalset" asukohta pole → tagastatakse organisatsiooni enda GLN.
4. Kui on legaalne asukoht, kuid teisi pole (äärmusjuhtum) → GLN ehitatakse glnPrefix-ist.

Lisaks (muudatus sellest piletist): kui sel viisil genereeritud GLN langeb kokku organisatsiooni enda GLN-iga (punktid 2 ja 3 ülal) – seda suurendatakse 1 võrra, nii et see ei dubleeriks kunagi organisatsiooni GLN-i.

Teadaolevad piirangud (aktsepteeritud sellisel kujul, ilma täiendava kaitsmeta):

1. Tehingulist lukku "järgmise GLN-i hankimise" ja "asukoha loomise sellega" vahel ei ole – paralleelsete päringutega ilma iln-ita on võimalik võidujooks ja 400 duplicate.line.iln.
2. Ülevoolu korral suurendamine (GLN-i keha = 999999999999) võiks teoreetiliselt luua GLN-i, mis on ühe märgi võrra pikem kui tavaline – äärmiselt ebatõenäoline äärmusjuhtum, parandust ei palutud.
3. legal lippu EI seata automaatselt esimesele asukohale, mis luuakse ilma iln-ita – kui organisatsioonil pole legaalset asukohta, proovib korduv POST ilma iln-ita uuesti sama organisatsiooni GLN-i genereerida ja ebaõnnestub veaga 400 duplicate.line.iln. Klient peab kas teisel ja järgnevatel päringutel iln-i selgesõnaliselt edastama või legal-i ise haldama.

3.2 GET /organization/{gln}/locations — asukohtade saamine¶

Üksikasjad: filter edastatakse GET-päringu kehas (JSON); need ei ole päringuparameetrid. Kui keha on tühi (Content-Length <= 0) – tagastatakse kõik organisatsiooni asukohad.

Päringu keha (valikuline):

Väli	Tüüp	Kirjeldus
id	Long	täpne otsing asukoha ID järgi (lisaks valikuline kontroll ILN-i vastu, kui see on edastatud)
iln	string	filter GLN-i järgi
name	string	filter nime järgi (alamstring)
address	string	filter aadressi järgi (alamstring)

Prioriteet: kui id on edastatud – tagastatakse (maksimaalselt) üks asukoht ID järgi; vastasel juhul, kui vähemalt üks iln/name/address on määratud – filtreeritud otsing; vastasel juhul – kõik organisatsiooni asukohad.

Vastus (200): asukohtade massiiv (sama formaat nagu POST-vastuses).

3.3 DELETE /organization/{gln}/locations¶

Päringu keha (kohustuslik):

Väli	Tüüp	Nõutud
id	Long	jah

Kustutamine ainult sisemise asukoha ID järgi; ILN-i järgi kustutamist ei ole rakendatud (seda kaaluti ja sellest loobuti selle pileti raames).

Vastus: 200 õnnestumisel, 404, kui selle ID-ga asukohta organisatsioonis ei leita, 400 location.id.should.be.specified, kui id ei ole edastatud.

---

4. Organisatsiooni GLN-i muutmine¶

PATCH /organization/{organizationId}/gln?gln=<new GLN>¶

Märkus: siin on {organizationId} organisatsiooni numbriline sisemine id (erinevalt ülaltoodud asukoha lõpp-punktidest, mis tee peal võtavad GLN-i).

Õigused:

1. SYSTEM_ADMIN / SYSTEM_SUPPORT — piiranguteta.
2. PROVIDER_ADMIN — ainult juhul, kui helistaja organisatsioon = sihtorganisatsiooni operatorId.
3. Muud — 403 not.have.access.
4. Organisatsiooni ei leitud id järgi → 404 (tühi sisu).

Parameetrid:

Parameeter	Tüüp	Nõutav
gln	string	jah, päringuparameeter

Mis juhtub sees (standardne organisatsiooni uuendamise torujuhe taaskasutatakse, OrganizationUpdateEvent → OrganizationCommonUpdateHandler):

1. GLN-i formaadi valideerimine + kontrollnumber → 400 vea korral.
2. Dublikaadi kontroll — GLN ei tohi kuuluda teisele organisatsioonile → 400 Duplicate ILN.
3. Vana väärtus salvestatakse previousIln-i.
4. Kui organisatsioonil on "legaalne" LOCCAT asukoht — selle iln sünkroniseeritakse automaatselt organisatsiooni uue GLN-iga (loccatReconciliation). Kui legaalset asukohta ei ole — samm jäetakse vaikselt vahele.
5. Organisatsiooni uuendamise standardsed ühildamisetapid (partner/tingimus/teavitused jne, mis ei ole sellele funktsioonile spetsiifilised).

Vastus (200): organisatsiooni sisu (OrganizationWithIdData) koos juba rakendatud uue GLN-iga.

---

5. Lõpp-punktide kokkuvõtlik tabel¶

Meetod	Tee	Tee identifikaator	Rollid
POST	/user/organization	—	iga autentitud kasutaja
GET	/organizations/search	—	SYSTEM_ADMIN, SYSTEM_SUPPORT, PROVIDER_ADMIN
POST	/organization/{gln}/locations	GLN	SYSTEM_ADMIN, SYSTEM_SUPPORT, PROVIDER_ADMIN (operaatori ID vastavus)
GET	/organization/{gln}/locations	GLN	SYSTEM_ADMIN, SYSTEM_SUPPORT, PROVIDER_ADMIN (operaatori ID vastavus)
DELETE	/organization/{gln}/locations	GLN	SYSTEM_ADMIN, SYSTEM_SUPPORT, PROVIDER_ADMIN (operaatori ID vastavus)
PATCH	/organization/{organizationId}/gln	numbriline ID	SYSTEM_ADMIN, SYSTEM_SUPPORT, PROVIDER_ADMIN (operaatori ID vastavus)

---

6. Näited¶

# Create an organisation
curl --location --request POST 'https://api-test.docura.net/ap1/partner/api/user/organization' \
--header 'X-Authorization: <token>' \
--header 'Content-Type: application/json' \
--data '{
  "taxId": "EE100000001",
  "registrationNumber": "12345678",
  "name": "Example OU",
  "countryCode": "EE",
  "locale": "en" 
}'

# Search organisations
curl --location 'https://api-test.docura.net/ap1/partner/api/organizations/search?query=Example' \
--header 'X-Authorization: <token>'

# Create a location without an explicit GLN (auto-generation)
curl --location --request POST 'https://api-test.docura.net/ap1/partner/api/organization/<org_gln>/locations' \
--header 'X-Authorization: <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Warehouse 1",
  "codeBySender": "WH1",
  "countryCode": "EE" 
}'

# Get all locations of an organisation
curl --location 'https://api-test.docura.net/ap1/partner/api/organization/<org_gln>/locations' \
--header 'X-Authorization: <token>'

# Delete a location by id
curl --location --request DELETE 'https://api-test.docura.net/ap1/partner/api/organization/<org_gln>/locations' \
--header 'X-Authorization: <token>' \
--header 'Content-Type: application/json' \
--data '{"id": 682021}'

# Change an organisation's GLN
curl --location --request PATCH 'https://api-test.docura.net/ap1/partner/api/organization/<numeric_id>/gln?gln=2000005819995' \
--header 'X-Authorization: <token>'