Julkinen asiakasdokumentaatio raportointi-, telemetria-, palvelupyyntö- ja export-rajapintoihin. Tämä sivu kertoo miten API otetaan käyttöön, miten dataa kysellään ja miten integraatiot kannattaa rakentaa tuotantoon.
https://api.sarkahq.com/api/external/v1X-API-Key headerissaKäytä tenant-avainta organisaation laajuisiin integraatioihin, BI-raportointiin, data lakeen ja muihin järjestelmiin, joiden kuuluu nähdä koko tenantin data.
Käytä asiakasavainta ulkoisille asiakkaille ja rajatuille portaaleille. Asiakasavain näkee vain rivit, joiden customerName vastaa avaimen asetusta.
export SARKA_BASE_URL="https://api.sarkahq.com/api/external/v1"
export SARKA_API_KEY="sk_sarka_..."
curl -sS "$SARKA_BASE_URL/me" \
-H "X-API-Key: $SARKA_API_KEY" | jq .Ensimmäinen tuotantotesti on aina GET /me suhteessa base URLiin, eli /api/external/v1/me. Se kertoo tenantin, avaimen nimen, customerName-scopen ja API-version.
curl -sS "$SARKA_BASE_URL/reporting/overview?from=2026-01-01&to=2026-12-31" \
-H "X-API-Key: $SARKA_API_KEY" | jq .curl -sS "$SARKA_BASE_URL/reporting/assets?q=kurottaja&assetType=Kurottaja&limit=100" \
-H "X-API-Key: $SARKA_API_KEY" | jq .curl -sS "$SARKA_BASE_URL/reporting/reports/00000000-0000-0000-0000-000000000000" \
-H "X-API-Key: $SARKA_API_KEY" | jq .curl -sS "$SARKA_BASE_URL/reporting/inspections?from=2026-05-01&to=2026-05-31&status=completed&outcome=rejected&assetId=00000000-0000-0000-0000-000000000000" \
-H "X-API-Key: $SARKA_API_KEY" | jq .curl -sS "$SARKA_BASE_URL/telemetry/utilization?from=2026-05-01&to=2026-05-31&bucket=day&groupBy=fleet" \
-H "X-API-Key: $SARKA_API_KEY" | jq .curl -sS "$SARKA_BASE_URL/telemetry/utilization?from=2026-05-16T00:00:00Z&to=2026-05-17T00:00:00Z&bucket=hour&groupBy=asset&limit=500" \
-H "X-API-Key: $SARKA_API_KEY" | jq .curl -sS "$SARKA_BASE_URL/telemetry/container-work?from=2026-05-01&to=2026-05-31&bucket=day&groupBy=asset&q=kurottaja" \
-H "X-API-Key: $SARKA_API_KEY" | jq .curl -sS "$SARKA_BASE_URL/telemetry/identifier-sessions?from=2026-05-16&to=2026-05-17&identifier=RFID1234" \
-H "X-API-Key: $SARKA_API_KEY" | jq .runningSeconds, stationaryRunningSeconds, utilizationPercent, hourmeterDelta ja distanceM kuvaavat koneen käyttöä valitulla tunti- tai päiväbucketilla.
adcin=on tarkoittaa, että spreader/lukitusmekanismi on lukittu tai kontti on mukana. adcin=off tarkoittaa avointa/tyhjää ajoa. API palauttaa loaded/empty-sekunnit, matkat ja syklit.
source-kenttä kertoo, palautettiinko vastaus esilasketusta tunti-/päivätason aggregaatista vai laskettiinko se kyselyn aikana.
from-aikaa.CSV/XLSX-viennit ovat paginoituja. Yksi vastaus palauttaa enintään 50 000 riviä. Jos X-Export-Truncated on true, hae seuraava sivu X-Next-Offset-headerin arvolla.
offset=0
while true; do
headers=$(mktemp)
curl -sS -D "$headers" \
"$SARKA_BASE_URL/telemetry/utilization/export.csv?from=2026-05-01&to=2026-05-31&bucket=day&groupBy=asset&offset=$offset" \
-H "X-API-Key: $SARKA_API_KEY" \
-o "utilization-$offset.csv"
truncated=$(grep -i '^X-Export-Truncated:' "$headers" | awk '{print tolower($2)}' | tr -d '\r')
next=$(grep -i '^X-Next-Offset:' "$headers" | awk '{print $2}' | tr -d '\r')
rm "$headers"
[ "$truncated" = "true" ] || break
offset="$next"
donecurl -sS -X POST "$SARKA_BASE_URL/service-requests" \
-H "X-API-Key: $SARKA_API_KEY" \
-H "Idempotency-Key: customer-portal-ticket-12345" \
-H "Content-Type: application/json" \
-d '{
"title": "WC-hana vuotaa",
"description": "Vuoto näkyy altaan alla.",
"category": "defect",
"priority": "high",
"location": "A-rappu, asunto 12, WC",
"customerName": "Kiinteistö Oy Esimerkki",
"reportedByName": "Matti Meikäläinen",
"reportedByEmail": "matti@example.com",
"externalRef": "customer-portal-12345"
}' | jq .curl -sS -X PATCH "$SARKA_BASE_URL/service-requests/00000000-0000-0000-0000-000000000000" \
-H "X-API-Key: $SARKA_API_KEY" \
-H "Idempotency-Key: customer-portal-ticket-12345-resolve" \
-H "Content-Type: application/json" \
-d '{
"status": "resolved",
"resolution": "Liitos kiristetty ja vuoto tarkistettu.",
"resolutionReviewed": true,
"comment": "Ratkaistu paikan päällä."
}' | jq .resolved ja closed vaativat ratkaisun ja resolutionReviewed: true. Käsiteltyä pyyntöä ei poisteta pysyvästi, vaan se perutaan endpointilla POST /service-requests/{id}/cancel. Käytä Idempotency-Key-headeria palvelupyyntöjen luonnissa ja päivityksessä kaikissa asiakasportaalin ja ERP:n retry-kutsuissa.Webhookit ovat push-kanava asiakkaan järjestelmiin. API sopii kyselyyn ja raportointiin; webhook sopii tapahtumailmoituksiin. Aseta webhook asiakkaan asetuksissa Webhookit-näkymässä.
| Tapahtuma | Käyttö |
|---|---|
inspection.completed, report.created | Raportointi- ja dokumenttivirrat. |
service_request.created, service_request.updated, service_request.cancelled | Asiakasportaali-, ERP- ja ticketing-integraatiot. |
telemetry.geofence_alert.opened, acknowledged, resolved | Aluehälytykset ja operatiivinen valvonta. |
{
"event": "service_request.created",
"entityType": "service_request",
"entityId": "11111111-1111-1111-1111-111111111111",
"tenantId": "00000000-0000-0000-0000-000000000000",
"createdAt": "2026-05-17T10:15:00Z",
"data": {
"id": "11111111-1111-1111-1111-111111111111",
"title": "WC-hana vuotaa",
"status": "new",
"priority": "high",
"customerName": "Kiinteistö Oy Esimerkki"
}
}| Header | Merkitys |
|---|---|
X-Sarka-Webhook-Id | Yksittäisen toimitusyrityksen tunniste. Käytä deduplikointiin. |
X-Sarka-Webhook-Attempt | Yrityksen numero alkaen arvosta 1. |
X-Sarka-Webhook-Timestamp | Toimitusyrityksen UTC-aikaleima RFC3339-muodossa. |
X-Sarka-Signature | sha256=<hex>, HMAC-SHA256 raakaa JSON-bodya vasten, kun webhook secret on asetettu. |
Retry-policy on rakenteisena endpointissa GET /webhooks/events: retryStrategy.maxAttempts ja retryStrategy.backoffSeconds.
400 invalid request, 401 puuttuva/virheellinen avain, 403 scope ei salli, 404 ei löydy, 409 tilasiirtymä ei sallittu, 429 rate limit, 500 palvelinvirhe.
JSON-listat käyttävät limit/offset. Oletus 100, maksimi 500. Exportit käyttävät omaa 50 000 rivin rajaa ja continuation-headereita.
Älä upota avainta selaimen julkiseen JavaScriptiin. Kierrätä avaimet, lokita request-id/timestamp omassa järjestelmässä ja siedä uusia kenttiä responseissa.
/me/api/external/v1/me. Tarkista API-avain, tenant ja customerName-scope./reporting/overview, /reporting/assets, /reporting/assets/{id}, /reporting/inspections, /reporting/inspections/{id}, /reporting/reports, /reporting/reports/{id}/reporting/asset-types, /reporting/templates/reporting/export.csv, /reporting/export.xlsx/telemetry/capabilities, /telemetry/devices, /telemetry/assets/{assetId}/state, /telemetry/assets/{assetId}/positions/telemetry/usage-sessions, /telemetry/identifier-sessions/telemetry/utilization, /telemetry/container-work, /telemetry/service-request-metrics/telemetry/*/export.csv, /telemetry/*/export.xlsx/telemetry/data-quality, /telemetry/geofences, /telemetry/operators, /telemetry/geofence-alerts/service-requests/service-requests, /service-requests/{id}/service-requests/{id}, POST /service-requests/{id}/cancel/service-requests/{id}/files/webhooks/events, /webhooks/subscriptions, /webhooks/deliveriesTäydellinen endpoint-, parametri- ja skeemalista: Swagger / OpenAPI Reference.