Utseende

REST-API ​

HIT inkluderar ett REST-API som låter dig utföra vissa åtgärder från ett annat system.

Autentisering ​

För att använda API:et behöver du först skapa en API-nyckel under Min profil → Säkerhet → API-nycklar.

Behörigheter

API-nycklar har samma behörigheter som användaren som skapade nyckeln. Det går dock att skapa en nyckel med endast läsrättigheter.

Varje API-anrop behöver ha headern Authorization: Bearer <nyckel>:

sh
curl -H 'Authorization: Bearer <apitoken>' https://din-hit-domän/api/queues

Basadressen

Byt ut din-hit-domän mot adressen ni når HIT på — samma värdnamn som i webbläsaren.

Anrop som ska få svar i JSON bör dessutom skicka med headern Accept: application/json.

Lista tillgängliga köer ​

Metod: GETEndpoint: /api/queues

Exempel på anrop:

sh
curl -H 'Authorization: Bearer <apitoken>' https://din-hit-domän/api/queues

Exempel på svar:

json
{
    "status": "OK",
    "queues": [
        {
            "id": 1,
            "name": "Demoskolan IT"
        },
        {
            "id": 2,
            "name": "Demoskolan Vaktis"
        }
    ]
}

Lista ärenden i en kö ​

Metod: GETEndpoint: /api/queues/{queueId}/tickets

Exempel på anrop:

sh
curl -H 'Authorization: Bearer <apitoken>' https://din-hit-domän/api/queues/1/tickets

Exempel på svar:

json
{
    "status": "OK",
    "page": 1,
    "limit": 50,
    "tickets_count": 42,
    "tickets": [
        {
            "id": 67,
            "submitter_name": "Robin Friberg",
            "submitter_email": "robin@devpeak.se",
            "subject": "Nothing to see here",
            "date": "2023-07-12T06:04:50.000000Z",
            "closed_date": null
        },
        {
            "id": 66,
            "submitter_name": "Robin Friberg",
            "submitter_email": "robin@devpeak.se",
            "subject": "Other ticket",
            "date": "2023-07-09T08:07:29.000000Z",
            "closed_date": null
        }
    ]
}

Sök efter ärenden i en kö ​

Metod: GETEndpoint: /api/queues/{queueId}/tickets

Krävda parametrar:

  • search

Exempel på anrop:

sh
curl -H 'Authorization: Bearer <apitoken>' 'https://din-hit-domän/api/queues/1/tickets?search=Something'

Exempel på svar:

json
{
    "status": "OK",
    "page": 1,
    "limit": 50,
    "tickets_count": 42,
    "tickets": [
        {
            "id": 67,
            "submitter_name": "Robin Friberg",
            "submitter_email": "robin@devpeak.se",
            "subject": "Nothing to see here",
            "date": "2023-07-12T06:04:50.000000Z",
            "closed_date": null
        },
        {
            "id": 66,
            "submitter_name": "Robin Friberg",
            "submitter_email": "robin@devpeak.se",
            "subject": "Other ticket",
            "date": "2023-07-09T08:07:29.000000Z",
            "closed_date": null
        }
    ]
}

Skapa nytt ärende ​

Metod: POSTEndpoint: /api/queues/{queueId}/tickets

Krävda parametrar:

  • subject
  • description

Valfria parametrar:

  • submitter
  • submitter_name
  • notify_submitter
  • priority
  • owner
  • category
  • customer
  • status
  • duedate
  • hideuntil
  • files[]

priority är 0–3 (låg till kritisk). owner, category, customer och status måste tillhöra kön. category, customer, status, duedate och hideuntil kräver dessutom att motsvarande modul är påslagen i kön, och varje valfritt fält kräver samma behörighet som att ändra det på ett befintligt ärende.

Exempel på anrop:

sh
curl -H 'Authorization: Bearer <apitoken>' -X POST \
  -d 'subject=A well written subject&description=Not so well written description&submitter=reporter@example.com&priority=3&duedate=2026-09-01' \
  https://din-hit-domän/api/queues/1/tickets

Exempel på svar:

json
{
    "status": "OK",
    "message": "Your ticket has been created correctly",
    "ticketid": 73
}

Lista ärendemallar ​

Metod: GETEndpoint: /api/queues/{queueId}/tickettemplates

Exempel på anrop:

sh
curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  https://din-hit-domän/api/queues/1/tickettemplates

Exempel på svar:

json
{
    "status": "OK",
    "tickettemplates": [
        {
            "id": 1,
            "name": "A ticket template",
            "description": "Description of the ticket template",
            "template_text": "<p>Some HTML content</p>",
            "subtickets": [
                {
                    "id": 1,
                    "subject": "A subticket for this ticket template",
                    "tickettemplate": 1
                },
                {
                    "id": 2,
                    "subject": "Another subticket for this ticket template",
                    "tickettemplate": 1
                }
            ]
        }
    ]
}

Skapa nya ärenden från en ärendemall ​

Metod: POSTEndpoint: /api/queues/{queueId}/tickets

Krävda parametrar:

  • subject
  • description
  • template
  • subtickets

Valfria parametrar:

  • should_mail — styr handläggarnotisen för huvudärendet. Anges den gäller den även samtliga underärenden, om inte subtickets_mail skickas med. Utelämnas den används mallens egen inställning för huvudärendet respektive varje underärende.
  • subtickets_mail — kommaseparerad lista med de underärenden som ska ge handläggarnotis. Måste vara en delmängd av subtickets. Underärenden som utelämnas ur listan notifierar inte.

Exempel på anrop:

sh
curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' -X POST \
  -d 'template=1&subject=New user&description=A new user should be created called Example_User&should_mail=0&subtickets=1,2' \
  https://din-hit-domän/api/queues/1/tickets

Exempel där bara underärende 2 ska notifiera handläggare:

sh
curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' -X POST \
  -d 'template=1&subject=New user&description=A new user should be created called Example_User&subtickets=1,2&subtickets_mail=2' \
  https://din-hit-domän/api/queues/1/tickets

Exempel på svar:

json
{
    "status": "OK",
    "message": "Your ticket has been created correctly",
    "ticketid": 84
}

Visa ärende ​

Metod: GETEndpoint: /api/tickets/{ticketId}

Exempel på anrop:

sh
curl -H 'Authorization: Bearer <apitoken>' -H 'Accept: application/json' \
  https://din-hit-domän/api/tickets/1

Exempel på svar:

json
{
    "status": "OK",
    "ticket": {
        "id": 85,
        "submitter_name": "Robin Friberg",
        "submitter_email": "robin@devpeak.se",
        "subject": "An example ticket",
        "date": "2023-07-14T13:42:10.000000Z",
        "closed_date": null,
        "description": "<p>With a somewhat normal description.</p>",
        "priority": "low",
        "duedate": null,
        "last_activity": "2023-07-14T13:42:10.000000Z",
        "link": "https://din-hit-domän/view?id=85"
    }
}

Devpeak AB