Kohandatud väljade API

Kohandatud väljad võimaldavad laiendada Kordoni ressursse täiendavate atribuutidega, mis on spetsiifilised teie organisatsiooni vajadustele. Kohandatud välju saab lisada kõigile peamistele objektitüüpidele: Varad, Äriprotsessid, Kontrollid, Leiud, Nõuded, Riskid, Ülesanded ja Tarnijad.

Väljatüübid

Igal kohandatud väljal on kind, mis määrab andmetüübi ja saadaolevad konfiguratsioonivõimalused:

Kind	Nimi kasutajaliideses	Kirjeldus
`string`	Lühitekst	Üherealine tekstiväli
`text`	Pikk tekst	Mitmerealine tekstiala
`integer`	Arv	Täisarv valikulise min/max vahemikuga
`boolean`	Jah/Ei	Tõene või väär
`date`	Kuupäev	Kuupäevavalik valikulise mineviku/tuleviku piiranguga
`single_select`	Üksikvalik	Rippmenüü eelmääratletud valikutega
`multi_select`	Mitmikvalik	Mitme valiku tegemine eelmääratletud valikutest
`url`	Link	URL valikulise kuvatekstiga
`percentage`	Protsent	Arv seadistatava vahemikuga (vaikimisi 0–100)
`monetary`	Valuuta	Summa fikseeritud valuutaga
`file`	Faili üleslaadimine	Failimanused — üks või mitu faili

Välja seadistused

configuration objekt sisaldab tüübispetsiifilisi seadistusi. Enamik tüüpe kasutab tühja {}. Tüübid, mis aktsepteerivad seadistust:

integer

{
  "min_value": 0,
  "max_value": 1000
}

percentage

{
  "min_value": 0,
  "max_value": 100
}

date

{
  "restriction": "past_only"
}

Lubatud väärtused: "past_only", "future_only" või võti puudub täielikult (lubatakse igasugune kuupäev).

single_select ja multi_select

Valikuid hallatakse pärast loomist valikute otspunktide kaudu. Seadistus kajastab praegust olekut:

{
  "options": [
    { "id": "uuid", "label": "Aktiivne", "position": 1 },
    { "id": "uuid", "label": "Passiivne", "position": 2 }
  ]
}

url

{
  "allowed_protocols": ["http", "https"]
}

monetary

{
  "currency": "EUR"
}

currency väärtust ei saa pärast välja loomist muuta.

file

{
  "max_file_size_mb": 25,
  "allowed_content_types": ["image/*", "application/pdf"],
  "allow_multiple": false
}

Nähtavuse ja vormi valikud

Väli	Tüüp	Kirjeldus
`is_shown_in_forms`	boolean	Kuva väli loomise ja muutmise vormides. Vaikimisi: `false`.
`is_shown_in_detail_view`	boolean	Kuva väli detailvaates ja loendites. Vaikimisi: `false`.
`is_required`	boolean	Nõua välja täitmist enne salvestamist. Nõuab `is_shown_in_forms: true`. Ei toetata `boolean` väljadel. Vaikimisi: `false`.
`public`	boolean	Kas väli kuvatakse avalikes API vastustes. Vaikimisi: `true`.

Õigused

Admin ja Haldur rollid saavad kohandatud välju luua, muuta, kustutada ja ümber järjestada. Kõik autentitud kasutajad saavad välju lugeda ja file tüüpi väljadele lisatud faile alla laadida.

GET `/custom_fields/`

Kõikide organisatsiooni kohandatud väljade nimekiri.

Vastuse väljad

Väli	Tüüp	Kirjeldus
`id`	UUID	Kohandatud välja unikaalne tunnus
`name`	string	Välja sisemine nimi (väiketähed alakriipsudega)
`label`	string	Kasutajatele näidatav nimi
`description`	string	Välja eesmärgi kirjeldus (valikuline)
`kind`	string	Väljatüüp — vaata väljatüübid
`attribute_of`	string	Ressursitüüp, millele see väli kuulub (nt `"Asset"`, `"Risk"`)
`field_has_usage`	boolean	Kas mõnel kirjel on praegu selle välja väärtus
`is_required`	boolean	Kas väli tuleb täita
`is_shown_in_forms`	boolean	Kas väli kuvatakse loomise/muutmise vormides
`is_shown_in_detail_view`	boolean	Kas väli kuvatakse detailvaates/loendites
`public`	boolean	Kas väli on nähtav avalikes API vastustes
`configuration`	object	Tüübispetsiifilised seadistused ja valikud
`created_at`	timestamp	ISO 8601 loomise ajatempel
`updated_at`	timestamp	ISO 8601 viimase muudatuse ajatempel

curl --location GET \
--url "https://SINU_KORDONI_DOMEEN/api/v1/custom_fields/" \
--header "Authorization: Bearer SINU_VÕTI"

Vastuse näide

Staatus: 200

{
    "data": [
        {
            "id": "83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f",
            "name": "vendor_tier",
            "label": "Tarnija tase",
            "description": "",
            "kind": "single_select",
            "attribute_of": "Vendor",
            "field_has_usage": true,
            "is_required": false,
            "is_shown_in_forms": true,
            "is_shown_in_detail_view": true,
            "public": true,
            "configuration": {
                "options": [
                    { "id": "c1d2e3f4-0000-0000-0000-000000000001", "label": "Kuld", "position": 1 },
                    { "id": "c1d2e3f4-0000-0000-0000-000000000002", "label": "Hõbe", "position": 2 }
                ]
            },
            "created_at": "2026-02-20T11:19:53+00:00",
            "updated_at": "2026-02-20T11:19:53+00:00"
        }
    ],
    "meta": {
        "total_count": 1,
        "page": 1,
        "permissions": {
            "create": true
        }
    }
}

GET `/custom_fields/:id`

Konkreetse kohandatud välja päring ID järgi. Vastus sisaldab position, permissions ja valikuväljadel option_usage_counts — valik-ID-de kaart koos sellele praegu viitavate kirjete arvuga.

curl --location GET \
--url "https://SINU_KORDONI_DOMEEN/api/v1/custom_fields/83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f" \
--header "Authorization: Bearer SINU_VÕTI"

Vastuse näide

Staatus: 200

{
    "data": {
        "id": "83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f",
        "name": "vendor_tier",
        "label": "Tarnija tase",
        "description": "",
        "kind": "single_select",
        "attribute_of": "Vendor",
        "field_has_usage": true,
        "is_required": false,
        "is_shown_in_forms": true,
        "is_shown_in_detail_view": true,
        "public": true,
        "configuration": {
            "options": [
                { "id": "c1d2e3f4-0000-0000-0000-000000000001", "label": "Kuld", "position": 1 },
                { "id": "c1d2e3f4-0000-0000-0000-000000000002", "label": "Hõbe", "position": 2 }
            ]
        },
        "option_usage_counts": {
            "c1d2e3f4-0000-0000-0000-000000000001": 42,
            "c1d2e3f4-0000-0000-0000-000000000002": 15
        },
        "position": 1,
        "permissions": {
            "update": true,
            "destroy": true
        },
        "created_at": "2026-02-20T11:19:53+00:00",
        "updated_at": "2026-02-20T11:19:53+00:00"
    }
}

POST `/custom_fields/`

Uue kohandatud välja loomine.

Väli	Tüüp	Kohustuslik	Kirjeldus
`name`	string	Ei	Välja sisemine nimi (väiketähed, ainult alakriipsud). Genereeritakse automaatselt `label` põhjal, kui puudub. Peab olema unikaalne ressursitüübi piires.
`label`	string	Jah	Kasutajatele näidatav nimi.
`kind`	string	Jah	Väljatüüp — vaata väljatüübid. Ei saa muuta, kui väljal on juba andmeid.
`attribute_of`	string	Jah	Ressursitüüp: `Asset`, `BusinessProcess`, `Control`, `Finding`, `Requirement`, `Risk`, `Task` või `Vendor`.
`description`	string	Ei	Välja eesmärgi kirjeldus (valikuline).
`is_required`	boolean	Ei	Kas väli tuleb täita. Nõuab `is_shown_in_forms: true`. Vaikimisi: `false`.
`is_shown_in_forms`	boolean	Ei	Kuva loomise/muutmise vormides. Vaikimisi: `false`.
`is_shown_in_detail_view`	boolean	Ei	Kuva detailvaates/loendites. Vaikimisi: `false`.
`public`	boolean	Ei	Nähtav avalikes API vastustes. Vaikimisi: `true`.
`configuration`	object	Ei	Tüübispetsiifilised seadistused — vaata välja seadistused.

Näide: üksikvaliku välja loomine

curl --location POST \
--url "https://SINU_KORDONI_DOMEEN/api/v1/custom_fields/" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer SINU_VÕTI" \
--data '{
    "custom_field": {
        "label": "Tarnija tase",
        "kind": "single_select",
        "attribute_of": "Vendor",
        "description": "Tarnija klassifitseerimistase",
        "is_shown_in_forms": true,
        "is_shown_in_detail_view": true
    }
}'

Näide: valuuta välja loomine

curl --location POST \
--url "https://SINU_KORDONI_DOMEEN/api/v1/custom_fields/" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer SINU_VÕTI" \
--data '{
    "custom_field": {
        "label": "Lepingu väärtus",
        "kind": "monetary",
        "attribute_of": "Vendor",
        "is_shown_in_forms": true,
        "configuration": {
            "currency": "EUR"
        }
    }
}'

Vastuse näide

Staatus: 201

{
    "data": {
        "id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
        "name": "vendor_tier",
        "label": "Tarnija tase",
        "description": "Tarnija klassifitseerimistase",
        "kind": "single_select",
        "attribute_of": "Vendor",
        "field_has_usage": false,
        "is_required": false,
        "is_shown_in_forms": true,
        "is_shown_in_detail_view": true,
        "public": true,
        "configuration": { "options": [] },
        "position": 1,
        "permissions": {
            "update": true,
            "destroy": true
        },
        "created_at": "2026-06-01T12:30:45+00:00",
        "updated_at": "2026-06-01T12:30:45+00:00"
    }
}

PATCH `/custom_fields/:id`

Olemasoleva kohandatud välja uuendamine. Lisage ainult väljad, mida soovite muuta.

curl --location PATCH \
--url "https://SINU_KORDONI_DOMEEN/api/v1/custom_fields/83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer SINU_VÕTI" \
--data '{
    "custom_field": {
        "label": "Tarnija klassifikatsioon",
        "is_required": true,
        "is_shown_in_forms": true,
        "is_shown_in_detail_view": true
    }
}'

Vastuse näide

Staatus: 200

Tagastatakse täielik kohandatud välja objekt (sama kujuga kui ühe välja GET vastus).

DELETE `/custom_fields/:id`

Kohandatud välja kustutamine. Väli kustutatakse pehmelt — see eemaldatakse API-st, kuid olemasolevad kirjeandmed säilitatakse.

curl --location DELETE \
--url "https://SINU_KORDONI_DOMEEN/api/v1/custom_fields/83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f" \
--header "Authorization: Bearer SINU_VÕTI"

Vastus

Staatus: 204 No Content

PATCH `/custom_fields/:id/reorder`

Muuda kohandatud välja kuvajärjestust selle ressursitüübi piires. Positsioon on 1-põhine ja on scoped attribute_of järgi.

curl --location PATCH \
--url "https://SINU_KORDONI_DOMEEN/api/v1/custom_fields/83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f/reorder" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer SINU_VÕTI" \
--data '{
    "position": 3
}'

Vastuse näide

Staatus: 200

{
    "data": {
        "id": "83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f",
        "position": 3
    }
}

Valikute haldamine

single_select ja multi_select väljad haldavad oma valikuid eraldi otspunktide kaudu. Igal valikul on UUID, silt ja positsioon välja piires.

POST `/custom_fields/:id/options`

Lisa valikuväljale uus valik.

Väli	Tüüp	Kohustuslik	Kirjeldus
`label`	string	Jah	Valiku kuvatekst
`value`	string	Ei	Sisemine väärtuse kaardistus. Kui puudub, kasutatakse silti.

curl --location POST \
--url "https://SINU_KORDONI_DOMEEN/api/v1/custom_fields/83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f/options" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer SINU_VÕTI" \
--data '{
    "option": {
        "label": "Kuld"
    }
}'

Vastuse näide

Staatus: 201

{
    "data": {
        "option_id": "c1d2e3f4-0000-0000-0000-000000000001",
        "configuration": {
            "options": [
                { "id": "c1d2e3f4-0000-0000-0000-000000000001", "label": "Kuld", "position": 1 }
            ]
        }
    }
}

PATCH `/custom_fields/:id/options/:option_id`

Nimeta olemasolev valik ümber. Sellele valikule viitavad kirjeväärtused ei muutu.

curl --location PATCH \
--url "https://SINU_KORDONI_DOMEEN/api/v1/custom_fields/83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f/options/c1d2e3f4-0000-0000-0000-000000000001" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer SINU_VÕTI" \
--data '{
    "option": {
        "label": "Plaatina"
    }
}'

Vastuse näide

Staatus: 200

{
    "data": {
        "option_id": "c1d2e3f4-0000-0000-0000-000000000001",
        "configuration": {
            "options": [
                { "id": "c1d2e3f4-0000-0000-0000-000000000001", "label": "Plaatina", "position": 1 },
                { "id": "c1d2e3f4-0000-0000-0000-000000000002", "label": "Hõbe", "position": 2 }
            ]
        }
    }
}

DELETE `/custom_fields/:id/options/:option_id`

Kustuta valik. Kui mõned kirjed kasutavad praegu seda valikut, peate esitama replacement_option_id — need kirjed migreeritakse asendusvalikule. Kasutuses oleva valiku kustutamine ilma asenduseta tagastab 422 vea.

Päringuparameetrid

Parameeter	Tüüp	Kirjeldus
`replacement_option_id`	UUID	Kohustuslik, kui kirjed viitavad sellele valikule. Need kirjed migreeritakse asendusvalikule.

curl --location DELETE \
--url "https://SINU_KORDONI_DOMEEN/api/v1/custom_fields/83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f/options/c1d2e3f4-0000-0000-0000-000000000002?replacement_option_id=c1d2e3f4-0000-0000-0000-000000000001" \
--header "Authorization: Bearer SINU_VÕTI"

Vastuse näide

Staatus: 200

{
    "data": {
        "affected_count": 15,
        "async": false,
        "configuration": {
            "options": [
                { "id": "c1d2e3f4-0000-0000-0000-000000000001", "label": "Kuld", "position": 1 }
            ]
        }
    }
}

Kui affected_count on 100 või rohkem, käivitatakse migratsioon taustatöö kaudu ja tagastatakse "async": true. Valik eemaldatakse väljalt koheselt; kirjete uuendused toimuvad asünkroonselt.

GET `/custom_fields/:id/options/:option_id/usage`

Kontrolli, kui palju kirjeid kasutab praegu konkreetset valikut — kasulik enne kustutamist.

curl --location GET \
--url "https://SINU_KORDONI_DOMEEN/api/v1/custom_fields/83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f/options/c1d2e3f4-0000-0000-0000-000000000001/usage" \
--header "Authorization: Bearer SINU_VÕTI"

Vastuse näide

Staatus: 200

{
    "data": {
        "option_id": "c1d2e3f4-0000-0000-0000-000000000001",
        "usage_count": 42
    }
}

Failide allalaadimine

file tüüpi väljade puhul on failid manustatud kirje kaupa. Kasutage neid otspunkte failide hankimiseks.

GET `/custom_fields/:id/file/:attachment_id`

Tagastab allalaadimise URL-i ja faili nime konkreetse manuse jaoks.

Vastuse näide

Staatus: 200

{
    "data": {
        "url": "/api/v1/custom_fields/83d028c1.../file/att-uuid/download",
        "filename": "leping.pdf"
    }
}

GET `/custom_fields/:id/file/:attachment_id/download`

Edastab faili otse. Aktsepteerib valikulist disposition päringuparmeetrit: inline (vaikimisi) või attachment.

Kohandatud väljade väärtuste seadmine ressurssidel

Kui kohandatud väli on loodud, seadke selle väärtus, lisades välja name võtmena PATCH päringus vastavasse ressursi otspunkti.

Väärtuse formaat väljatüübi järgi

Kind	Oodatav väärtus	Näide
`string`	string	`"Acme Corp"`
`text`	string	`"Mitmerealiline\ntekst"`
`integer`	täisarv	`42`
`boolean`	boolean	`true`
`date`	ISO 8601 kuupäeva string	`"2026-12-31"`
`single_select`	valiku UUID	`"c1d2e3f4-0000-0000-0000-000000000001"`
`multi_select`	valikute UUID-de massiiv	`["c1d2e3f4-...", "c1d2e3f4-..."]`
`url`	objekt `url` ja valikulise `display_text` väljaga	`{"url": "https://example.com", "display_text": "Veebisait"}`
`percentage`	arv	`75.5`
`monetary`	arv	`12500.00`

Näide: üksikvaliku väärtuse seadmine riskil

curl --location PATCH \
--url "https://SINU_KORDONI_DOMEEN/api/v1/risks/RISKI_ID" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer SINU_VÕTI" \
--data '{
    "risk": {
        "riski_kategooria": "c1d2e3f4-0000-0000-0000-000000000001"
    }
}'

Näide: URL-välja seadmine

curl --location PATCH \
--url "https://SINU_KORDONI_DOMEEN/api/v1/vendors/TARNIJA_ID" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer SINU_VÕTI" \
--data '{
    "vendor": {
        "lepingu_link": {
            "url": "https://contracts.example.com/vendor-123",
            "display_text": "Põhileping"
        }
    }
}'

Näide: mitme kohandatud välja seadmine korraga

curl --location PATCH \
--url "https://SINU_KORDONI_DOMEEN/api/v1/assets/VARA_ID" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer SINU_VÕTI" \
--data '{
    "asset": {
        "osakond": "Inseneeria",
        "asenduskulu": 15000.00,
        "viimati_kontrollitud": "2026-05-15"
    }
}'

Kohandatud välja väärtuse tühjendamine

Seadke väli null väärtusele selle tühjendamiseks:

curl --location PATCH \
--url "https://SINU_KORDONI_DOMEEN/api/v1/risks/RISKI_ID" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer SINU_VÕTI" \
--data '{
    "risk": {
        "riski_kategooria": null
    }
}'

Kohandatud väljade API

Väljatüübid

Välja seadistused

Nähtavuse ja vormi valikud

Õigused

GET /custom_fields/

GET /custom_fields/:id

POST /custom_fields/

PATCH /custom_fields/:id

DELETE /custom_fields/:id

PATCH /custom_fields/:id/reorder

Valikute haldamine

POST /custom_fields/:id/options

PATCH /custom_fields/:id/options/:option_id

DELETE /custom_fields/:id/options/:option_id

GET /custom_fields/:id/options/:option_id/usage

Failide allalaadimine

GET /custom_fields/:id/file/:attachment_id

GET /custom_fields/:id/file/:attachment_id/download

Kohandatud väljade väärtuste seadmine ressurssidel

Väärtuse formaat väljatüübi järgi

Kohandatud välja väärtuse tühjendamine

GET `/custom_fields/`

GET `/custom_fields/:id`

POST `/custom_fields/`

PATCH `/custom_fields/:id`

DELETE `/custom_fields/:id`

PATCH `/custom_fields/:id/reorder`

POST `/custom_fields/:id/options`

PATCH `/custom_fields/:id/options/:option_id`

DELETE `/custom_fields/:id/options/:option_id`

GET `/custom_fields/:id/options/:option_id/usage`

GET `/custom_fields/:id/file/:attachment_id`

GET `/custom_fields/:id/file/:attachment_id/download`