convez.ai
SkillIntegração & APIsIntermediário
Qapla

Qapla' API — Knowledge Pack para IA

Qapla/qapla-api-skill

Knowledge pack para integração Qapla' em agentes de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill portátil que ensina agentes de IA a integrar com a API REST pública Qapla' (v1.3) para gerenciar remessas, pedidos brutos, etiquetas de transportadora, rastreamento, cotações em tempo real e pontos de coleta (PUDO). Funciona como skill Claude, AGENTS.md universal ou regra Cursor, com documentação offline espelhada da API oficial.

Instalação

$npx convez-ai Qapla/qapla-api-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
1
Saúde
37%
Último commit
há 3 semanas
Versão
v1.5.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automatizar integrações de logística e remessas em aplicações com IA
  • Consultar cotações e rastreamento de pedidos via agente conversacional
  • Gerar etiquetas de transportadora e gerenciar pontos de coleta programaticamente
  • Treinar assistentes de IA sobre a API Qapla sem acesso à rede

Veredito

Solução bem estruturada para capacitar agentes IA com conhecimento sobre logística Qapla', com múltiplos pontos de entrada (Claude skill, AGENTS.md, Cursor rules) e fonte única de verdade. Ideal para times que precisam de integrações de e-commerce/logística assistidas por IA.

README

A tradução para o português deste README ainda está na fila.

Qapla' API — AI Agent Knowledge Pack

Release API License

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 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.

What's inside

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
scripts/qapla_client.py      # dependency-free reference client

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.

Installing

Whichever agent you use, the references/ and scripts/ folders must travel with the entrypoint — they hold the actual knowledge.

Claude Code

Copy the whole folder into your skills directory:

# project-level (this repo only)
mkdir -p .claude/skills && cp -r qapla-api .claude/skills/

# or user-level (all your projects)
mkdir -p ~/.claude/skills && cp -r qapla-api ~/.claude/skills/

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 (Codex, Gemini CLI, Cursor, Copilot, Windsurf, Aider, Zed, Jules…)

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 root AGENTS.md, or
  • Use the file as-is if the project has no AGENTS.md yet.

Keep references/ and scripts/ at the path the snippet references (repo root by default) so the relative links resolve.

Cursor

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 these

The 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.

Quick start (the 30-second version)

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 apiKey in 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.

Scope & disclaimer

  • Covers the public API v1.3 (with notes on 1.4 and a pointer to the newer v2). It deliberately documents only what is public at https://api.qapla.dev.
  • This is documentation/tooling, not an official SDK. The live docs are authoritative; if anything here drifts, trust https://api.qapla.dev.

License

MIT.

Links

Ver o original no GitHub

Bom para

Relacionados