# Sorraia API

> Sorraia provides embeddable forms, booking calendars, and e-commerce widgets
> for websites. The REST API (base URL https://api.sorraia.app/v1) gives
> programmatic access to forms, submissions, calendars, bookings, shop widgets,
> and orders. Authenticate with an API key (Authorization: Bearer sor_live_...).
> Responses are JSON; list endpoints return a { data, pagination } envelope,
> single-resource endpoints return the object directly. Requests are rate-limited
> per key (1000/hour by default; see X-RateLimit-* headers). Read access spans
> all resources; write access covers forms and submissions.

## Getting started

- [Getting started](https://docs.sorraia.app/getting-started): Create an API key and make your first request (curl + TypeScript).
- [Authentication](https://docs.sorraia.app/authentication): API key format (sor_live_*), Bearer tokens, scopes (read:forms, write:forms, read:submissions, write:submissions, read:calendars, read:bookings, read:ecommerce, read:orders), and rotation.

## Resources

- [Forms](https://docs.sorraia.app/resources/forms): Create, read, update, archive forms. GET/POST /v1/forms, GET/PATCH/DELETE /v1/forms/{id}.
- [Submissions](https://docs.sorraia.app/resources/submissions): Read and ingest submissions. GET /v1/forms/{id}/submissions, GET /v1/submissions/{id}, POST /v1/forms/{id}/submissions (supports Idempotency-Key, 24h window).
- [Calendars](https://docs.sorraia.app/resources/calendars): Read calendar widgets. GET /v1/calendar-widgets, GET /v1/calendar-widgets/{id}.
- [Bookings](https://docs.sorraia.app/resources/bookings): Read bookings. GET /v1/calendar-widgets/{id}/bookings, GET /v1/bookings/{id}.
- [E-commerce](https://docs.sorraia.app/resources/ecommerce): Read shop widgets. GET /v1/ecommerce-widgets, GET /v1/ecommerce-widgets/{id}.
- [Orders](https://docs.sorraia.app/resources/orders): Read orders. GET /v1/ecommerce-widgets/{id}/orders, GET /v1/orders/{id}.

## Integrate

- [Webhooks](https://docs.sorraia.app/webhooks): Verify signed deliveries. Header X-Sorraia-Signature: t=<unix>,v1=<hmac-sha256-hex>; signed string is `${t}.${rawBody}`; HMAC-SHA256; 300s replay window.
- [TypeScript SDK](https://docs.sorraia.app/sdks): npm install @sorraia/sdk. Client class Sorraiasdk; namespaces forms/submissions/calendars/bookings/ecommerce/orders; bundled webhooks.verifySignature().

## Reference

- [API reference](https://docs.sorraia.app/api-reference/introduction): Full OpenAPI 3.1 reference — every endpoint, parameter, and response.