Developers

Everything an engineer - or an AI agent - needs to integrate with waybill.ge. The product's primary programmatic surface is a hosted MCP (Model Context Protocol) server; a small public REST API and machine-readable discovery files sit alongside it.

Quick reference

Resource URL
MCP endpoint /mcp/ (streamable HTTP)
Agent index (llms.txt) /llms.txt
OpenAPI spec /openapi.json
API reference (Swagger UI) /docs
Public REST API /api/v1/
OAuth discovery /.well-known/oauth-protected-resource/mcp/
Site map /sitemap.xml

Markdown-first: every public page on this site is also available as text/markdown - either send an Accept: text/markdown header or append .md to the path (for example /developers.md).

Authentication and scopes

Two credential types, both sent as a Bearer token to /mcp/:

  1. OAuth 2.1 (recommended for agent platforms such as claude.ai, Claude Code and Codex). Authorization-code flow with PKCE; dynamic client registration (RFC 7591) and client-ID metadata documents are both supported. Scope model:
    • mcp - access to the tenant's RS.GE waybill tools. What the token can do within that scope is further constrained server-side by the tenant's plan: trial tenants get read + draft tools only; write tools (activate, close, cancel, confirm, reject, invoice) require a paid plan. Discovery starts at /.well-known/oauth-protected-resource/mcp/.
  2. API keys (rsk_live_...) minted in the dashboard under API keys. A key is tenant-scoped, revocable at any time, shown once at creation, and stored server-side as an Argon2 hash. Keys inherit the same plan-based tool gating as OAuth tokens.

Never embed your RS.GE service password in a client; it is entered once in the dashboard and stored encrypted.

MCP tools

The server exposes typed tools for the full RS.GE waybill lifecycle: save_waybill_draft, activate_waybill, close_waybill, cancel_waybill, confirm_waybill, reject_waybill, save_invoice_from_waybill, plus read tools (get_waybill, list_seller_waybills, list_buyer_waybills, lookup_name_by_tin, lookup_taxpayer_info, list_units, list_waybill_types, list_transport_types) and system tools (check_credentials, get_quota_status, get_egress_ip, whoami). Every tool returns a structured {ok, data | code+message} JSON shape.

Public REST API

A minimal unauthenticated surface for integrators and agents:

  • GET /api/v1/plans - the current plan catalog (names, prices in GEL, quotas) as typed JSON
  • GET /health - service health (DB, RS.GE WSDL, payments provider)

Both are described with typed response schemas and operation IDs in /openapi.json.

Versioning and deprecation policy

  • The REST surface is versioned in the URL path (/api/v1/). Breaking changes ship as a new path version; v1 responses will not change shape without a version bump.
  • MCP tool schemas are additive by default: fields are added, not removed or repurposed.
  • When a surface is scheduled for removal we announce it at least 6 months ahead: the affected responses gain Deprecation and Sunset headers (RFC 8594) and the change is documented on this page. Nothing is removed silently.

Rate limits and quotas

  • The public REST API is rate-limited per client IP. Responses carry the IETF draft rate-limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy); exceeding the window returns 429 with a Retry-After header.
  • MCP tool calls draw down a per-tenant plan quota. Check remaining quota programmatically with the get_quota_status tool; exceeding it returns a structured QUOTA_EXCEEDED tool error (never a bare HTTP failure), and upgrade options are linked in the error payload.

Getting started

  1. Sign up (14-day trial, no card required)
  2. Connect your RS.GE service user in the dashboard (setup guide)
  3. Add the MCP server to your assistant - the dashboard's Connector page has copy-paste instructions for claude.ai, Claude Desktop, Claude Code and Codex - or mint an API key for custom clients

Integration questions: hello@waybill.ge.