API REST pública

Usa la API REST pública de cside para crear o eliminar equipos, gestionar dominios y añadir selectores de páginas de pago desde un flujo de trabajo de backend. La API usa JSON sobre HTTPS y un token Bearer de la organización.

URL base: https://api.cside.com

Flujo de aprovisionamiento

La creación de equipos y el registro de dominios son operaciones independientes:

1. Crea un token de API de la organización con los permisos necesarios
2. Llama a POST /v1/teams/ y guarda el teamId devuelto
3. Llama a POST /v1/domains/ con ese teamId y hasta 100 nombres de host
4. Llama a POST /v1/payment-pages/ para añadir selectores de páginas de pago al equipo
5. Revisa cada respuesta antes de dar por finalizado el aprovisionamiento

Si el registro de dominios falla, el equipo permanece disponible. La API no revierte la creación correcta de un equipo.

Disponibilidad y autenticación

Un administrador de la organización puede generar un token en Configuración de la organización > General en el panel de cside. Selecciona Generar token, asigna un nombre al token (por ejemplo, el de la integración a la que pertenece) y elige solo los permisos que necesita la integración:

teams:create o teams:delete también permite consultar con un filtro name no vacío. domains:create o domains:delete permite consultar con un filtro domain no vacío. Las listas sin filtro requieren teams:read o domains:read; las integraciones de solo lectura pueden usar estos permisos sin acceso de escritura. Las lecturas comparten con las escrituras el límite de 60 solicitudes por minuto y organización.

El panel muestra cada token una sola vez. Guárdalo en un gestor de secretos del servidor antes de cerrar el cuadro de diálogo. No lo expongas en código del navegador, no lo envíes al control de versiones ni lo escribas en los registros de la aplicación.

Los tokens tienen la forma cside_oatv2_<id>_<secret>. La parte <id> identifica el token en la lista del panel y en los registros de auditoría; el resto es el secreto.

Envía el token con cada solicitud:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Gestionar y revocar tokens

Configuración de la organización > General muestra todos los tokens activos con su Nombre, el prefijo enmascarado del Token, sus Ámbitos, la fecha de Creación y la fecha de Último uso. Una organización puede tener hasta 50 tokens activos. Cuando se alcanza el límite, revoca un token que no uses antes de generar uno nuevo.

Un token sigue siendo válido hasta que se revoca. Puedes revocar tokens de dos formas:

• Revocar un solo token desde la lista. Solo ese token deja de funcionar y el resto de integraciones siguen en marcha.
• Revocar todos los tokens para invalidar de una vez todos los tokens de API de la organización, incluidos los que no aparecen en la lista.

Los tokens generados antes de que existiera la lista de tokens no aparecen en ella. Siguen funcionando, pero Revocar todos los tokens es la única forma de revocarlos.

La creación de tokens, la revocación individual y Revocar todos los tokens se registran en el registro de auditoría de la organización como org.api_token.create, org.api_token.revoke y org.api_secret.rotate.

Límite de solicitudes

La API acepta 60 solicitudes por organización y minuto. Este límite se comparte entre los endpoints de equipos, dominios y páginas de pago. Una solicitud que supere el límite devuelve 429 con el código de error rate_limited. Vuelve a intentarlo con una pausa progresiva cuando comience el siguiente minuto.

Crear un equipo

Usa POST /v1/teams/ para crear un equipo en la organización del token.

curl --request POST \
  --url https://api.cside.com/v1/teams/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Acme Production"
  }'

El nombre del equipo debe cumplir estos requisitos:

• Contener entre 3 y 32 caracteres
• Usar letras, números, guiones bajos, espacios o apóstrofos
• Ser único dentro de la organización

No se admiten guiones en los nombres de equipo.

Una solicitud correcta devuelve 201 Created:

{
  "data": {
    "teamId": "1897425263682514944"
  }
}

Guarda data.teamId. Lo necesitarás para registrar o eliminar dominios del equipo.

Un conflicto devuelve 409 team_name_exists con el equipo existente, así que repetir la llamada es seguro y te sigue dando un ID con el que trabajar:

{
  "error": "team_name_exists",
  "message": "Team with name `Acme Production` already exists in this organization.",
  "data": {
    "teamId": "1897425263682514944"
  }
}

Crear un equipo no activa la incorporación automática de dominios. Esta función se configura por separado para cada equipo y está desactivada de forma predeterminada.

Registrar dominios

Usa POST /v1/domains/ para registrar entre 1 y 100 nombres de host de dominios gestionados para un equipo. team_id es obligatorio cuando usas un token de API de la organización.

curl --request POST \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "domains": [
      "checkout.example.com",
      "app.example.com"
    ]
  }'

Envía los nombres de host sin protocolo, puerto, ruta, cadena de consulta ni fragmento. cside elimina los espacios en blanco y normaliza en minúsculas los nombres de host aceptados.

Cada elemento registra el nombre de host exacto que envías. La API no crea un dominio comodín, por lo que debes incluir todos los nombres de host que necesites, como example.com y www.example.com.

El endpoint devuelve 200 OK con un resultado por cada valor de entrada, en el mismo orden:

{
  "data": {
    "results": [
      {
        "status": "created",
        "input": "checkout.example.com",
        "domain": "checkout.example.com",
        "domainId": "1897425263682514945"
      },
      {
        "status": "existing",
        "input": "app.example.com",
        "domain": "app.example.com",
        "domainId": "1897425263682514946"
      },
      {
        "status": "invalid",
        "input": "not a hostname",
        "code": "invalid_domain",
        "message": "Domain is invalid."
      }
    ],
    "totals": {
      "created": 1,
      "existing": 1,
      "invalid": 1
    }
  }
}

La solicitud puede incluir resultados correctos y no válidos y aun así devolver 200 OK. Revisa cada resultado:

Los reintentos son seguros para los dominios que ya se crearon para el mismo equipo. Devuelven existing en lugar de crear un duplicado. Un nombre de host gestionado por otro equipo devuelve invalid con domain_already_licensed.

Si los dominios se guardaron pero cside no pudo terminar de enviar la configuración a la red de distribución, la solicitud devuelve 503 domain_registration_unavailable con el mensaje “Domains saved, but synchronization is incomplete. Retry to synchronize them.” Envía de nuevo la misma solicitud: los nombres de host guardados se devuelven como existing y se reintenta la sincronización.

Los dominios nuevos reciben automáticamente protección gestionada. No se requiere una llamada independiente a la API para activarlos. La configuración puede tardar un poco en llegar a la red de distribución.

Códigos de validación de dominios

Un resultado invalid puede incluir uno de estos códigos:

Añadir páginas de pago

Usa POST /v1/payment-pages/ para añadir un selector de página de pago a un equipo existente. team_id es obligatorio cuando usas un token de API de la organización. Es opcional para un token limitado a un equipo y, si lo envías, debe coincidir con el equipo del token.

curl --request POST \
  --url https://api.cside.com/v1/payment-pages/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "payment_page": "checkout.example.com/checkout"
  }'

Envía payment_page como un selector canónico de host/ruta, sin https://, puerto ni URL completa. Por ejemplo, usa checkout.example.com/checkout, no https://checkout.example.com/checkout. cside elimina los espacios en blanco alrededor del selector, así como las cadenas de consulta y las barras finales, antes de guardarlo. Un fragmento # se conserva tal como se envía, de modo que las aplicaciones de página única que enrutan su página de pago mediante un fragmento pueden coincidir con él. Un selector que contenga espacios en blanco, como checkout.example.com/check out, se rechaza con 400 invalid_payment_page.

El selector usa el mismo formato de patrón que el panel. Un equipo puede tener hasta 500 selectores de páginas de pago. El endpoint no registra dominios, así que registra primero el nombre de host con POST /v1/domains/ si el equipo aún no lo gestiona.

El endpoint devuelve 200 OK:

{
  "data": {
    "status": "created",
    "teamId": "1897425263682514944",
    "paymentPage": "checkout.example.com/checkout"
  }
}

Añadir de nuevo el mismo selector es seguro y devuelve status: "existing". Un selector nuevo devuelve status: "created". Cuando el equipo posee dominios que coinciden, cside actualiza sus proyecciones de páginas de pago y la configuración relacionada después de guardar el selector a nivel de equipo.

Cargar cside para el equipo

Usa el teamId devuelto al crear el equipo en la URL estándar del script de cside. No lo sustituyas por un domainId.

<script
  src="https://[your-team-id].csidetm.com/client.js"
  referrerpolicy="origin">
</script>

El nombre de host de la página debe estar registrado en el equipo cuyo ID se usa en la URL del script. Si falta el registro o el equipo no coincide, la solicitud devuelve 403. Si esto ocurre justo después del registro, vuelve a intentarlo poco después. Contacta con el soporte de cside si el problema continúa.

La monitorización estándar no requiere un CNAME del cliente ni redirigir el tráfico. Si tu sitio tiene una política de seguridad de contenido restrictiva, sigue la guía de configuración de CSP para permitir *.csidetm.com.

Incorporación automática de dominios

La incorporación automática de dominios es una función opcional del equipo para implementaciones que cargan el script de arranque estándar de cside. Está desactivada de forma predeterminada en los equipos nuevos. Contacta con tu representante de cside si necesitas activarla.

Cuando la función está activada y un nombre de host sin registrar carga el script de arranque /client.js o /script.js específico del equipo, cside envía el nombre de host de referencia mediante el mismo flujo de validación y registro de dominios. Mantén el atributo estándar referrerpolicy="origin" para que el origen de la página esté disponible sin exponer su ruta ni su cadena de consulta.

La solicitud que detecta el nombre de host sin registrar no se vuelve a intentar. El registro se aplica a una solicitud posterior del script una vez que la configuración se ha propagado. Los dominios registrados automáticamente aparecen en el inventario de dominios del equipo igual que los registrados mediante la API.

La incorporación automática no crea equipos y las solicitudes a otros endpoints de cside no registran ningún nombre de host. Usa el flujo explícito de la API cuando necesites un resultado para cada dominio antes de desplegar el script. La incorporación automática se aplica al script de monitorización estándar y no activa la recopilación de Device Intelligence.

Listar equipos

Usa GET /v1/teams/ con un token de organización. Los tokens de equipo no pueden llamar a este endpoint. Omite name para listar equipos o indica un nombre exacto, distinguiendo mayúsculas y minúsculas, para buscarlo. Se recortan los espacios de los extremos, igual que al crear equipos. Los equipos renombrados pueden compartir nombre; trata siempre el resultado como una matriz. Se incluyen los equipos suspendidos. Si no hay coincidencias, devuelve 200 OK con data vacío.

curl --get \
  --url https://api.cside.com/v1/teams/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --data-urlencode "name=Acme Production"

{
  "data": [
    {
      "id": "1897425263682514944",
      "name": "Acme Production",
      "createdAt": "2026-07-07T10:00:00Z",
      "suspended": false
    }
  ],
  "next_cursor": null
}

Listar dominios

Usa GET /v1/domains/ para listar dominios. Con un token de organización, omite team_id para consultar toda la organización o indícalo para seleccionar un equipo. Un token de equipo solo puede consultar su propio equipo, incluso sin team_id. Un equipo desconocido o inaccesible devuelve 404 team_not_found. El filtro opcional domain busca un nombre de host exacto.

curl --get \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --data-urlencode "team_id=1897425263682514944"

{
  "data": [
    {
      "id": "1897425263682514945",
      "domain": "checkout.acme.com",
      "teamId": "1897425263682514944",
      "managed": true,
      "wildcard": false,
      "suspended": false,
      "createdAt": "2026-07-07T10:00:00Z"
    }
  ],
  "next_cursor": null
}

Los resultados incluyen dominios gestionados y no gestionados. id corresponde al domainId del registro de dominios. Comprueba managed antes de usar ese ID con DELETE /v1/domains/: esta API solo permite eliminar dominios gestionados. Si el nombre de host no coincide, devuelve data vacío.

Paginar los resultados

Ambos endpoints aceptan limit (de 1 a 100, 50 por defecto) y un cursor opcional. Los resultados se ordenan por creación, del más antiguo al más reciente, y por ID en caso de empate. Cada respuesta 200 OK contiene una matriz data y next_cursor. Continúa hasta que next_cursor sea null.

Trata el cursor como opaco y codifícalo para URL al enviarlo. Mantén el mismo ámbito del token y los mismos filtros entre páginas. Un cursor mal formado o de otra consulta o cuenta devuelve 400 invalid_cursor; reinicia la consulta sin cursor.

curl --get \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --data-urlencode "team_id=1897425263682514944" \
  --data-urlencode "cursor=NEXT_CURSOR"

Eliminar dominios

Usa DELETE /v1/domains/ con los valores domainId devueltos por el registro de dominios. No envíes nombres de host a este endpoint.

curl --request DELETE \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "domains": [
      "1897425263682514945",
      "1897425263682514946"
    ]
  }'

Puedes enviar entre 1 y 100 ID de dominio. Una solicitud correcta devuelve resultados parciales ordenados:

{
  "data": {
    "results": [
      {
        "status": "deleted",
        "domainId": "1897425263682514945",
        "domain": "checkout.example.com"
      },
      {
        "status": "not_found",
        "domainId": "1897425263682514999"
      }
    ],
    "totals": {
      "deleted": 1,
      "not_found": 1
    }
  }
}

La eliminación es idempotente. Un ID desconocido, un dominio ya eliminado o un dominio ajeno al equipo de destino devuelve not_found sin exponer información sobre otro equipo.

Eliminar un equipo

Usa DELETE /v1/teams/ para eliminar permanentemente un equipo y todos sus dominios. La solicitud requiere un token de organización con Eliminar equipos (teams:delete). Este permiso incluye la eliminación de dominios; domains:delete por sí solo no permite eliminar un equipo. Genera un token nuevo para añadir este permiso a una integración existente. No se aceptan tokens limitados a un equipo.

Envía el teamId obtenido al crear el equipo como team_id, una cadena decimal entre comillas. No necesitas enumerar sus dominios ni eliminarlos por separado.

curl --request DELETE \
  --url https://api.cside.com/v1/teams/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944"
  }'

Una solicitud correcta devuelve 200 OK. deletedDomains indica el número de dominios eliminados:

{
  "data": {
    "status": "deleted",
    "teamId": "1897425263682514944",
    "deletedDomains": 2
  }
}

Un equipo con una suscripción de Stripe asociada devuelve 409 team_subscription_attached. Cancela la suscripción antes de eliminar el equipo. Si ya está cancelada y el error persiste, contacta con el soporte de cside.

Un equipo desconocido, ajeno a la organización del token o ya eliminado devuelve 404 team_not_found. Repetir una eliminación correcta no elimina nada más. Si la limpieza falla, se devuelve 503 team_deletion_unavailable. Vuelve a intentarlo más tarde y contacta con soporte si el error continúa.

El acceso Enterprise se comprueba en cada solicitud. Si eliminas el último equipo Enterprise activo de la organización, las solicitudes posteriores a la API pública, incluidos los reintentos, devuelven 403 enterprise_required.

Errores de solicitud

Los errores que afectan a toda la solicitud tienen esta estructura:

{
  "error": "insufficient_scope",
  "message": "Token is missing the domains:create scope."
}

Lista de comprobación de seguridad

• Genera un token independiente y con nombre para cada integración de backend
• Concede solo los permisos que necesita esa integración
• Guarda los tokens en un gestor de secretos del servidor
• Nunca expongas tokens en código del navegador, URL, control de versiones ni registros
• Revoca de inmediato un token si queda expuesto; usa Revocar todos los tokens cuando no puedas saber qué token se filtró o cuando el token sea anterior a la lista de tokens
• Revisa la columna Último uso y revoca los tokens que ya no se utilicen
• Trata los ID de equipo y dominio devueltos como cadenas

Documentación relacionada

• Referencia interactiva de la API
• Agregar tu dominio
• Agregar el script de cside
• Configuración del panel