Rydym wedi cyfieithu’r wefan hon yn ofalus gan ddefnyddio adnoddau terminoleg swyddogol, gan gynnwys TermCymru. Efallai na fydd pob cyfieithiad yn berffaith. Os gwelwch gamgymeriad, anfonwch e-bost at welsh@qwtn.co.uk. Byddem yn ddiolchgar iawn.

Pob enghraifft o’r defnydd

Enghraifft o’r defnydd, nid stori cwsmer

Sut y byddai tîm datblygu mewnol yn cysylltu QWTN â’i system ERP ei hun

Cwmni gwastraff gyda’i ERP ei hun a thîm datblygu bach. Maen nhw eisiau anfon swyddi i mewn, cael nodiadau wedi’u llofnodi a thaliadau’n ôl, a ffigurau ESG yn eu dangosfwrdd.

  • 2datblygwr
  • 1ERP i’w gysylltu
  • 120o geisiadau’r funud, fesul allwedd
  • £69Fleet, y mis

Busnes dychmygol. Tybiaethau ar gyfer yr enghraifft hon yw’r ffigurau am y tîm, y fflyd a’r nifer, nid canlyniadau gan gwsmer.

Pwy ydyn nhw a beth sy’n mynd o chwith

Cwmni gwastraff gydag ERP mewnol sy’n dal cwsmeriaid, swyddi a’r cyfriflyfr cyffredinol. Mae tîm datblygu bach eisiau i’r ERP aros yn brif system gofnodion ar gyfer arian a chwsmeriaid, ac i QWTN drin y nodiadau trosglwyddo, y llofnodion ac ochr y gyrwyr.

Caiff pob swydd ei theipio ddwywaith, unwaith yn yr ERP ac unwaith ar nodyn. Mae nodiadau wedi’u llofnodi a thaliadau’n cael eu hymlid dros y ffôn a’u teipio’n ôl i mewn.

Mae’r tîm cynaliadwyedd yn gofyn am ffigurau ailgylchu a charbon bob chwarter, ac mae rhywun yn allforio ac yn cyfuno ffeiliau i’w cynhyrchu.

Busnes
Casglu gwastraff gydag ERP mewnol
Tîm
Dau ddatblygwr ac arweinydd gweithrediadau
Nod
Dim ail-deipio rhwng yr ERP a QWTN
Technoleg
Node a warws data, fel enghraifft
Man cychwyn
Ffeiliau CSV yn cael eu symud â llaw bob nos

Sut mae’r integreiddio’n rhedeg

  1. Swydd wedi’i harchebuDrafftio’r nodyn o’r ERPMae’r ERP yn creu nodyn drafft gyda disgrifiad o’r gwastraff, cod EWC, cleient a phwysau. Id y swydd yw’r allwedd idempotency, felly ni fydd ailgynnig ar ôl terfyn amser byth yn creu ail nodyn.
  2. Cyn casgluGofyn am lofnodMae’r ERP yn gofyn i’r cynhyrchydd lofnodi drwy ddolen mewn e-bost. Mae’r alwad hon yn defnyddio API yr ap gydag allwedd mynediad llawn.
  3. Wedi’i lofnodiMae’r ERP yn cael gwybodMae QWTN yn anfon digwyddiad note.signed wedi’i lofnodi ac mae’r ERP yn marcio bod y swydd wedi’i dogfennu. Mae digwyddiad collection.completed yn dilyn pan fydd y gyrrwr yn gorffen.
  4. Wedi’i thaluMae taliadau’n dod yn ôlMae QWTN yn codi anfonebau o rediadau bilio. Pan gaiff un ei thalu, drwy ddolen dalu neu â llaw, mae digwyddiad invoice.paid yn gadael i’r ERP ei bostio i’r cyfriflyfr.
  5. Bob chwarterTynnu’r ffigurau ESGMae’r dangosfwrdd yn gofyn am y gyfradd ailgylchu, dargyfeirio o safleoedd tirlenwi a charbon amcangyfrifedig ar gyfer cyfnod, ar gyfer pob cwsmer neu un.
Llif enghreifftiol. Mae digwyddiadau bachau gwe wedi’u llofnodi, ac mae’r ERP yn ateb gyda 2xx i gadarnhau.

Beth maen nhw’n ei ddefnyddio

  • Pwyntiau terfyn REST wedi’u teipio

    Nodiadau, cleientiaid, safleoedd cleientiaid, safleoedd derbyn, casgliadau, cynwysyddion a thocynnau pont bwyso, gyda chwmpasau darllen ac ysgrifennu. Mae creu mewn swmp yn derbyn hyd at 100 o gofnodion ym mhob galwad.

    Pwyntiau terfyn (Saesneg)

  • Bachau gwe wedi’u llofnodi

    Wyth math o ddigwyddiad, wedi’u llofnodi ag HMAC, yn cael eu hailgynnig gydag oedi cynyddol a gellir eu hailchwarae o’r log anfon.

    Bachau gwe (Saesneg)

  • Allweddi idempotency

    Anfonwch allwedd ar bob POST a PATCH. Mae ailgynnig o fewn 24 awr yn dychwelyd yr ymateb gwreiddiol.

    Idempotency (Saesneg)

  • API yr ap

    Gellir cyrraedd popeth y gall yr ap gwe ei wneud o dan /api/v1/app gydag allwedd mynediad llawn, yn rhedeg fel y person a greodd yr allwedd.

    API yr ap (Saesneg)

  • Digwyddiadau archwilio

    Darllenwch yr hanes newidiadau drwy /api/v1/audit-events gydag allwedd audit:read, wedi’i hidlo yn ôl cofnod, cleient, gweithred neu ffynhonnell.

    Pwynt terfyn y trywydd archwilio (Saesneg)

  • OpenAPI 3.1

    Manyleb wedi’i chynhyrchu i’w mewnforio i Postman, Insomnia neu gynhyrchydd cod.

    JSON OpenAPI (Saesneg)

Y galwadau mewn cod

Pwyntiau terfyn go iawn o’r dogfennau datblygwyr (Saesneg). Mae’r allweddi, yr ids a’r cyfeiriadau’n rhai enghreifftiol. Mae’r cod yn Saesneg.

Creu nodyn trosglwyddo o swydd wedi’i harchebu

Mae allwedd gyda’r cwmpas notes:write yn ddigon. Mae’r allwedd idempotency yn atal ailgynnig rhag creu ail nodyn.

const res = await fetch('https://qwtn.co.uk/api/v1/notes', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.QWTN_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'erp-job-' + job.id,
  },
  body: JSON.stringify({
    waste_description: 'Mixed construction and demolition waste',
    ewc_codes: ['17 09 04'],
    client_id: job.qwtnClientId,
    weight_kg: 1200,
    transfer_date: '2026-10-14',
  }),
})
const note = await res.json()
// the new draft note: note.id, note.reference, note.status === 'draft'

// Ask the producer to sign. This is an app API call and needs a full-access key.
await fetch('https://qwtn.co.uk/api/v1/app/notes/' + note.id + '/request-signature', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.QWTN_FULL_ACCESS_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    party: 'transferor',
    recipientEmail: 'site@client.co.uk',
    recipientName: 'Sam Lee',
  }),
})

Derbyn a gwirio bachyn gwe

Gwiriwch HMAC y stamp amser a’r corff crai, gwrthodwch unrhyw beth sy’n hŷn na phum munud, dad-ddyblygwch ar id y digwyddiad ac atebwch yn gyflym. Ychwanegwch y pwynt terfyn o dan Settings, Webhooks.

import crypto from 'node:crypto'
import express from 'express'

const app = express()

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 fresh = Math.abs(Date.now() / 1000 - t) < 300
  const valid = [...header.matchAll(/v1=([0-9a-f]{64})/g)].some(([, sig]) =>
    crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex')))
  if (!fresh || !valid) return res.status(400).end()

  const event = JSON.parse(req.body.toString())
  if (alreadyProcessed(event.id)) return res.sendStatus(204)

  switch (event.type) {
    case 'note.signed':          markJobDocumented(event.data.object); break
    case 'collection.completed': releaseForBilling(event.data.object); break
    case 'invoice.paid':         postToLedger(event.data.object); break
  }
  res.sendStatus(204)
})

Tynnu ffigurau ESG ar gyfer cyfnod

Mae’r adroddiad yn rhedeg fel y person a greodd yr allwedd, felly mae angen caniatâd ar y person hwnnw i weld adroddiadau. Ychwanegwch customer=CLIENT_ID ar gyfer un cwsmer, neu format=csv, pdf neu returns i gael ffeil.

const url = new URL('https://qwtn.co.uk/api/v1/app/reports/esg')
url.searchParams.set('from', '2026-07-01')
url.searchParams.set('to', '2026-09-30')

const r = await fetch(url, {
  headers: { Authorization: 'Bearer ' + process.env.QWTN_FULL_ACCESS_KEY },
})
const { summary } = await r.json()

// summary.totalTonnes, summary.recyclingRate, summary.landfillDiversion,
// summary.carbonKg (an estimate, with the method in the full report)

Copïo’r hanes newidiadau bob nos

Gall allwedd gyda’r cwmpas audit:read ddarllen y trywydd archwilio. Ychwanegwch source=api i weld dim ond newidiadau a wnaed drwy’r API, a thudalennwch gyda next_cursor.

curl "https://qwtn.co.uk/api/v1/audit-events?created_after=2026-10-14T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $QWTN_AUDIT_KEY"

Y cynllun sy’n addas

Fleet, oherwydd bod yr API a’r bachau gwe’n dechrau yno

Mae mynediad i’r API REST a bachau gwe yn nodweddion Fleet. Mae allweddi â chwmpas yn gadael i’r tîm roi’r lleiaf sydd ei angen i bob gwaith: notes:write ar gyfer yr alwad archebu, audit:read ar gyfer y copi i’r warws, ac un allwedd mynediad llawn wedi’i chadw mewn storfa gyfrinachau ar gyfer API yr ap.

Beth fyddai’n ei newid. Gallai tîm sydd angen dim ond nodiadau, llofnodion ac amserlennu, heb yr API na bachau gwe, ddefnyddio Carrier yn lle hynny. Mae treial 30 diwrnod ar gael ar gynlluniau taledig.

Cymharu pob cynllun
  • Fleet£69 y mis, neu £690 y flwyddyn
  • Diderfyno bobl ar y cynllun hwn

Dim TAW. Nid yw QWTN wedi’i gofrestru ar gyfer TAW, felly’r pris a welwch yw’r pris a dalwch.

Beth i’w wirio gyntaf

Y manylion am y cynllun a’r nodweddion sydd bwysicaf ar gyfer yr enghraifft hon.

  • Y terfyn yw 120 o geisiadau’r funud fesul allwedd. Os ewch drosto, cewch 429 gyda phennawd Retry-After, felly tudalennwch drwy restrau yn hytrach na nôl cofnodion fesul un.
  • Mae API yr ap yn dychwelyd JSON yr ap ei hun. Mae’n sefydlog yn ymarferol ond heb fersiynau fel y pwyntiau terfyn wedi’u teipio, felly defnyddiwch bwynt terfyn wedi’i deipio lle mae un yn bodoli.
  • Caiff bachau gwe eu hanfon o leiaf unwaith ac nid oes sicrwydd o’r drefn. Dad-ddyblygwch ar id y digwyddiad a nôl y cofnod os oes angen ei gyflwr diweddaraf arnoch.

Ble i fynd nesaf

Gwnewch eich galwad API gyntaf

Crëwch allwedd o dan Settings, API access, neu dechreuwch gyda chyfrif a’r demo.

Creu allwedd API Dogfennau datblygwyr (Saesneg)

Darluniau yw’r enghreifftiau o’r defnydd, nid straeon cwsmeriaid.