API Skjölun | Wise handbækur

API kerfishluti Wise Sveitarstjórnarkerfisins veitir öflugar REST API þjónustur sem gera utanaðkomandi kerfum kleift að nálgast og vinna með gögn Business Central með öruggum hætti. Þessar API þjónustur eru sérstaklega hannaðar fyrir sveitarstjórnaþarfir og styðja samþættingu við ytri kerfi eins og vefsíður, farsímaforrit og þriðja aðila hugbúnað.

Skjámyndarstaðsetning: API yfirlit sem sýnir tiltæka endapunkta og auðkenningarflæði

Helstu eiginleikar

Örugg REST API þjónusta

OAuth 2.0 auðkenning: Tryggð API aðgangur með nútíma auðkenningarstöðlum
HTTPS dulkóðun: Öll API samskipti eru dulkóðuð og örugg
Takmörkun á aðgangi: Notendamiðaður aðgangur með heimildarstjórnun
Audit leiðir: Fullkomin skráning allra API kalla og gagnaaðgangs

Sveitarstjórnarmiðaðar API þjónustur

Viðskiptareikningar: Aðgangur að sveitarfélagsþjónustutegundum og flokkun
Vinnubeiðnir: Samþætting við vinnubeiðnistjórnunarkerfi
Fjárhagsgögn: Aðgangur að fjárhagsupplýsingum með víddastýringu
Viðskiptavinagögn: Örugg samþætting við íbúaþjónustu

Þróunarvinir eiginleikar

OpenAPI forskrift: Sjálfkrafa API skjölun og próf
JSON snið: Staðlað JSON gagnasnið fyrir auðvelda samþættingu
OData stefna: Stuðningur við OData leitarskilyrði og síun
Sveigjanleiki útgáfu: Framhlutun samhæfni milli útgáfna

API sniðmát og endapunktar

Grunn URL skipulag

Skjámyndarstaðsetning: API endapunkta skipulag með dæmum um URL slóðir

Framleiðsluumhverfi

https://[tenant].api.businesscentral.dynamics.com/v2.0/[environment]/api/wise/sve/v1.0/

Sandkassitest

https://[tenant].sandbox.api.businesscentral.dynamics.com/v2.0/[environment]/api/wise/sve/v1.0/

URL breytur:

[tenant]: Microsoft 365 leigjandaheiti
[environment]: Business Central umhverfisnafn (framleiðsla, sandbox)
wise: API útgefandi (Wise ehf.)
sve: API flokkur (Sveitarstjórnarkerfi)
v1.0: API útgáfa

Tiltækar API þjónustur

1. Viðskiptareikningar API

Endapunktur: /businessAccounts
Tilvísun: SveBusinessAccountAPI (Page 10008086)

Skjámyndarstaðsetning: Viðskiptareikningar API sýnidæmi með JSON svari

Tilgangur: Veitir aðgang að skilgreindum viðskiptareikningum sveitarfélagsins fyrir þjónustuflokkunar- og tekjustjórnunartilgangi.

Studdar aðgerðir:

GET: Sækja lista yfir viðskiptareikninga
GET {id}: Sækja ákveðinn viðskiptareikning
POST: Búa til nýjan viðskiptareikning
PATCH {id}: Uppfæra viðskiptareikning
DELETE {id}: Eyða viðskiptareikningi

Svargagnastrúktúr:

JSON

{
  "value": [
    {
      "id": "system-generated-guid",
      "code": "VATN001",
      "description": "Vatnsveita - heimili",
      "postingGroup": "VATN",
      "type": "Service", 
      "visibleOnWeb": true,
      "systemCreatedAt": "2024-01-15T10:30:00Z",
      "systemModifiedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Svæðalýsingar:

code: Einstakur kóti viðskiptareiknings (hámark 10 stafir)
description: Lýsandi heiti viðskiptareiknings
postingGroup: Tengdur bókunarhópur fyrir fjárhagslega meðhöndlun
type: Tegund viðskiptareiknings (þjónusta, vara, gjald)
visibleOnWeb: Hvort reikningur birtist á vefþjónustu

2. Vinnubeiðnir API

Endapunktur: /jobRequests
Tilvísun: SveJobRequestAPI (Page 10008138)

Skjámyndarstaðsetning: Vinnubeiðnir API með dæmi um POST beiðni

Tilgangur: Gerir ytri kerfum kleift að búa til og stjórna vinnubeiðnum fyrir viðhald sveitarfélagsins og þjónustu.

Studd svæði:

number: Einstakt númer vinnubeiðni (sjálfkrafa úthlutað)
requesterNumber: Kennitala/númer þess sem biður um vinnu
requesterName: Nafn þess sem biður um vinnu
responsible: Ábyrgðarmaður fyrir framkvæmd
workDepartment: Vinnudeild sem sér um verkið
shortDescription: Stutt lýsing á verkinu
description: Nákvæm lýsing á vinnubeiðni
priority: Forgangsstig (Lágt, Miðlungs, Hátt, Brýnt)
urgency: Brýnni (Já/Nei)
promisedDate: Lofuð lokadagsetning
phoneNumber: Símanúmer þess sem biður

Sjálfvirkir eiginleikar:

Notandastjórnun: Búur sjálfkrafa til vinnubeiðninotendur úr netföngum
Kennitalaprófun: Staðfestir íslenskar kennitölur
Vímunarstig: Setur sjálfkrafa vímunarkóta út frá uppsetningu
Stöðustjórnun: Stjórnar verkflæði vinnubeiðna

3. Viðbótar API þjónustur

Fyrirtækisupplýsingar API:

Endapunktur: /companyInfo
Tilgangur: Grunnupplýsingar um sveitarfélagið

Viðskiptavinabókarfærslur API:

Endapunktur: /customerLedgerEntries
Tilgangur: Fjárhagsleg saga viðskiptavina

Viðskiptareikningar viðskiptavina API:

Endapunktur: /customerBusinessAccounts
Tilgangur: Tengsl viðskiptavina við þjónustuflokka

Sölureikningshausar API:

Endapunktur: /salesInvoiceHeaders
Tilgangur: Aðgangur að sölureikningum

Sölureikningslínur API:

Endapunktur: /salesInvoiceLines
Tilgangur: Nákvæm línuatriði reikninga

Auðkenning og öryggi

OAuth 2.0 uppsetning

Skjámyndarstaðsetning: OAuth 2.0 stillingarferli með Azure AD skráningu

Skref 1: Azure Active Directory skráning

Skrá forrit í Azure AD gáttinni
Stilla API heimildir fyrir Business Central
Búa til client secret fyrir örugg samskipti
Stilla callback URLs fyrir auðkenningarflæði

Nauðsynlegar heimildir:

https://api.businesscentral.dynamics.com/user_impersonation
https://api.businesscentral.dynamics.com/.default

Skref 2: Fá aðgangstókn

Token endapunktur:

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token

Beiðnigögn:

grant_type=client_credentials
&client_id={your-client-id}
&client_secret={your-client-secret}
&scope=https://api.businesscentral.dynamics.com/.default

Dæmi um svar:

JSON

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJS...",
  "scope": "https://api.businesscentral.dynamics.com/.default"
}

Skref 3: Nota tókn í API köllum

Authorization header:

Authorization: Bearer {access-token}

Öryggisatriði

Aðgangsstýring

Notendamiðaður aðgangur: API kall takmarkast við heimildir þess notanda sem er auðkenndur
Hlutverkastýring: Mismunandi aðgangur eftir notendahlutverki
Víddastýring: Aðgangur takmarkaður við ákveðnar deildir/verkefni
Tímatakmörkun: Tókn renna út og þarf að endurnýja reglulega

Gagnaskipti öryggi

HTTPS krafist: Öll API samskipti verða að nota HTTPS
Rate limiting: Takmarkanir á fjölda API kalla á mínútu
Skráning og endurskoðun: Öll API köll eru skráð í öryggisskyni
Gögnumöskvun: Viðkvæmar upplýsingar eru faldar í loggar

Dæmi um notkun

JavaScript/Node.js dæmi

Skjámyndarstaðsetning: Kóðadæmi sem sýnir JavaScript API integration

Sækja lista yfir viðskiptareikninga

JavaScript

const fetch = require('node-fetch');

async function getBusinessAccounts() {
  const token = await getAccessToken(); // Útfærsla fyrir OAuth
  
  const response = await fetch(
    'https://tenant.api.businesscentral.dynamics.com/v2.0/production/api/wise/sve/v1.0/businessAccounts',
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  
  const data = await response.json();
  return data.value;
}

Búa til nýja vinnubeiðni

JavaScript

async function createJobRequest(requestData) {
  const token = await getAccessToken();
  
  const response = await fetch(
    'https://tenant.api.businesscentral.dynamics.com/v2.0/production/api/wise/sve/v1.0/jobRequests',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        requesterName: requestData.name,
        requesterEmail: requestData.email,
        phoneNumber: requestData.phone,
        shortDescription: requestData.title,
        description: requestData.details,
        priority: requestData.priority || 'Medium'
      })
    }
  );
  
  return await response.json();
}

Python dæmi

OAuth auðkenning og API köll

Python

import requests
import json
from datetime import datetime, timedelta

class WiseAPI:
    def __init__(self, tenant, client_id, client_secret, environment='production'):
        self.tenant = tenant
        self.client_id = client_id
        self.client_secret = client_secret
        self.environment = environment
        self.base_url = f"https://{tenant}.api.businesscentral.dynamics.com/v2.0/{environment}/api/wise/sve/v1.0"
        self.token = None
        self.token_expires = None
    
    def get_access_token(self):
        if self.token and self.token_expires > datetime.now():
            return self.token
        
        url = f"https://login.microsoftonline.com/{self.tenant}/oauth2/v2.0/token"
        data = {
            'grant_type': 'client_credentials',
            'client_id': self.client_id,
            'client_secret': self.client_secret,
            'scope': 'https://api.businesscentral.dynamics.com/.default'
        }
        
        response = requests.post(url, data=data)
        response.raise_for_status()
        
        token_data = response.json()
        self.token = token_data['access_token']
        self.token_expires = datetime.now() + timedelta(seconds=token_data['expires_in'] - 300)
        
        return self.token
    
    def get_business_accounts(self):
        headers = {
            'Authorization': f'Bearer {self.get_access_token()}',
            'Content-Type': 'application/json'
        }
        
        response = requests.get(f"{self.base_url}/businessAccounts", headers=headers)
        response.raise_for_status()
        
        return response.json()['value']

C# .NET dæmi

Skjámyndarstaðsetning: C# kóðadæmi fyrir .NET samþættingu

API biðlari klasi

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class WiseMunicipalAPI
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;
    private readonly string _tenantId;
    private readonly string _clientId;
    private readonly string _clientSecret;
    
    public WiseMunicipalAPI(string tenant, string clientId, string clientSecret, string environment = "production")
    {
        _httpClient = new HttpClient();
        _baseUrl = $"https://{tenant}.api.businesscentral.dynamics.com/v2.0/{environment}/api/wise/sve/v1.0";
        _tenantId = tenant;
        _clientId = clientId;
        _clientSecret = clientSecret;
    }
    
    public async Task<string> GetAccessTokenAsync()
    {
        var tokenUrl = $"https://login.microsoftonline.com/{_tenantId}/oauth2/v2.0/token";
        var requestBody = $"grant_type=client_credentials&client_id={_clientId}&client_secret={_clientSecret}&scope=https://api.businesscentral.dynamics.com/.default";
        
        var response = await _httpClient.PostAsync(tokenUrl, new StringContent(requestBody, Encoding.UTF8, "application/x-www-form-urlencoded"));
        var responseContent = await response.Content.ReadAsStringAsync();
        var tokenResponse = JsonConvert.DeserializeObject<dynamic>(responseContent);
        
        return tokenResponse.access_token;
    }
    
    public async Task<T> GetAsync<T>(string endpoint)
    {
        var token = await GetAccessTokenAsync();
        _httpClient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
        
        var response = await _httpClient.GetAsync($"{_baseUrl}/{endpoint}");
        response.EnsureSuccessStatusCode();
        
        var content = await response.Content.ReadAsStringAsync();
        return JsonConvert.DeserializeObject<T>(content);
    }
}

Villustjórnun og úrræðaleit

Algengar villur og lausnir

Skjámyndarstaðsetning: Villubótin með dæmum um villuskilaboð og lausnir

401 Unauthorized

Orsök: Auðkenningarvilla eða útrunnið tókn
Lausnir:

Staðfesta að client ID og secret séu rétt
Endurnýja access token
Athuga að nauðsynlegar heimildir séu veittar í Azure AD

403 Forbidden

Orsök: Notandinn hefur ekki aðgang að umbeðnum gögnum
Lausnir:

Staðfesta notendaheimildir í Business Central
Athuga víddatakmarkanir fyrir notandann
Staðfesta að viðeigandi permission set sé úthlutað

404 Not Found

Orsök: Endapunktur eða gögn finnast ekki
Lausnir:

Staðfesta að URL slóð sé rétt
Athuga að umbeðin gögn séu til
Staðfesta API útgáfu í URL

429 Too Many Requests

Orsök: Of mörg API köll innan ákveðins tíma
Lausnir:

Útfæra exponential backoff stefnu
Minnka tíðni API kalla
Nota batch aðgerðir þar sem mögulegt er
Athuga rate limiting stefnu

Bestu starfsvenjur

Afköst og skilvirkni

Cache tókn: Vistaðu access tókn þar til það rennur út
Batch aðgerðir: Notaðu fjöldaaðgerðir þar sem mögulegt er
Síun: Notaðu OData síur til að takmarka gagnasafn
Paging: Útfærðu paging fyrir stór gagnasöfn
Compression: Notaðu gzip compression fyrir stórar beiðnir

Öryggi

Varðveittu secrets örugg: Geymdu client secrets á öruggum stað
Notaðu HTTPS: Aldrei senda næm gögn yfir HTTP
Takmörk heimildir: Biðjið aðeins um nauðsynlegar heimildir
Logga aðgang: Skráðu alla API notkun í öryggisskyni
Uppfærslu reglulega: Haldtu libraries og dependencies uppfærðum

Villumeðhöndlun

JavaScript

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        // Rate limited - wait and retry
        const retryAfter = response.headers.get('Retry-After') || Math.pow(2, attempt);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }
      
      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
      // Wait before retry
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}

Prófanir og þróunarumhverfi

Sandbox umhverfi

Skjámyndarstaðsetning: Sandbox uppsetning og prófanarleiðbeiningar

Uppsetning prófanaraðgangs

Búa til sandbox umhverfi í Business Central
Skrá þróunarforrit í Azure AD
Stilla redirect URLs fyrir þróunaruppsetningu
Nota sandbox endpoint: .sandbox.api.businesscentral.dynamics.com

Prófanargögn

Sandbox umhverfið inniheldur:

Dæmi viðskiptareikninga fyrir allar helstu þjónustutegundir
Prófunarviðskiptavini með íslenskum kennitölum
Dæmi vinnubeiðnir með mismunandi forgangi
Prófunargögn fyrir allar API þjónustur

API prófunarverkfæri

Postman safn

Við bjóðum upp á Postman safn með:

Öllum API endapunktum með dæmabeiðnum
Auðkenningarskiptum fyrir OAuth 2.0
Prófunarskriptum fyrir sjálfvirkar prófanir
Umhverfisbreytum fyrir mismunandi uppsetningu

Swagger/OpenAPI

Gagnvirk API skjölun á /swagger endapunkti
Prófunarviðmót fyrir alla endapunkta
Schema sannprófun fyrir beiðnir og svör
Kóðamyndun fyrir mismunandi forritunarmál

Framtíðarþróun og útgáfustjórnun

Útgáfustefna

Framhlutun samhæfni: v1.0 endapunktar verða studdir í að minnsta kosti 2 ár
Deprecated eiginleikar: 6 mánaða fyrirvari áður en eiginleikar eru fjarlægðir
Nýjar útgáfur: Nýir eiginleikar bætast við sem nýir endapunktar
Breaking breytingar: Aðeins í nýjum major útgáfum (v2.0, v3.0, osfrv.)

Væntanlegir eiginleikar

Webhook stuðningur: Real-time tilkynningar um breytingar
GraphQL endapunktar: Sveigjanlegri gagnaleit
Bulk aðgerðir: Fjöldainnflutningur og uppfærsla
Aukin síun: Flóknari OData leitarskilyrði
Aukin öryggi: Certificate-based auðkenning

Helstu kostir

Öflug samþætting: Beinn aðgangur að öllum kerfishlutum
Sveitarstjórnarmiðað: Sérstaklega hannað fyrir íslensk sveitarfélög
Öryggi í fyrirrúmi: Nútíma auðkenningar- og öryggisstaðlar
Þróunarvinir: Auðveld samþætting með þekktum verkfærum
Skalanlegt: Styður bæði lítil og stór sveitarfélög
Vel skjalað: Ítarleg skjölun og dæmi
Traust stuðningur: Professionell þjónusta og uppfærslur
Framtíðaröryggi: Stöðug þróun og viðhald

API kerfishlutinn veitir örugg og öflug tól fyrir samþættingu ytri kerfa við Wise Sveitarstjórnarkerfið, sem gerir sveitarfélögum kleift að byggja upp heildstæðar og sjálfvirkar lausnir fyrir þjónustu við íbúa.