Saltar para o conteúdo
Verificado

Visão geral

Um endpoint, um envelope de resposta e os 337 métodos a que uma chave de API pode aceder.

Cada ecrã do painel da Xuda, cada programa do Studio e cada integração de terceiros chama a mesma superfície HTTP: o CPI, abreviatura do despachante de métodos da plataforma. Existe um só formato de endpoint, /cpi/<method>, e um só envelope de resposta. Aprendê-lo uma vez cobre todos os 337 métodos a que uma chave de API de conta pode aceder atualmente.

O endpoint

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

<method> é um nome de método como get_account_projects ou dbs_read, nunca um caminho de recurso com um id lá dentro. Todos os dados de entrada, incluindo um id, são parâmetros: em POST é um campo num corpo JSON, em GET é um parâmetro da query string (consulte Chamar um método para as regras de corpo versus query e exemplos práticos em cURL, JavaScript e Python).

Este site de documentação

A documentação é servida em xuda.ai/docs, pelo que a sandbox deste site chama /cpi/<method> na mesma origem. O seu próprio código, a correr em qualquer lado, chama https://xuda.ai/cpi/<method> diretamente.

O envelope

Todos os métodos, com sucesso ou falha, respondem com o mesmo formato:

json
{ "code": 1, "data": { "...": "..." } }
  • code > 0 é sucesso. O número em si não tem significado além de ser positivo, leia data.
  • code < 0 é um erro. data é normalmente uma string de mensagem; uma falha de validação também acrescenta um campo message derivado dela. Consulte Erros para os códigos em que vale a pena ramificar e os que deve simplesmente registar e apresentar.
  • Um método que devolve um ficheiro ou um tipo de conteúdo personalizado (uma exportação CSV, uma imagem) dispensa o envelope JSON e define os seus próprios cabeçalhos e corpo. Essa é a exceção, não a regra.
  • Uma resposta bem-sucedida inclui um cabeçalho xu-region com o nome da região Xuda que tratou a chamada. Uma resposta de erro não o inclui.

Autorização e o muro privado

Todos os métodos têm uma clearance: public, user, user_access, developer ou admin. Indica quem lhe pode aceder através de uma sessão iniciada no painel: um método public não precisa de nada, os restantes precisam de uma sessão com esse nível ou superior.

Uma chave de API é um muro separado, não outra clearance. Um método também tem um indicador private. private: true é absoluto: nenhuma chave de API o pode chamar, nem mesmo uma com acesso total, independentemente da sua clearance. Cerca de um quarto do catálogo é público nesse sentido: 337 métodos em 24 microserviços, abrangendo desde Voice e Domains até ao Drive e à API de criação do Studio. O resto, incluindo todos os métodos do próprio api_module (os métodos que criam e gerem chaves de API), continua a ser apenas de sessão. Autenticação explica o acesso total versus personalizado das chaves, e cada guia de módulo abaixo termina com a tabela em direto do que o seu microserviço expõe.

Encontrar um método

A referência da API interativa lista os 337 métodos com os seus campos e permite executar um na sua própria conta diretamente a partir do navegador.