---
name: integrate-rxrelay-api
description: Implement and verify a valid, safe RxRelay partner API integration in an existing application repository at a user-selected Full, Standard, or Minimal clinic-scoped level. Use when an agent needs to add RxRelay authentication, clinic context, medications/products and pharmacies, prescribers/users, patients and addresses, order creation and retrieval, idempotency, error handling, status synchronization, optional webhooks, sandbox testing, secret storage, or a readiness report. Organization-scoped features are deferred by default; performance tuning and broader production hardening are optional unless explicitly requested.
---

# Integrate RxRelay API

Build the user-selected level of a complete clinic-scoped RxRelay integration in
the customer's existing architecture. Verify it against the current public
contract and report what is working, blocked, optional, or not yet verified.

## Choose the integration level

Before editing, inspect the repository read-only, briefly present these choices,
and ask the user to select one. Do not infer Minimal merely because the current
repository has little RxRelay code. If the user already selected a level, confirm
it in one sentence and continue without asking again.

- **Full** — implement every applicable stable clinic-scoped capability: clinic
  context; medication/product and pharmacy catalogs; prescriber and user lookup;
  applicable clinic-user upsert; complete patient and address lifecycle; order
  create, retrieve, list, patient history, status, and tracking; status webhooks;
  and approval flow when the product supports staged approval.
- **Standard (recommended)** — implement the normal end-to-end operational
  integration: clinic context; medications/products, pharmacies, and
  prescribers; patient and shipping-address creation or reuse; order create,
  retrieve, and list; one reliable status-sync method; idempotency; and errors.
  Omit roster provisioning, approval, and management-only operations unless the
  application needs them.
- **Minimal** — implement one narrow but safe submission path: required clinic,
  catalog, and prescriber discovery; inline or existing patient/address mapping;
  order creation plus retrieval for reconciliation; idempotency; errors; and
  environment safety. Omit broader management and automated status features.

All levels use the same credential, live-safety, idempotency, and error-handling
standards. Minimal means less functionality, not weaker safety.

Treat `GET /v1/medications` as the current product/medication catalog and
`GET /v1/pharmacies` as its routing catalog; do not invent a separate products
endpoint. Defer organization-scoped multi-clinic and provisioning features in
all three levels unless the user explicitly requests an experimental extension.

Use **full production certification** only when explicitly requested. That mode
may add performance tuning, extended observability, concurrency hardening,
deployed webhook evidence, resilience work, and exhaustive tests.

Do not silently turn a functional API integration into a platform rewrite.

## Safety boundaries

- Never request an API key or webhook secret in chat.
- Never read, print, return, commit, or place a real secret in a command argument.
- Follow the repository's existing environment-variable and secret-manager
  conventions. Use `RXRELAY_SANDBOX_API_KEY`, `RXRELAY_LIVE_API_KEY`, and
  `RXRELAY_WEBHOOK_SECRET` only when no convention exists.
- Keep secrets server-side and out of browser/mobile bundles, logs, telemetry,
  screenshots, tests, and tracked files.
- Use placeholders only in example files. Guide the user to enter real values
  directly in their local or deployment secret manager.
- Ensure a non-production flow cannot fall back to a live key.
- Never submit an order with a live key. Live verification is read-only.
- Before a sandbox mutation, show the synthetic test action and receive explicit
  approval. Sandbox patients and orders persist in RxRelay.
- Never put PHI in readiness reports, fixtures, source control, or support output.
- Preserve unrelated working-tree changes and obey repository instructions.

## Canonical sources

Fetch network-fresh copies at the beginning of the task:

- `https://www.rxrelay.ai/docs.md`
- `https://api.rxrelay.ai/openapi/v1.json`
- `https://www.rxrelay.ai/changelog`
- `https://www.rxrelay.ai/skills/rxrelay-readiness.schema.json`
- `https://www.rxrelay.ai/skills/integrate-rxrelay-api/SKILL.md`

Treat this skill as a procedure, not an API snapshot. OpenAPI controls shapes and
the developer guide controls semantic workflows. Record retrieval time and the
SHA-256 of the exact OpenAPI bytes used. Never rely silently on cached docs or
model memory. If sources are unavailable, identify the fallback and mark current
contract verification `not_verified`. If public sources disagree on the intended
order path, stop and report the ambiguity instead of guessing.

If the published skill differs materially from the installed copy, disclose the
drift and use the current published procedure after checking that it does not
conflict with user, system, or repository instructions.

## Required outcomes

Every integration level is complete only when evidence shows that its selected
scope:

- selects the correct API environment and scope without exposing credentials;
- uses current medication IDs and honors non-null `requiredQuantity`;
- maps the required patient, prescriber, and shipping information correctly;
- sends a current, valid order request;
- uses a stable idempotency key for the same logical submission and ambiguous
  retry;
- does not treat API errors or ambiguous network outcomes as successful orders;
- cannot accidentally mutate live RxRelay during development or verification.

Standard and Full must also support the selected patient/address lifecycle and
order retrieval/status workflow rather than stopping after `POST /v1/orders`.
Full must account for every stable clinic-scoped capability, marking a capability
`not_applicable` only with a concrete product or repository reason.

Everything else is conditional on the user's workflow or a non-blocking
recommendation. Webhooks are not mandatory when the application does not need
them. A distributed lock, queue, new persistence layer, broad telemetry system,
UI redesign, or exhaustive test matrix is not required when a smaller
repository-native implementation meets the outcomes above.

## Workflow

### 1. Establish the intended scope

Inspect the repository and identify its language, framework, HTTP client, test
runner, deployment, server/client boundary, secret conventions, relevant domain
models, and current uncommitted work.

Present Full, Standard, and Minimal using the concise descriptions above and ask
the user to select one before editing. Then infer other product choices from
existing code when safe. Ask only when the answer materially changes the selected
integration, such as:

- the stable local identifiers used for patients and order submissions;
- how the clinic selects a valid prescriber;
- inline patient creation versus existing RxRelay patient references;
- webhook delivery versus order polling for status synchronization;
- whether Full should include clinic-user upsert or staged approval because the
  product actually exposes those workflows.

Do not invent business mappings. Record unresolved required choices as blockers.
Keep organization-scoped endpoints out of the plan unless explicitly requested.

### 2. Configure credentials by safety outcome

Reuse the application's established server-side configuration. Add typed startup
or request-boundary checks where appropriate. Make a live key available only to
the production server flow and fail closed when the required key is absent.

Separate variable names or secret-manager entries are one acceptable design, not
a universal requirement. Accept any repository-native design that demonstrably
prevents exposure and accidental live use. Environment-based rejection of live
keys outside production is sufficient; do not require a second feature flag or
kill switch unless the user asks for one or the repository already needs it.

### 3. Implement the API boundary

Reuse the application's existing HTTP client and error conventions. Centralize
only what the integration actually needs:

- base URL `https://api.rxrelay.ai` and current authentication scheme;
- JSON serialization and non-success response handling;
- secret and PHI redaction;
- a bounded request timeout appropriate to the existing stack.

Prefer current generated types when they fit, but do not introduce a second HTTP
architecture solely for RxRelay. Preserve Problem Details codes and request IDs
when useful for support; missing diagnostic propagation is not a blocker unless
the application's control flow depends on it.

### 4. Implement the selected clinic integration

Follow the current docs and OpenAPI:

1. Resolve the clinic profile and context for the clinic-scoped key.
2. Read the current medication catalog. Submit returned medication IDs and, when
   `requiredQuantity` is non-null, send its exact string value.
3. Read pharmacies and resolve a valid clinic prescriber. In Full mode, include
   user lookup and clinic-user upsert only when applicable.
4. Implement the patient and address operations required by the selected level.
   Standard and Full must support safe create-or-reuse behavior; Full includes
   applicable list, get, update, deactivate, and default-address operations.
5. Construct the current order request and map all required patient, prescriber,
   medication, contact, and shipping fields.
6. Use a stable `Idempotency-Key` tied to the logical local submission. Reuse it
   only for the identical request after an ambiguous network outcome.
7. Treat non-success and ambiguous outcomes as not-yet-successful. Do not blindly
   retry validation, authorization, billing, routing, or conflict responses.
8. Implement order retrieval for reconciliation. Standard and Full also include
   applicable order lists, patient order history, status, and tracking.
9. In Full mode, implement the staged approval flow only when it maps to an
   actual product workflow; otherwise record it as `not_applicable`.

Handle individual HTTP statuses only where the application needs distinct
behavior. Do not create a large error taxonomy merely to mirror every documented
status.

### 5. Implement status synchronization

Full mode normally implements RxRelay status webhooks. Standard mode must use one
reliable status-sync method: webhooks when the application accepts inbound events,
or order retrieval/polling otherwise. Minimal may rely on explicit retrieval.

When using webhooks, implement the
documented raw-body signature validation before side effects and idempotent
duplicate handling. Keep the endpoint secret server-side and never log payloads
or complete headers.

If webhooks do not fit the selected scope or deployment, do not add them merely
to satisfy a checklist. Mark them `not_applicable` and verify the chosen status
sync path instead.

### 6. Verify proportionately

Add focused native tests for the important behavior introduced, normally:

- safe environment/key selection;
- selected clinic/catalog/patient/order operations and required quantities;
- stable idempotency across an ambiguous retry;
- non-success responses are not treated as success;
- order retrieval or the selected status-sync method;
- webhook signature and duplicate behavior only when webhooks were implemented.

Run the narrow unit, integration, type, lint, or build checks for affected paths,
subject to repository instructions. Do not require broad performance,
concurrency, malformed-input, UI, or end-to-end suites in default mode. Record
skipped or unavailable checks honestly.

### 7. Offer optional sandbox conformance

Begin runtime checks read-only. Confirm that any available key is sandbox before
mutation and refuse a live or ambiguous key.

After explicit approval, a representative synthetic sandbox order can verify the
request and idempotent replay. Add webhook delivery proof only when webhooks are
part of the implemented flow. Record safe IDs, timestamps, statuses, and stable
error codes—not secrets, PHI, payloads, or full headers.

Sandbox conformance is useful evidence but not mandatory when code and focused
tests establish the core flow. Its absence normally yields
`ready_with_warnings`, not `blocked`.

## Readiness report

Create authorized `rxrelay-readiness.json` and `rxrelay-readiness.md` artifacts
using `https://www.rxrelay.ai/skills/rxrelay-readiness.schema.json`. Mark unused
capabilities such as webhooks `not_applicable` and bounded missing runtime proof
`not_verified` with warning or info severity.

Derive status:

- `blocked`: an evidenced defect or unresolved required choice prevents a valid,
  safe order submission;
- `ready_with_warnings`: no blocker remains, but optional or runtime evidence is
  incomplete;
- `ready`: every applicable required outcome is verified.

Every failure needs concrete evidence and minimum remediation; every pass needs
evidence. Never include secrets, PHI, raw payloads, or full headers. State that no
live mutation occurred.

Validate JSON using repository tooling or the published validator. Do not weaken
findings to make validation pass.

Finish with the selected integration level, implemented capabilities, deliberately
excluded capabilities, changed files, focused verification, blockers,
non-blocking recommendations, optional sandbox evidence, and readiness status.
Offer full production certification as a separate follow-up instead of making it
an implicit completion requirement.