# Horeca API

The API supports the Horeca browser application and its authenticated MCP server. Browser routes use a Better Auth session cookie; the MCP endpoint accepts a resource-bound OAuth bearer token. OAuth tokens are not accepted by the browser API routes. See [authentication instructions](https://horeca.derrumbar.top/auth.md) before using authenticated routes.

## Discovery and status

- `GET /api/healthz` — public application and database status.
- `GET /.well-known/api-catalog` — API links in RFC 9264 Linkset JSON format.
- `GET /openapi.json` — machine-readable API description.
- `POST /api/mcp` — MCP endpoint for authenticated buyer catalog search. Requires the `horeca:catalog:read` OAuth scope.
- `GET /.well-known/oauth-protected-resource` — protected-resource metadata for the MCP endpoint.
- `GET /.well-known/oauth-authorization-server` — OAuth authorization server metadata.
- `GET /.well-known/openid-configuration` — OpenID Connect provider metadata.
- `GET /api/auth/jwks` — public signing keys used to verify OAuth access tokens.

OAuth authorization, token, registration, user-info, and revocation endpoints are published in the authorization server metadata. Registration supports CIMD and explicit Dynamic Client Registration.

## Session and catalog

- `GET /api/me` — current user, buyer site, and supplier association.
- `GET /api/catalog` — products, categories, suppliers, and offers visible to the signed-in account.
- `PUT /api/me/site` — create or update a buyer delivery site.

## Buyer orders

- `POST /api/quotes` — calculate delivery eligibility and current order totals for a buyer cart.
- `POST /api/checkouts` — create a Stripe Checkout session from a valid quote.
- `GET /api/checkouts/{sessionId}` — read the signed-in buyer’s checkout status.
- `POST /api/checkouts/{sessionId}/cancel` — cancel a pending checkout session.
- `GET /api/orders` — list orders visible to the signed-in account.

## Supplier and operations routes

- `PATCH /api/supplier/offers/{offerId}` — update supplier offer fields.
- `PATCH /api/supplier-orders/{id}/status` — advance a supplier order through an allowed status transition.
- `POST /api/supplier/connect/onboarding` — create a supplier’s Stripe Connect onboarding link.
- `POST /api/orders/{id}/refund` — request a full refund; operations role required.
- `GET /api/operations/stripe-reconciliation` and `POST /api/operations/stripe-reconciliation/{id}/retry` — inspect and retry pending payment movements; operations role required.

All browser mutations require the application origin. The API validates request bodies and does not treat `robots.txt` rules as access control.