# Alshhbaa Copperware API Developer Portal

This Alshhbaa Store developer portal documents the public agent-readable API, OpenAPI spec, auth guide, API versioning strategy, webhook policy, MCP server card, llms.txt, and checkout helper surfaces for Alshhbaa Copperware. The APIs support the Arabic storefront experience and are not a full partner commerce platform.

## Quickstart

1. Read [llms.txt](https://shop.alshhbaa.com/llms.txt) for agent use cases and constraints.
2. Fetch [OpenAPI](https://shop.alshhbaa.com/openapi.json) for endpoint schemas.
3. Read [API versioning](https://shop.alshhbaa.com/versioning.md) for stability and deprecation policy.
4. Read [webhooks](https://shop.alshhbaa.com/webhooks.md) for the current public webhook policy and polling alternative.
5. Use anonymous public endpoints for catalog search and checkout preparation.
6. Send `Idempotency-Key` on checkout or retryable write requests.
7. Confirm cart contents, customer details, delivery options, and total with the user before submitting checkout.

## Authentication

Public catalog and checkout helper endpoints are anonymous. Staff administration is session-authenticated and not available to agents. See [auth.md](https://shop.alshhbaa.com/auth.md) and [OAuth protected-resource metadata](https://shop.alshhbaa.com/.well-known/oauth-protected-resource).

## Versioning and Webhooks

The public API is documented as v1 in [OpenAPI](https://shop.alshhbaa.com/openapi.json) and [versioning.md](https://shop.alshhbaa.com/versioning.md). Alshhbaa Store does not currently provide public outbound webhook subscriptions; agents should use the documented order-status polling endpoint. See [webhooks.md](https://shop.alshhbaa.com/webhooks.md).

## API Surfaces

- `GET /api/status`
- `GET /api/search/suggestions?q=...`
- `GET /api/cities?q=...`
- `GET /api/address-suggestions?q=...`
- `GET /api/shipping-carriers?city=...`
- `POST /api/cart/sync`
- `POST /api/coupons/validate`
- `POST /api/checkout`
- `GET /api/orders/{id}/status?token=...`

## Errors and Rate Limits

Errors use JSON objects with `error.code`, `error.message`, and optional `error.hint`. API responses include `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers.