API REST pública

Usa la API REST pública de cside para aprovisionar equipos y dominios gestionados 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. Revisa cada elemento de data.results 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 solo los permisos que necesita la integración:

Permiso	Acceso a la API
Crear equipos (teams:create)	POST /v1/teams/
Registrar dominios (domains:create)	POST /v1/domains/
Eliminar dominios (domains:delete)	DELETE /v1/domains/

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.

Envía el token con cada solicitud:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Los tokens siguen siendo válidos hasta que un administrador selecciona Revocar todos los tokens. Esta acción invalida de inmediato todos los tokens de API de la organización.

Límite de solicitudes

La API acepta 60 solicitudes por organización y minuto. Este límite se comparte entre los endpoints de equipos y dominios. 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.

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:

Estado	Significado
created	cside registró el nombre de host y devolvió su nuevo domainId
existing	El mismo equipo ya posee el nombre de host y se devuelve el domainId original
invalid	cside no registró el nombre de host, consulta code y message

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.

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:

Código	Significado
empty_domain	El valor de entrada está vacío
invalid_domain	El nombre de host no es válido
public_suffix_domain	El valor de entrada es un sufijo público y no un nombre de host registrable
internal_domain	El nombre de host está reservado o no está permitido
reserved_ip	DNS resuelve el nombre de host a una dirección IP reservada
wildcard_conflict	Un dominio comodín existente ya abarca este nombre de host
subdomain_conflict	Una configuración de dominio existente ya incluye este subdominio
domain_already_licensed	Otro equipo ya gestiona el nombre de host
internal_error	cside no pudo validar ni crear el dominio

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.

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.

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."
}

Estado HTTP	Códigos de error habituales	Acción
400	invalid_request	Revisa el cuerpo JSON, los campos obligatorios, las cadenas de ID y los límites de elementos
401	unauthorized	Revisa el token Bearer y si se revocaron todos los tokens de la organización
403	insufficient_scope, enterprise_required, errores de suspensión	Revisa los permisos del token, el acceso al plan y el estado de la cuenta
404	team_not_found	Confirma que el ID del equipo pertenece a la organización del token
409	team_name_exists	Elige un nombre de equipo único o usa el equipo existente
429	rate_limited	Vuelve a intentarlo con una pausa progresiva después del intervalo de límite de solicitudes actual
503	rate_limit_unavailable, domain_deletion_unavailable	Vuelve a intentarlo más tarde y contacta con el soporte de cside si el error continúa

Lista de comprobación de seguridad

• Genera un token independiente 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 todos los tokens de la organización si alguno queda expuesto
• 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