Controle de APIversões da RTC
O /v1 promessa
Seção intitulada “O /v1 promessa”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.
Defina os formatos de resposta com RTC-Version
Seção intitulada “Defina os formatos de resposta com RTC-Version”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ão | Alterações |
|---|---|
| nenhuma | Formas originais. Os erros são { "error": "<message>", "code"? }. |
2026-11-01 | Os 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.
Fixar cargas úteis de webhooks com apiVersion
Seção intitulada “Fixar cargas úteis de webhooks com apiVersion”Cada ponto de extremidade do webhook possui um apiVersion que corrige o envelope que recebe, independentemente dos cabeçalhos da solicitação:
apiVersion | Envelope |
|---|---|
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.
Versão do contrato para SDKs
Seção intitulada “Versão do contrato para SDKs”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.
Descrição da OpenAPI
Seção intitulada “Descrição da OpenAPI”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.