A portable knowledge pack that teaches an AI coding agent how to integrate with and answer questions about the Qapla' public REST API (v1.3) — shipments, raw orders, carrier labels, tracking, real-time quotes, pickup points (PUDO), address checks, couriers, and channels. It also documents the stable core of the newer v2 generation (Bearer/JWT auth, RESTful resources, async jobs) — auth, parcels, sandbox, and jobs.
It mirrors the official, public documentation at https://api.qapla.dev/1.3/ so the agent can work without network access, and links back to the live docs as the source of truth.
The same content is exposed through several agent entrypoints — a Claude
skill (SKILL.md), a universal AGENTS.md (read by Codex, Gemini CLI,
Cursor, Copilot, Windsurf, Aider, Zed, Jules and 20+ tools), and a Cursor
rule (.cursor/rules/qapla-api.mdc). All of them point back to a single
source of truth in references/overview.md, so there is no duplicated content
to drift.
SKILL.md # Claude entrypoint (skill, with YAML frontmatter)
AGENTS.md # universal entrypoint (Codex, Gemini, Cursor, Copilot, …)
.cursor/rules/qapla-api.mdc # Cursor entrypoint (agent-requested rule)
references/
overview.md # single source of truth: core facts, domain model, decision rule
conventions.md # base URL, response envelope, rate limiting, sandbox, dates
authentication.md # per-channel API Key
endpoints.md # full endpoint catalog
versioning.md # version policy (1.3/1.2/1.4/v2) + which version to call
migration.md # upgrading a legacy integration; v1.x → v2
statuses.md # canonical status model (branch on the id, not the label)
webhooks.md # Pillar 2: outbound event callbacks
pushshipment.md # deep-dives for the main endpoints
pushorder.md
createlabel.md # incl. confirmLabel (generate → transmit) flow
getquotes.md
getpudos.md
trackingbytimeframe.md # pull alternative to webhooks
apivirtual.md # virtual courier (push your own status updates)
examples/ # real request/response JSON samples + webhookReceiver.md
v2/ # the v2 generation (Bearer/JWT, RESTful, async jobs)
overview.md # model, base URL, JWT, RFC 7807 errors, async jobs
authentication.md # token exchange (apiKey → Bearer JWT) + scopes
parcels.md # parcels resource CRUD
sandbox.md # sandbox playground resource CRUD
couriers.md # delivery-time / efficiency-index network benchmarks
stock-release.md # release a shipment held in depot (giacenza)
endpoints.md # v2 catalog: stable core + in-flight resources
examples/v2/ # runnable v2 JSON samples (auth, parcels, job, error, sandbox,
# delivery-times, efficiency-index, stock-release)
scripts/qapla_client.py # dependency-free reference client (v1.3)
scripts/qapla_v2_client.py # dependency-free reference client (v2: JWT, REST, jobs)
The three entrypoints are thin: they orient the agent and point into
references/. All shared knowledge lives under references/ and scripts/, so
a documentation fix is made once.
Whichever agent you use, the references/ and scripts/ folders must travel
with the entrypoint — they hold the actual knowledge.
Export the tree into your skills directory:
# project-level (this repo only)
mkdir -p .claude/skills/qapla-api
git archive HEAD | tar -x -C .claude/skills/qapla-api
# or user-level (all your projects)
mkdir -p ~/.claude/skills/qapla-api
git archive HEAD | tar -x -C ~/.claude/skills/qapla-apigit archive is used rather than cp -r because evaluation/ is marked
export-ignore in .gitattributes and must not be
installed: it lists the expected answer for every validation prompt, so an
agent that can read it while answering one of those prompts is grading its own
homework. (This also keeps it out of GitHub's release tarballs. The suite still
lives in the repo — it is a maintainer tool, not part of the knowledge pack.)
If you copy by hand instead, exclude it explicitly:
rsync -a --exclude 'evaluation/' --exclude '.git/' ./ ~/.claude/skills/qapla-api/The skill loads automatically when a task matches its description. Keep
SKILL.md at the skill root (valid YAML frontmatter: name, description) with
the supporting files under references/.
AGENTS.md is the universal entrypoint. Drop this repo's content
into the project where you integrate Qapla' and either:
- Merge the snippet — copy the block between the
<!-- BEGIN qapla-api -->/<!-- END qapla-api -->markers into your project's existing rootAGENTS.md, or - Use the file as-is if the project has no
AGENTS.mdyet.
Keep references/ and scripts/ at the path the snippet references (repo root
by default) so the relative links resolve.
Copy the rule (and the knowledge it points to) into your project:
mkdir -p .cursor/rules && cp .cursor/rules/qapla-api.mdc .cursor/rules/
cp -r references scripts . # the rule links into theseThe rule is agent-requested (alwaysApply: false, no globs), so Cursor
pulls it in on demand when your prompt matches its description — the closest
analog to a Claude skill. The .mdc extension and frontmatter are required;
a plain .md in .cursor/rules is ignored.
curl -X POST https://api.qapla.it/1.3/pushShipment \
-H 'Content-Type: application/json' \
-d '{
"apiKey": "YOUR_CHANNEL_API_KEY",
"pushShipment": [
{ "trackingNumber": "1Z999AA10123456784", "courier": "UPS",
"email": "customer@example.com", "name": "Jane Doe" }
]
}'- Base URL:
https://api.qapla.it/<version>/<endpoint> - Auth: per-channel
apiKeyin the JSON body (Control Panel → Settings → Channels → Configure → Private API Key) - Response:
{"pushShipment": {"result": "OK", "error": null, ...}} - Rate limit: token bucket, 120 capacity, +2/sec; a batch of N costs N
See SKILL.md and references/ for everything else.
- Covers the public API v1.3 (with notes on
1.4) and the stable core of v2 (auth, parcels, sandbox, jobs, courier delivery-time/efficiency-index benchmarks, shipment stock-release). v2's still-in-flight resources (orders, general shipments CRUD, labels, courier list/get) are flagged and point to the live docs. The v2 core is extracted from the deployed implementation, which can be ahead of the public Swagger — https://api.qapla.dev/v2/ remains the source of truth. - This is documentation/tooling, not an official SDK. The live docs are authoritative; if anything here drifts, trust https://api.qapla.dev.
MIT.
- Latest release: https://github.com/Qapla/qapla-api-skill/releases/latest
- Changelog: CHANGELOG.md
- API docs: https://api.qapla.dev/1.3/
- Control Panel: https://cp.qapla.it
- Qapla': https://www.qapla.it