Saltar al contenido
Verificada

Resumen

Un endpoint, un sobre de respuesta y los 337 métodos a los que puede llegar una clave de API.

Cada pantalla del panel de Xuda, cada programa de Studio y cada integración de terceros llama a la misma superficie HTTP: CPI, siglas del despachador de métodos de la plataforma. Hay una sola forma de endpoint, /cpi/<method>, y un único sobre de respuesta. Aprenderlo una vez cubre los 337 métodos a los que una clave de API de cuenta puede llegar hoy.

El endpoint

POST https://xuda.ai/cpi/<method>GET  https://xuda.ai/cpi/<method>

<method> es un nombre de método como get_account_projects o dbs_read, nunca una ruta de recurso con un id dentro. Toda entrada, incluido un id, es un parámetro: en POST es un campo de un cuerpo JSON, y en GET es un parámetro de la cadena de consulta (consulta Llamar a un método para las reglas de cuerpo frente a consulta y ejemplos prácticos en cURL, JavaScript y Python).

Este sitio de documentación

La documentación se sirve en xuda.ai/docs, así que el sandbox de este sitio llama a /cpi/<method> en el mismo origen. Tu propio código, ejecutándose en cualquier lugar, llama directamente a https://xuda.ai/cpi/<method>.

El sobre

Cada método, con éxito o con error, responde con la misma forma:

json
{ "code": 1, "data": { "...": "..." } }
  • code > 0 es éxito. El número en sí no tiene más significado que ser positivo, lee data.
  • code < 0 es un error. data suele ser una cadena de mensaje; un fallo de validación también añade un campo message derivado de ella. Consulta Errores para ver los códigos que conviene ramificar y los que basta con registrar y mostrar.
  • Un método que devuelve un archivo o un tipo de contenido personalizado (una exportación CSV, una imagen) omite el sobre JSON y establece sus propias cabeceras y cuerpo. Es la excepción, no la regla.
  • Una respuesta correcta lleva una cabecera xu-region con el nombre de la región de Xuda que atendió la llamada. Una respuesta de error no la lleva.

Autorización y el muro privado

Cada método tiene un clearance: public, user, user_access, developer o admin. Indica quién puede llegar a él mediante una sesión iniciada en el panel: un método public no necesita nada, el resto necesitan una sesión de ese nivel o superior.

Una clave de API es un muro aparte, no otro nivel de autorización. Un método también tiene una marca private. private: true es absoluta: ninguna clave de API puede llamarlo, ni siquiera una con acceso total, sea cual sea su clearance. Aproximadamente una cuarta parte del catálogo es público en ese sentido: 337 métodos en 24 microservicios, que abarcan desde Voice y Domains hasta Drive y la API de creación de Studio. El resto, incluido cada método del propio api_module (los métodos que crean y gestionan las claves de API), queda solo para sesión. Autenticación explica el acceso total frente al personalizado de las claves, y cada guía de módulo de abajo termina con la tabla en vivo de lo que expone su microservicio.

Encontrar un método

La referencia de la API interactiva lista los 337 métodos con sus campos y te permite ejecutar uno contra tu propia cuenta directamente desde el navegador.