# Descripción general de la API

> Automatiza tiendas, scripts, alertas y reportes PCI DSS de Proteside con la API REST v1 y recibe eventos por webhook.

URL: https://docs.proteside.com/es/docs/api

La API pública v1 te da acceso, por código, a casi todo lo que haces en el dashboard. Úsala para integrar Proteside con
tu CI/CD, SIEM, herramienta de tickets o panel de partner, y usa los webhooks para reaccionar a eventos sin tener que
consultar la API constantemente.

## Qué puedes automatizar
* **Tiendas:** crear una tienda, obtener la clave del SDK y el snippet de instalación, ajustar la configuración del
  SDK, rotar la clave y comprobar si el SDK está instalado.
* **Páginas de pago:** registrar las URLs de checkout que el SDK debe proteger.
* **Scripts:** listar el inventario y autorizar o bloquear scripts con justificación (PCI DSS 4.0, requisito 6.4.3).
* **Reglas:** crear, activar, desactivar y eliminar reglas de bloqueo o de permiso por dominio, URL o hash.
* **Políticas de aprobación:** crear, simular y aplicar políticas que deciden sobre los scripts automáticamente.
* **Alertas:** listar, consultar, resolver y reabrir alertas.
* **Reportes PCI DSS:** generar y descargar reportes en JSON, PDF o CSV y programar el envío semanal o mensual.
* **Webhooks:** registrar endpoints, canales de Slack y de Microsoft Teams y disparar eventos de prueba.
* **Partners:** crear organizaciones hijas, actuar en ellas y seguir el consumo de cada una.

## Antes de empezar
| Elemento          | Valor                                       |
| ----------------- | ------------------------------------------- |
| Base URL          | `https://app.proteside.com/api/v1`          |
| Transporte        | HTTPS, cuerpo y respuestas en JSON          |
| Nombres de campos | `snake_case`                                |
| Autenticación     | `Authorization: Bearer ps_live_…`           |
| Límite            | 120 solicitudes por minuto por organización |

> **No existe un entorno de pruebas**
>
> Todos los tokens emitidos son `ps_live_` y cada llamada actúa sobre tus datos de producción. Para experimentar, usa
> una tienda de homologación y tokens con alcances de solo lectura.

La API está hecha para llamadas de servidor a servidor: las rutas autenticadas no responden a CORS, así que las
llamadas hechas directamente desde el navegador se bloquean. Guarda el token en tu backend.

## Inicio rápido
### Crea un token
En **Ajustes → API**, haz clic en **Nuevo token**, ponle un nombre, marca el atajo **solo lectura** y haz clic en
**Crear token**. Copia el token en la ventana **Copia el token ahora**: aparece una sola vez. El paso a paso completo
está en [Tokens y alcances](https://docs.proteside.com/es/docs/api/authentication).

### Haz la primera solicitud
Lista las tiendas de tu organización:

```bash
export PROTESIDE_TOKEN="ps_live_TU_TOKEN"

curl -s "https://app.proteside.com/api/v1/stores?limit=2" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN"
```

### Lee la respuesta
Las listas siempre vienen en `data`, con `next_cursor` para obtener la página siguiente (`null` cuando terminó):

```json
{
  "data": [
    {
      "id": "0c1d2e3f-1111-4222-8333-444455556666",
      "org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
      "name": "Mi Tienda",
      "domain": "mitienda.com",
      "country": "BR",
      "timezone": "America/Sao_Paulo",
      "status": "active",
      "sdk_key": "pk_live_TU_CLAVE",
      "safe_slug": "mitienda-ps3fa9c1",
      "emergency_contact": null,
      "created_at": "2026-09-27T10:01:00.000Z",
      "updated_at": "2026-09-27T10:01:00.000Z",
      "sdk_config": {
        "mode": "monitor",
        "payment_methods": ["pix", "card"],
        "release_channel": "stable"
      }
    }
  ],
  "next_cursor": null
}
```

Los headers `X-RateLimit-Limit` y `X-RateLimit-Remaining` muestran cuánto queda del límite por minuto. Consulta
[Convenciones](https://docs.proteside.com/es/docs/api/conventions) para la paginación, los errores y los límites.

## Especificación OpenAPI
El contrato completo de la API está en [`https://app.proteside.com/api/v1/openapi.json`](https://app.proteside.com/api/v1/openapi.json)
(OpenAPI 3.1, público, sin token). Importa esa dirección en Postman, en Insomnia o en el generador de clientes de tu
lenguaje. La [referencia de endpoints](https://docs.proteside.com/es/docs/api/reference/stores/listStores) de esta documentación se genera a partir de
ella.

> **Nota**
>
> Cuando esta documentación y el spec no coincidan, vale lo que se describe aquí: las páginas conceptuales registran el
> comportamiento real de la API, incluidos los puntos en los que el spec todavía está desactualizado.

## Próximos pasos
- [Tokens y alcances](https://docs.proteside.com/es/docs/api/authentication): Crea, usa y revoca tokens con el menor privilegio posible.
- [Convenciones](https://docs.proteside.com/es/docs/api/conventions): Paginación, errores, límite de solicitudes e idempotencia.
- [Webhooks](https://docs.proteside.com/es/docs/api/webhooks): Recibe eventos firmados y valida la firma.
- [Partners](https://docs.proteside.com/es/docs/api/partners): Gestiona organizaciones hijas con un único token.
- [Recetas](https://docs.proteside.com/es/docs/api/recipes): Flujos completos con curl, del registro de la tienda al reporte PCI.

## Referencia de endpoints
- [Tiendas](https://docs.proteside.com/es/docs/api/reference/stores/listStores): Crear, configurar, suspender y rotar la clave del SDK.
- [Páginas](https://docs.proteside.com/es/docs/api/reference/pages/listPages): Páginas de pago protegidas.
- [Scripts](https://docs.proteside.com/es/docs/api/reference/scripts/listScripts): Inventario, autorización y bloqueo.
- [Reglas](https://docs.proteside.com/es/docs/api/reference/rules/listRules): Bloqueo y permiso por dominio, URL o hash.
- [Políticas](https://docs.proteside.com/es/docs/api/reference/policies/listPolicies): Políticas de aprobación automática.
- [Alertas](https://docs.proteside.com/es/docs/api/reference/alerts/listAlerts): Consultar, resolver y reabrir.
- [Reportes](https://docs.proteside.com/es/docs/api/reference/reports/getPciReport): Reporte PCI DSS y programaciones.
- [Webhooks](https://docs.proteside.com/es/docs/api/reference/webhooks/listWebhooks): Canales de webhook, Slack y Teams.
- [Organizaciones](https://docs.proteside.com/es/docs/api/reference/organizations/listOrganizations): Organizaciones hijas y consumo.
- [Meta](https://docs.proteside.com/es/docs/api/reference/meta/getOpenApi): Documento OpenAPI.
