Treadx API

Koppla verkstadens egna system till Treadx: ekonomisystem, CRM, en webbplats eller en egen app. API:t ger åtkomst till samma kunder, fordon och hjuluppsättningar som verkstaden ser i Treadx, och bara till dem.

Bas-URL

https://api.treadx.se/v1

Format

JSON över HTTPS

Autentisering

API-nyckel från verkstaden

Referens

Alla endpoints · openapi.json

Första anropet

1. En administratör i verkstaden skapar en nyckel i Treadx under Inställningar → Företag → API-nycklar och väljer bara de behörigheter integrationen behöver.
2. Nyckeln visas en gång. Spara den i integrationens hemlighetshantering, aldrig i källkod, i en webbläsare eller i en mobilapp.
3. Hämta de första kunderna:

curl "https://api.treadx.se/v1/customers?limit=10" \
  -H "Authorization: Bearer $TREADX_API_KEY"

const response = await fetch("https://api.treadx.se/v1/customers?limit=10", {
  headers: { Authorization: `Bearer ${process.env.TREADX_API_KEY}` },
});
if (!response.ok) throw new Error(`Treadx svarade ${response.status}`);
const data = await response.json();

import os
import requests

response = requests.get(
    "https://api.treadx.se/v1/customers?limit=10",
    headers={"Authorization": f"Bearer {os.environ['TREADX_API_KEY']}"},
)
response.raise_for_status()
data = response.json()

using System.Net.Http.Headers;

using var http = new HttpClient { BaseAddress = new Uri("https://api.treadx.se") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("TREADX_API_KEY"));

var response = await http.GetAsync("/v1/customers?limit=10");
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

{
  "data": [
    {
      "id": "3f2c1a9e-7b4d-4e0a-9c55-1f0e8a6d2b71",
      "externalId": null,
      "firstName": "Anna",
      "lastName": "Svensson",
      "email": "anna.svensson@example.se",
      "phone": "070-123 45 67",
      "company": null,
      "address": "Storgatan 1",
      "address2": null,
      "postalCode": "791 30",
      "city": "Falun",
      "country": null,
      "isActive": true,
      "createdAt": "2026-10-01T08:12:44Z",
      "updatedAt": "2026-10-03T14:02:10Z"
    }
  ],
  "nextCursor": "eyJ1IjoiMjAyNi0xMC0wM1QxNDowMjoxMFoifQ"
}

Autentisering

Skicka nyckeln i Authorization-headern:

Authorization: Bearer trx_live_…

X-API-Key: trx_live_… fungerar också, för verktyg som inte kan sätta Authorization.

• En nyckel hör till en verkstad. Den ger aldrig åtkomst till en annan verkstads data, och ingen parameter byter verkstad.
• Nycklar börjar på trx_live_ och går mot verkstadens riktiga data.
• En nyckel kan ha ett utgångsdatum.
• API:t tar inte emot anrop från webbläsare (ingen CORS). Anropa det från en server.
• Bara API-nycklar fungerar. En användares inloggning i Treadx ger 401.

Om en nyckel läcker

Återkalla den i Treadx. Den slutar fungera direkt. Skapa en ny och byt i integrationen.

Byta nyckel

1. Skapa en ny nyckel med samma behörigheter.
2. Byt till den nya i integrationen.
3. Kontrollera under Senast använd att den gamla inte längre anropas.
4. Återkalla den gamla.

Behörigheter

Varje nyckel har en lista med behörigheter. Ett anrop som kräver en behörighet nyckeln saknar får 403. Vilken behörighet varje endpoint kräver står i referensen.

Nya behörigheter tillkommer när API:t växer. En befintlig nyckel får dem aldrig automatiskt.

Resurser

Fält, filter och exempel för varje endpoint finns i referensen.

Kunder

email är frivillig, alla kunder har inte e-post. Finns den är den unik inom verkstaden. En kund utan e-post kan inte logga in i kundportalen.

Fordon

Registreringsnummer sparas med versaler och utan blanksteg, så abc 123 blir ABC123. Filtret registrationNumber fungerar på samma sätt. Samma registreringsnummer kan finnas på flera fordon.

När verkstaden anonymiserar en kund får kundens fordon registreringsnumret ANON-…, och vin och externalId töms. Matcha därför alltid på id.

Hjuluppsättningar och hjulskifte

En hjuluppsättning är fyra hjul med däck. Den ligger antingen i lager (InStorage) eller sitter på bilen (Mounted). Lagerplatser och paket anges alltid med id. Hämta dem från /storage-locations och /packages.

Ny däckhotellkund

1. Skapa kunden med POST /customers.
2. Skapa fordonet med POST /vehicles.
3. Registrera uppsättningen som läggs i lager med POST /wheelsets och "status": "InStorage".

Hjulen bilen kör på behöver inte registreras i förväg. De registreras vid första hjulskiftet.

Hjulskifte

POST /vehicles/{id}/tyre-swap sätter en lagrad uppsättning på bilen och lägger den som tas av i lager, på platsen som frigörs. Ny data för hjulen, till exempel slitage, skickas per position i samma anrop.

{
  "mountWheelsetId": "9c3f7a12-5e8b-4d21-a6f0-3b9e1c4d7a85",
  "removed": {
    "wheels": [
      { "position": "FrontLeft", "treadDepthMm": 3.1 },
      { "position": "FrontRight", "treadDepthMm": 3.4 }
    ]
  }
}

Vid fordonets första skifte i Treadx finns uppsättningen som tas av inte registrerad. Skicka då removed.season och alla fyra hjul, så skapas den i samma anrop.

Allt sker i en transaktion. Ett skifte som skickas igen får 409, eftersom uppsättningen redan är monterad. Ett omförsök efter en timeout byter alltså aldrig tillbaka hjulen.

Paginering

Listor pagineras med en markör.

Svaret innehåller nextCursor. Skicka den som cursor för nästa sida. När nextCursor är null finns inget mer. Markören ska skickas oförändrad. Tolka eller bygg den inte själv.

Synkronisera ändringar

Listorna för kunder, fordon och hjuluppsättningar tar updatedSince. Då kommer bara det som skapats eller ändrats från och med den tiden, äldst först. Ange tiden med tidszon, till exempel 2026-10-03T00:00:00Z eller 2026-10-03T02:00:00+02:00.

curl "https://api.treadx.se/v1/customers?updatedSince=2026-10-03T00:00:00Z" \
  -H "Authorization: Bearer $TREADX_API_KEY"

const response = await fetch("https://api.treadx.se/v1/customers?updatedSince=2026-10-03T00:00:00Z", {
  headers: { Authorization: `Bearer ${process.env.TREADX_API_KEY}` },
});
if (!response.ok) throw new Error(`Treadx svarade ${response.status}`);
const data = await response.json();

import os
import requests

response = requests.get(
    "https://api.treadx.se/v1/customers?updatedSince=2026-10-03T00:00:00Z",
    headers={"Authorization": f"Bearer {os.environ['TREADX_API_KEY']}"},
)
response.raise_for_status()
data = response.json()

using System.Net.Http.Headers;

using var http = new HttpClient { BaseAddress = new Uri("https://api.treadx.se") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("TREADX_API_KEY"));

var response = await http.GetAsync("/v1/customers?updatedSince=2026-10-03T00:00:00Z");
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

1. Första gången: hämta allt, sida för sida.
2. Spara det största updatedAt du har sett.
3. Nästa gång: fråga med updatedSince satt till det sparade värdet. Den senaste posten kan komma igen. Hantera den som en uppdatering, inte som en dubblett.

Borttagna och anonymiserade kunder

En kund som tas bort i Treadx får "isActive": false och kommer med i synken. Efter 30 dagar anonymiseras kunden: namn, kontaktuppgifter och fritext töms, men posten finns kvar. Även det kommer med i synken som en ändring.

Skriv över din kopia. När en kund anonymiseras i Treadx ska den inte finnas kvar med namn och kontaktuppgifter i systemet du synkar till.

Ditt eget id

Kunder, fordon och hjuluppsättningar har fältet externalId. Sätt det till ditt eget id, till exempel kundnumret i ekonomisystemet, högst 100 tecken. Sök på det med ?externalId=…, så behöver integrationen ingen egen uppslagstabell. Ett externalId är unikt inom verkstaden och ger 409 om det redan används. Treadx ändrar det aldrig. Kundens externalId finns kvar när kunden anonymiseras, så att du hittar posten du ska skriva över. Fordonets töms.

Skapa och ändra

• POST skapar. Svaret är 201 med posten och en Location-header.
• PATCH ändrar enligt JSON Merge Patch. Skicka bara fälten som ska ändras. Ett fält satt till null töms. Obligatoriska fält kan inte tömmas.
• Fält som inte finns eller inte går att ändra, som id eller createdAt, ger 400. De ignoreras aldrig.

{ "phone": "070-765 43 21", "company": null }

Fel

Fel returneras som Problem Details:

{
  "type": "https://treadx.se/problems/validation",
  "title": "Ogiltiga uppgifter",
  "status": 400,
  "errors": {
    "wheels[2].treadDepthMm": ["treadDepthMm must be a number between 0 and 30, or null."]
  }
}

Bygg felhanteringen på type, inte på title. Texten kan ändras. Nycklarna i errors är fältnamnen i anropet.

type ovan står efter https://treadx.se/problems/.

Gränser

En nyckel får göra 120 anrop per minut. Varje svar talar om hur många som återstår:

RateLimit-Limit: 120
RateLimit-Remaining: 87
RateLimit-Reset: 23

RateLimit-Reset är antal sekunder tills gränsen nollställs. Överskrids gränsen svarar API:t 429 med Retry-After. En integration som synkar med updatedSince kommer sällan i närheten.

Format

• Tider är ISO 8601 i UTC, till exempel 2026-10-03T14:02:10Z.
• Id:n är UUID.
• Uppräkningar, som status och season, är strängar. Nya värden kan tillkomma. Behandla ett okänt värde som "annat", inte som ett fel.
• Nya fält kan tillkomma i svaren. Ignorera fält du inte känner igen.

Versioner

Versionen står i adressen: /v1. Inom en version tillkommer bara sådant som inte bryter en integration som följer reglerna under Format: nya endpoints, nya fält och nya värden.

Ändringar som kan bryta en integration kommer i en ny version.

Personuppgifter

Data från API:t innehåller personuppgifter om verkstadens kunder. Verkstaden är personuppgiftsansvarig och bestämmer vilka system som får nycklar. Den som bygger en integration hanterar uppgifterna enligt verkstadens instruktioner och GDPR: hämta bara det som behövs och spara det inte längre än nödvändigt.

Verkstaden ser i Treadx när varje nyckel senast användes och hur många anrop den gjort.

Planerat

Finns inte än:

• Arbetsordrar och bokningar
• Testnycklar (trx_test_) mot en testmiljö
• Idempotency-Key för säkra omförsök av POST
• ETag och If-Match mot samtidiga ändringar
• Webhooks

Support

Frågor om API:t: support@treadx.se. Ange nyckelns början (de första tecknen, aldrig hela nyckeln) och när anropet gjordes.