Cysylltwch QWTN â gweddill eich busnes

Dilysu a chwmpasau

Mae allweddi’n edrych fel qwtn_live_XXXXXXXX_…. Dangosir y rhan gyntaf (y rhagddodiad) yn yr ap fel y gallwch wahaniaethu rhwng allweddi. Dim ond hash SHA-256 o’r gweddill rydyn ni’n ei storio. Mae allweddi’n perthyn i’r tîm, gallant ddod i ben, a gellir eu dirymu ar unwaith. Mae ceisiadau ag allwedd sydd ar goll, wedi’i dirymu neu wedi dod i ben yn cael 401, ac mae allwedd heb y cwmpas cywir yn cael 403 insufficient_scope.

Mae cwmpas :write yn cynnwys :read ar gyfer yr un cofnodion. Mae GET /api/v1/me yn dweud wrthych pa dîm a pha gwmpasau sydd gan allwedd.

Ceisiadau a gwallau

Anfonwch gyrff JSON gyda Content-Type: application/json. Caiff meysydd anhysbys eu gwrthod, fel na fydd camgymeriadau teipio’n mynd heb eu sylwi. Mae dyddiadau ar y ffurf YYYY-MM-DD, stampiau amser yn ISO 8601 UTC, ac arian mewn punnoedd fel rhifau. Mae gan bob ymateb X-Request-Id. Dyfynnwch ef os byddwch yn cysylltu â ni.

Mae gan wallau’r un ffurf bob amser. Defnyddiwch code i ganghennu, nid y neges:

HTTP/1.1 422 Unprocessable Entity
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "The request body has invalid fields",
    "request_id": "req_8b0153f6deef40de9fb0",
    "details": [{ "field": "ewc_codes", "message": "Required" }]
  }
}

Codau: unauthenticated, invalid_api_key, insufficient_scope, not_found, validation_failed, invalid_cursor, rate_limited, idempotency_conflict, idempotency_in_progress, internal_error.

Tudalennu

Mae rhestri’n dychwelyd hyd at limit o eitemau (rhwng 1 a 100, 25 yn ddiofyn), y diweddaraf yn gyntaf. Pan fydd has_more yn true, pasiwch next_cursor yn ôl fel cursor. Mae cyrchwyr yn sefydlog wrth i gofnodion newydd gyrraedd, felly fyddwch chi byth yn hepgor nac yn ailadrodd rhes. I gysoni nodiadau fesul cam, defnyddiwch updated_after.

let cursor = null
do {
  const url = new URL('https://qwtn.co.uk/api/v1/collections')
  url.searchParams.set('status', 'completed')
  if (cursor) url.searchParams.set('cursor', cursor)
  const page = await fetch(url, { headers: { Authorization: `Bearer ${process.env.QWTN_API_KEY}` } }).then((r) => r.json())
  for (const job of page.data) handle(job)
  cursor = page.next_cursor
} while (cursor)

Idempoteniaeth

Anfonwch bennyn Idempotency-Key (unrhyw linyn unigryw, e.e. UUID) ar bob POST a PATCH. Os bydd y rhwydwaith yn methu a’ch bod yn ailgeisio gyda’r un allwedd o fewn 24 awr, cewch yr ymateb gwreiddiol yn ôl gyda Idempotent-Replayed: true yn hytrach na nodyn neu docyn dyblyg. Mae ailddefnyddio allwedd gyda chorff gwahanol yn dychwelyd 422 idempotency_conflict.

curl -X POST https://qwtn.co.uk/api/v1/notes \
  -H "Authorization: Bearer $QWTN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c0f2a1e-job-8812" \
  -d '{
    "waste_description": "Mixed construction and demolition waste",
    "ewc_codes": ["17 09 04"],
    "client_id": "e913a8a6-ffe2-47c4-9686-f25938ae9154",
    "weight_kg": 1200,
    "transfer_date": "2026-10-14"
  }'

Creu swmp

Mae pob pwynt terfyn creu POST hefyd yn derbyn { "data": [ … ] } gyda hyd at 100 o gofnodion. Caiff pob eitem ei dilysu a’i chreu ar wahân, felly dydy un rhes wael ddim yn atal y gweddill. Yr ymateb yw 200 gyda chanlyniad ar gyfer pob eitem, yn eu trefn.

curl -X POST https://qwtn.co.uk/api/v1/client-locations \
  -H "Authorization: Bearer qwtn_live_…" -H "Content-Type: application/json" \
  -d '{ "data": [
        { "client_id": "…", "label": "Unit 4, Riverside", "postcode": "BS1 4DJ" },
        { "client_id": "…", "label": "Head office", "postcode": "M1 1AE", "is_default": true }
      ] }'

{ "object": "list", "created": 2, "failed": 0,
  "data": [ { "index": 0, "status": 201, "data": { "id": "…", "object": "client_location", … } },
            { "index": 1, "status": 201, "data": { … } } ] }

Anfonwch Idempotency-Key gyda cheisiadau swmp fel na fydd ailgeisio ar ôl terfyn amser byth yn creu dyblygiadau.

Cyfyngiadau cyfradd

120 cais y funud ar gyfer pob allwedd. Dros y terfyn, cewch 429 rate_limited gyda phennyn Retry-After mewn eiliadau. Arafwch ac ailgeisiwch. Dylai swyddi swmp dudalennu drwy restrau yn hytrach na nôl cofnodion fesul un.

Pwyntiau terfyn

URL sylfaenol https://qwtn.co.uk. Mae’r manylion llawn ar lefel maes yn y ddogfen OpenAPI 3.1 (mewnforiwch hi i Postman, Insomnia neu gynhyrchydd cod).

Popeth arall: yr API ap

Gallwch wneud popeth y gallwch ei wneud yn ap QWTN drwy’r API. Mae /api/v1/app/{path} yn cyrraedd pob pwynt terfyn yn yr ap (197 heddiw, o gyhoeddi a llofnodi nodiadau trosglwyddo i wiriadau fflyd, RAMS, Tracio Gwastraff yn Ddigidol, anfonebu a gosodiadau tîm) gyda’r un dilysu a’r un sgil-effeithiau â’r ap.

• Mae angen allwedd mynediad llawn (y cwmpas *). Mae ceisiadau’n rhedeg fel y person a greodd yr allwedd, gyda’i rôl a’i ganiatâd yn union, ac fe’u cofnodir yn y log archwilio yn ei enw ef neu hi.
• Yr un pennyn dilysu, yr un terfyn cyfradd, yr un cymorth Idempotency-Key a’r un amlen gwallau â gweddill yr API. Mae [id] mewn llwybr yn unrhyw ID cofnod.
• Mae cyrff yr ymatebion yn JSON yr ap ei hun. Maen nhw’n sefydlog yn ymarferol, ond dydyn nhw ddim wedi’u fersiynu fel y pwyntiau terfyn teipiedig uchod, felly dewiswch bwynt terfyn teipiedig lle mae un ar gael.
• Mae GET /api/v1/app yn dychwelyd y rhestr fyw o lwybrau a dulliau.
• Gallwch ddarllen a gweithredu ar y bwrdd byw drwy’r API. Mae GET /api/v1/app/ops/board?date=YYYY-MM-DD yn dychwelyd swyddi a gyrwyr diwrnod. Ychwanegwch &since= gydag amser ISO i gael dim ond yr hyn sydd wedi newid, a &derive=1 i gael cyflwr ac amseriad pob swydd. Mae POST /api/v1/app/ops/board/assign, /problem a /message yn gweithredu â chaniatâd perchennog yr allwedd, felly mae’r un gwiriadau cydymffurfio a’r un hysbysiadau i yrwyr yn berthnasol ag yn yr ap.
• Mae anfon swmp yn rhedeg fel swyddi cefndir. Mae POST /api/v1/app/invoices/bulk-reminders a POST /api/v1/app/notes/bulk-signature-requests yn ateb â 202 a ID swydd. Holwch GET /api/v1/app/jobs/{id} am y statws a’r cynnydd, ac anfonwch "dryRun": true i gyfrif yr hyn a fyddai’n cael ei anfon heb ei anfon. Galwadau POST ar yr un swydd yw canslo ac ailgeisio, ac mae gan swydd ffeil sydd wedi gorffen lwybr /download sy’n ailgyfeirio at ddolen fyrhoedlog.

# Add a collection site to a client (geocoded from the postcode, like in the app)
curl -X POST https://qwtn.co.uk/api/v1/app/clients/CLIENT_ID/locations \
  -H "Authorization: Bearer qwtn_live_…" -H "Content-Type: application/json" \
  -d '{ "label": "Unit 4, Riverside", "postcode": "BS1 4DJ", "contact_name": "Sam Lee" }'

# Send a draft note for e-signature
curl -X POST https://qwtn.co.uk/api/v1/app/notes/NOTE_ID/request-signature \
  -H "Authorization: Bearer qwtn_live_…" -H "Content-Type: application/json" -d '{ "party": "transferor", "recipientEmail": "site@client.co.uk", "recipientName": "Sam Lee" }'

Bachau gwe

Ychwanegwch bwyntiau terfyn HTTPS yn Settings → Webhooks a dewiswch y digwyddiadau i’w derbyn. Mae pob digwyddiad yn POST JSON lle mae data.object yn gofnod yn union fel y mae’r API REST yn ei ddychwelyd.

POST /your/endpoint
QWTN-Signature: t=1760262000,v1=5f2b…c9
QWTN-Event-Id: evt_6a1f…
QWTN-Event-Type: invoice.paid

{ "id": "evt_6a1f…", "object": "event", "type": "invoice.paid", "api_version": "2026-10-01",
  "created_at": "2026-10-12T09:40:00Z", "data": { "object": { "id": "…", "object": "invoice", "status": "paid", … } } }

Gwirio’r llofnod

Cyfrifwch HMAC-SHA256 o `${t}.${rawBody}` gyda chyfrinach eich pwynt terfyn a’i gymharu, mewn amser cyson, ag unrhyw werth v1. Gwrthodwch stampiau amser sy’n hŷn na phum munud. Yn ystod newid cyfrinach, mae’r pennyn yn cynnwys dau werth v1 am 24 awr.

import crypto from 'node:crypto'

app.post('/webhooks/qwtn', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('QWTN-Signature') ?? ''
  const t = Number(/t=(\d+)/.exec(header)?.[1])
  const expected = crypto.createHmac('sha256', process.env.QWTN_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`).digest('hex')
  const ok = Math.abs(Date.now() / 1000 - t) < 300 &&
    [...header.matchAll(/v1=([0-9a-f]{64})/g)].some(([, sig]) =>
      crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex')))
  if (!ok) return res.status(400).end()
  const event = JSON.parse(req.body)
  // dedupe on event.id, then queue your work and reply fast
  res.sendStatus(204)
})

Anfon ac ailgeisio

• Atebwch ag unrhyw 2xx o fewn 10 eiliad. Gwnewch waith araf ar ôl ateb.
• Caiff unrhyw ymateb arall ei ailgeisio ar ôl 1m, 5m, 30m, 2h, 6h, 12h, 24h, 24h (gyda jitter), yna ei farcio fel un a fethodd. Mae ailgeisio’n digwydd o leiaf unwaith: anwybyddwch ddyblygiadau yn ôl id.
• Mae ateb 410 Gone yn analluogi’r pwynt terfyn. Mae 15 digwyddiad yn olynol sy’n defnyddio eu holl ailgeisiadau yn ei analluogi hefyd.
• Mae’r log danfon yn Settings yn dangos pob ymgais, llwyth ac ymateb, ac yn gadael i chi ailchwarae unrhyw ddigwyddiad neu anfon ping prawf.
• Does dim trefn warantedig. Defnyddiwch created_at a nôl y cofnod o’r API os oes angen y cyflwr diweddaraf arnoch.

Integreiddiadau adeiledig

• Stripe a GoCardless: dolenni talu nawr ar anfonebau sy’n setlo i’ch cyfrif eich hun. Caiff anfonebau eu marcio’n rhai a dalwyd yn awtomatig.
• Mewnforio CSV ac allforio llawn: cleientiaid, safleoedd cleientiaid, cynwysyddion a cherbydau i mewn, a phob math o gofnod allan fel ZIP o ffeiliau CSV.

Fersiynau a chymorth

Dyma fersiwn 2026-10-01 yr API (a anfonir fel pennyn ymateb QWTN-Version). Rydyn ni’n ychwanegu meysydd a phwyntiau terfyn heb rybudd, felly anwybyddwch feysydd nad ydych yn eu hadnabod. Mae newidiadau sy’n torri pethau yn cael fersiwn newydd ac o leiaf chwe mis o rybudd drwy e-bost i berchnogion cyfrifon. Cwestiynau: support@qwtn.co.uk.