> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplepay.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Mapa de la API publica de SimplePay, base URL, autenticacion, objetos principales, scopes y paginas por endpoint.

La referencia interactiva se genera desde `/openapi.json`. Cada operacion publica tiene su propia pagina con uso recomendado, auth, scopes, idempotencia, ejemplo minimo y contrato OpenAPI embebido.

## Base URL

```txt theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://api.simplepay.mx
```

## Autenticacion

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer spk_sandbox_...
```

Todas las rutas publicas usan bearer auth. Algunas rutas declaran scopes en `x-simplepay-required-scopes`; ademas, las superficies de pago pasan por politica de tenant.

## Grupos de endpoints

| Area                 | Endpoints                                                                                                                                                                                    |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OpenAPI              | `GET /openapi.json`                                                                                                                                                                          |
| Bookable config      | `GET /v1/bookable-payments/config`, `GET /v1/bookable-payments/preflight`, `POST /v1/bookable-payments/setup`                                                                                |
| Products             | `GET /v1/products`, `POST /v1/products`, `GET/PATCH /v1/products/{id}`                                                                                                                       |
| Catalog              | `GET /v1/catalog/products`, categories y category tree                                                                                                                                       |
| Availability         | resources, schedules, rules, overrides, blackouts, slots                                                                                                                                     |
| Customer Hub         | `GET/POST /v1/customer-hub/customers`, `GET/PATCH /v1/customer-hub/customers/{customer_id}`, contacts, addresses, relationships, timeline, notes, tags, imports, sync-sources, provider-sync |
| Bookings             | holds, booking checkout, reads, cancel, no-show, reschedule, refund                                                                                                                          |
| Payments             | checkout sessions, payment links, refunds                                                                                                                                                    |
| Policy               | `GET /v1/payment-policy/effective`, `POST /v1/payment-policy/evaluate`                                                                                                                       |
| Webhooks             | webhook endpoints y event replay                                                                                                                                                             |
| Enterprise inventory | product bundle, package grants, offers, availability, holds, bookings                                                                                                                        |

## Como leer una pagina de endpoint

Cada pagina de endpoint tiene cuatro capas:

<Steps>
  <Step title="Uso">
    Cuando conviene llamar ese endpoint y que responsabilidad cumple dentro de
    la integracion.
  </Step>

  <Step title="Antes de llamar">
    Metodo, ruta, auth, scopes declarados, idempotencia y guia relacionada.
  </Step>

  <Step title="Patron recomendado">
    Reglas practicas para backend, retries, persistencia, webhooks y
    reconciliacion.
  </Step>

  <Step title="Contrato OpenAPI">
    Playground interactivo, parametros, body, responses y schemas generados
    desde la spec.
  </Step>
</Steps>

## Objetos de pago

| Objeto           | Prefijo      | Uso                                   |
| ---------------- | ------------ | ------------------------------------- |
| Checkout Session | `spcs_...`   | URL hospedada de pago.                |
| Payment Link     | `splink_...` | Link reusable o limitado.             |
| Refund           | `sprf_...`   | Reembolso administrado por SimplePay. |

## Policy preflight

Antes de mostrar metodos caros o restringidos, evalua politica:

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://api.simplepay.mx/v1/payment-policy/evaluate" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_key": "bookable_payments",
    "payment_surface": "hosted_checkout",
    "amount_minor": 90000,
    "currency": "mxn",
    "payment_method_types": ["card"],
    "installments": {
      "enabled": true,
      "desired_months": [3, 6]
    }
  }'
```

## Scopes declarados

| Scope                              | Endpoints tipicos                                                                                           |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `products:read`                    | Products, Bookable config y preflight.                                                                      |
| `products:write`                   | Product create/update, setup, bundles.                                                                      |
| `catalog:read`                     | Catalog products y categories.                                                                              |
| `customer_hub:read`                | Customer Hub list/read (customers, timeline, imports, sync sources).                                        |
| `customer_hub:write`               | Customer Hub customer create/update, addresses, relationships, external refs, links, imports, sync sources. |
| `customer_hub.contacts:write`      | Customer Hub contact add/update.                                                                            |
| `customer_hub.notes:write`         | Customer Hub note add.                                                                                      |
| `customer_hub.segments:read`       | Customer Hub tag list.                                                                                      |
| `customer_hub.segments:write`      | Customer Hub tag create.                                                                                    |
| `customer_hub.provider_sync:write` | Customer Hub provider projection trigger.                                                                   |
| `availability:read`                | Slots, resources, schedules, blackouts.                                                                     |
| `availability:write`               | Mutaciones de availability y event types.                                                                   |
| `bookings:read`                    | Booking list/read.                                                                                          |
| `bookings:write`                   | Holds, checkout, lifecycle y booking refunds.                                                               |
| `webhooks:read`                    | List webhook endpoints.                                                                                     |
| `webhooks:write`                   | Create/delete endpoints y replay events.                                                                    |
| `policies:read`                    | Effective policy y evaluate.                                                                                |

## Descargar la spec

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS "https://docs.simplepay.mx/openapi.json" -o simplepay-openapi.json
```

Generar un cliente TypeScript:

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx openapi-typescript "https://docs.simplepay.mx/openapi.json" -o simplepay-api.d.ts
```

<Tip>
  La pestana "API Reference" incluye una pagina MDX por cada operacion publica
  de SimplePay, agrupada por producto para que humanos y agentes puedan
  navegarla sin adivinar rutas.
</Tip>