v1.4.3 — validation record (no content change)

Nothing to upgrade for. references/, scripts/, SKILL.md and AGENTS.md
are byte-identical to
v1.4.2 — verified
by diffing the exported tree. This tag exists so a validation run is citable; if
you are on 1.4.2 you already have this content.

What was recorded

• Full suite: 25/25 against the installed 1.4.2. The first run since
  evaluation/ stopped being installed in 1.4.2, which confirmed the point of
  that change: no agent cited the suite, and the one that had previously found
  and quoted its own expected answer reached the same refusal from the references
  alone. The 1.4.2 updatedAfter fix surfaced in two answers in the words the
  fix added.
• Two run-hygiene findings, neither affecting shipped content:
  • The repo's git history still serves claims that were later retracted. One
    agent rebuilt part of an answer from a superseded commit message and
    presented a mechanism the current docs explicitly contradict. Its conclusion
    was right, but this cannot be fixed by excluding a path — history is
    immutable and agents read it.
  • An eval agent wrote a 316-line file into scripts/, which is part of
    the exported tree; an unnoticed commit would have shipped unreviewed code.
    Untracked and removed.

The method note in evaluation/scenarios.md now says to install via
git archive rather than cp -r, to check git status after a run, and to
distrust any answer whose sources include commit messages.

Full detail in CHANGELOG.md.

v1.4.2 — eval coverage for the v2 corrections

A validation release, not a content release: the 1.4.1 corrections now have eval
coverage, and adding it turned up one place 1.4.1 had missed.

Fixed

• GET /v2/sandbox: the updatedAfter / updatedBefore rows had no timezone
  warning. 1.4.1 said the Europe/Rome caveat was called out "wherever the
  filter appears" — it was in v2/overview.md only, while the query-param table
  you actually read while calling the endpoint still described them as plain
  "ISO 8601 datetime filter". Both rows now carry the warning, what to do about
  it (convert the cursor, or overlap the window and de-duplicate), and a pointer
  that the shipments resource has the same filter.

  ⚠️ If you poll incrementally with a UTC cursor, this is still the failure that
  costs you data silently — see the 1.4.1 notes.

Added

• Six eval scenarios (#20–25), one per correction shipped in 1.4.1:
  updatedAfter's timezone, the mixed timestamp formats, the sandbox casing
  break, the v2 rate limit, second-tier resources being published rather than in
  flight, and the published spec's info.version proving nothing about the
  contracts inside it. Three are negative controls on a wrong premise, which is
  the shape these failures take in practice. Full suite: 25/25.

  The previous 19 scenarios covered none of what 1.4.1 corrected — which is why
  that drift was found in a live integration rather than by the suite.

Changed

• evaluation/ is no longer installed with the skill. It is export-ignore
  in .gitattributes, so the install step (now git archive, see the README)
  leaves it out. It listed the expected answer for every validation prompt right
  beside the content it validates, and a run caught an agent reading it while
  answering one of those prompts. The suite stays in the repo — it is a
  maintainer tool, not part of the knowledge pack.

Full detail in CHANGELOG.md.

v1.4.1 — v2 timezone, casing & rate-limit corrections

Corrections release. Six places where the v2 references described the API
inaccurately, all verified against the deployed qore/api and the live public
docs.

Read these two if you already integrate v2

• ⚠️ updatedAfter is read in Europe/Rome, not UTC. Polling incrementally
  in UTC does not raise an error — it silently skips shipments in the offset
  window. If you built an incremental sync on UTC timestamps, check it.
• ⚠️ /v2/sandbox responses are camelCase since qore/api 2.21.10 (live in
  production since 2026-09-03). They used to come back in snake_case while
  accepting camelCase on the way in. Breaking if you parse
  string_value / created_at — rename to stringValue / createdAt.

Also fixed

• v2 is not uniformly UTC and never emits a literal Z. parcels and
  orders use ATOM with an explicit +00:00; shipment tracking (statusDate,
  statusUpdatedAt, history[].date) and sandbox return "Y-m-d H:i:s" with
  no offset, in Europe/Rome. Moving tracking to real UTC is a planned
  breaking change, not a done one.
• orders, shipments, labels and couriers are in the public spec. They
  were marked "not yet published" — the Swagger snapshot had simply gone stale at
  2.14.0. They are published, just not written up in depth in this pack.
• Authentication: the field is apiKey, and the public docs now show it
  correctly. A wrong field name returns 422 (apiKey should not be blank),
  not 400; 400 means an absent or malformed body. 429 on the token endpoint
  is documented too.
• The v2 rate limit is 300 capacity, refill 150/min (since qore/api
  v2.20.0). The pack still documented 120 capacity and 2/sec, which is the
  separate v1.x bucket.
• The published spec's info.version does not identify the contracts inside
  it. It is a hand-dumped snapshot whose label reflects whenever the dump ran.
  Use it to spot a badly stale spec, never to decide whether a feature is
  present — read the schemas, or ask the live GET /v2/version.

Full detail in CHANGELOG.md.

v1.4.0 — v2 courier benchmarks + stock-release

Added

• v2: three new stable endpoints, verified against qore/api 2.12.0:
  • POST /v2/couriers/delivery-times — rank couriers fastest-first for a destination CAP (delivery-times:read)
  • POST /v2/couriers/efficiency-index — 0–100 score blending speed/consistency/reliability 40/20/40 (efficiency-index:read)
  • POST /v2/shipments/{id}/stock-release — redeliver / redeliver elsewhere / return to sender a shipment held in depot (shipments:write)
• New reference docs: references/v2/couriers.md, references/v2/stock-release.md
• New runnable example payloads in references/examples/v2/
• scripts/qapla_v2_client.py: get_delivery_times, get_efficiency_index, request_stock_release
• 3 new eval scenarios (#17–19), 19/19 total pass

Notes

• Flags an undocumented quirk found in the controller code: the product-entitlement gate on the two courier-benchmark endpoints is not wired yet despite being billable features — expect a future 403 PRODUCT_NOT_OWNED.

Full changelog: CHANGELOG.md

v1.1.2 — v1.3 hardening for client launch

Pre-client-launch hardening. The v1.3 core is unchanged and verified accurate against the live docs, the real implementation, and the internal docs.

Changed

• v2 section reduced to a drift-proof pointer to https://api.qapla.dev/v2/ — removed specifics that conflicted with the deployed API (auth field, version label, scopes, endpoint table, "preview" wording). The skill targets v1.3; for v2 follow the live docs.

Fixed

• webhooks.md: corrected the return-webhook refundMethodCode example ("ORIGINAL" → "0001").

Removed

• Internal docs/merge-plan.md; sanitized internal references in evaluation/scenarios.md.

Wired

• trackingbytimeframe.md and apivirtual.md added to the reading order in SKILL.md / AGENTS.md / the Cursor rule.

Full changelog: see CHANGELOG.md.

v1.1.1 — webhook payloads verified against local source

Patch release: references/webhooks.md re-verified against a now-local mirror of webhook.qapla.dev (previously verified via live fetch only).

Fixed

• qaplaStatusID is a string ("99"), not an integer — documented, with a note to coerce via Number() before comparing. The receiver/branching examples already used Number(), so they were correct.
• rows[] numeric fields are strings; the return-webhook (webhookReturnShipments) example now uses the real envelope values.
• Confirmed verbatim: retry = 2 more attempts (3 total), and auto-disable after 100 consecutive failures.

No behavioral change to the documented contract — fidelity/accuracy only.

v1.1.0 — webhooks, status model, versioning & migration

Content expansion merged from a comparison with a sibling integration skill, every fact verified against the authoritative sources (live webhook.qapla.dev + api.qapla.dev per-version sources) and validated by a fresh-context eval (12/12).

Added

• Webhooks (Pillar 2) — references/webhooks.md + a Node/PHP receiver example: event types, verified payloads (v1.2 core + v1.3 enhanced + the return envelope), the {"result":"OK"|"KO"} contract, retry/auto-disable, security.
• Canonical status model — references/statuses.md built from the real getQaplaStatus output (ids, labels, colors, ECCEZIONE sub-states) + the three context-dependent field namings (statusID / id / qaplaStatusID).
• Versioning — references/versioning.md: 1.3 current, 1.1/1.2 deprecated-but-active, 1.4 = createLabel-only, and the separate v2 generation (Bearer/JWT, UTC/ISO-8601, scopes).
• Migration — references/migration.md: legacy upgrade checklist + v1.x → v2 differences.
• Endpoint gaps — trackingbytimeframe.md (pull alternative to webhooks), apivirtual.md (virtual courier), and a confirmLabel two-step section in createlabel.md.

Fixed

• Corrected the getQaplaStatus catalog description and the version-policy wording.
• Fixed invented status ids (60/70) in the receiver example — caught by the eval — to the canonical 5/6.

Full changelog: see CHANGELOG.md.

v1.0.0 — multi-agent Qapla' API knowledge pack

First stable release: a portable, multi-agent knowledge pack for the Qapla' public REST API (v1.3), validated end-to-end (eval 7/7 with fresh-context agents).

Highlights

• Multi-agent support via thin entrypoints over a single source of truth (references/overview.md):
  • SKILL.md — Claude skill
  • AGENTS.md — universal (Codex, Gemini CLI, Cursor, Copilot, Windsurf, Aider, Zed, Jules… 20+ tools)
  • .cursor/rules/qapla-api.mdc — Cursor agent-requested rule (on-demand)
• Endpoint references + per-endpoint deep-dives, real sample payloads, and a dependency-free Python reference client.
• Evaluation scenarios with 7/7 passing (incl. the critical getQuotes header-auth and anti-hallucination cases).

See CHANGELOG.md for the full list.

The package version is independent from the documented Qapla' API version (1.3).