Pular para o conteúdo
Documentation

Controle de APIversões da RTC

Tudo o que está sob /v1 alterações apenas de forma adicional. A RTC poderá adicionar:

  • novas rotas, campos opcionais de solicitação e parâmetros de consulta;
  • novos campos de resposta, códigos de erro, tipos de eventos de webhook e valores de enumeração;
  • novos cabeçalhos de resposta.

Crie clientes que ignorem campos desconhecidos e tratem um código de erro desconhecido como o código genérico de seu status HTTP. A RTC não remove nem renomeia um campo, não altera seu tipo ou significado, não torna uma entrada opcional obrigatória nem reutiliza um código de erro sob /v1.

Uma alteração compatibilidade é lançada como um novo caminho principal, /v2. Ambas as versões, então, funcionam em paralelo por pelo menos 12 meses antes /v1 foi descontinuada, com aviso neste site.

Algumas melhorias alteram a forma de uma resposta sem alterar seu significado, como a envelope de erro estruturado. Elas são opcionais por solicitação, com um cabeçalho de versão datado:

RTC-Version: 2026-11-01
VersãoAlterações
nenhumaFormas originais. Os erros são { "error": "<message>", "code"? }.
2026-11-01Os erros utilizam o envelope { "error": { code, message, details?, requestId, retryable, docUrl } }.

A RTC aplica a versão mais recente, desde que não seja posterior à data do seu envio, e a reflete no RTC-Version cabeçalho de resposta. Uma data anterior à primeira versão mantém os formatos originais. Fixe a versão para a qual seu código foi escrito e altere-a deliberadamente quando fizer a atualização.

Cada ponto de extremidade do webhook possui um apiVersion que corrige o envelope que recebe, independentemente dos cabeçalhos da solicitação:

apiVersionEnvelope
legacy{ id, type, createdAt, projectId, data }, o webhook único anterior foi migrado para um endpoint
2026-11-01{ id, type, apiVersion, createdAt, tenantId, projectId, roomId?, data }, o padrão para novos endpoints

Evento data cresce de forma aditiva, assim como o API. Para migrar um destinatário para uma versão mais recente da carga útil, adicione um segundo endpoint com a nova versão, altere seu processamento e, em seguida, remova o endpoint antigo.

GET /v1/capabilities relatórios contractVersion, que é atualizado sempre que o contrato do cliente é ampliado. SDKs pode utilizá-lo para habilitar novos recursos apenas nos casos em que a API já os suporte.

As rotas de clientes da RTC são descritas no OpenAPI 3.1, gerado a partir dos esquemas com os quais a API APIvalida as solicitações e verificado em relação ao código a cada alteração. O arquivo está docs/openapi/v1.yaml no repositório da plataforma RTC . Contato CHAMPREP para receber o arquivo atual para geração do cliente; esta referência e o API referência permanecem na documentação pública.