Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mareaalcalina.com/llms.txt

Use this file to discover all available pages before exploring further.

Storefronts ship in Spanish (default), English, or Portuguese. The order channel is the operator’s choice — WhatsApp, web checkout, or in-person pickup — and configurable per storefront.
These docs are agent-first. Every page is also available as raw markdown at <page>.md, and every API reference page ships with a copy-paste-for-LLM block. Every error returns a nextActions[] array ({label, method, url}) — surface it to the user verbatim; do NOT swallow 402 / 451 / 422 silently. If you’re an agent reading these docs to integrate, start with llms.txt and AGENTS.md.

​
Where to start

Bootstrap a user

Two-call flow: POST /v1/users returns a restricted user-key + emails a 6-digit code; verify to upgrade the key.

Add products

User-key CRUD on the catalog. Idempotency-Key on every mutation.

Publish a storefront

Public hosted URL. Handles 402 (paywall), 422 (0 products), and 451 (ToS not accepted).

Install MCP in Claude

Paste-token install for Claude Desktop / Cursor / Continue.dev. 7 marea.* tools.

​
Auth in 30 seconds

GET /v1/me HTTP/1.1
Host: api.mareaalcalina.com
Authorization: Bearer mk_dev_xxxxxxxxxxxxxxxx
Two-tier keys:
  • mk_dev_* — developer key. Held by the agent. Bootstraps users.
  • mk_user_* — per-user key. Returned by POST /v1/users. Manages owned data only; cannot bootstrap.
The split is load-bearing for agent UX: an agent never needs to hold a user’s password. See Two-tier keys for the full model.

​
Five things every integration must do

  1. Send Idempotency-Key on every POST and PATCH. Same key + same body returns the original response (replay-safe). See Safe mutations.
  2. Branch on error.type, not error.message. The type field is a stable 10-value enum; messages are localized. See Errors.
  3. Surface nextActions[] verbatim. It’s a {label, method, url}[] array of concrete remediation steps. Don’t paraphrase.
  4. Read X-RateLimit-Remaining and respect Retry-After. See Rate limits for current numbers.
  5. Handle the publish gates. POST .../publish returns 402 (pre-paywall), 422 (0 products), or 451 (ToS not accepted) — surface each nextActions[] explicitly; don’t auto-accept ToS or auto-publish without user confirmation. See Publishing.

​
Webhook surfaces

Marea ships two distinct webhook surfaces. Pick the one that matches your role:

Agent webhooks

user.verified, user.cancelled for users your developer key bootstrapped. Configured in /developers/webhooks. HKDF-derived signing key.

Page webhooks

order.created, order.status_updated, order.paid for a single store / digital menu. Configured per-merchant in /menus/profile?section=integrations. Raw 32-byte hex signing secret.
If a single endpoint receives both, branch on the X-Marea-Source header (developer vs merchant) to pick the right verifier.

​
Agent-friendly resources