Skip to main content

​
URL base, versionamento e estrutura dos endpoints

A Sorsa usa versionamento na URL para manter as integrações estáveis. O número da versão faz parte da URL base, então cada requisição aponta explicitamente para uma versão da API.

​
URL base

Todas as requisições usam HTTPS. HTTP sem criptografia não é aceito.
Os caminhos dos endpoints são relativos a essa URL. Por exemplo, a URL completa para consultar um perfil é:

​
Versão atual: v3

v3 é a versão atual, estável e recomendada. Novos endpoints, campos de resposta e melhorias são lançados nela.

​
Como versionamos as mudanças

Nem toda atualização exige uma nova versão. As mudanças se dividem em duas categorias.

​
Mudanças compatíveis com a v3

Estas mudanças entram na versão atual sem exigir alterações na integração:
  • Novos endpoints.
  • Novos parâmetros de consulta opcionais.
  • Novos campos nos objetos JSON de resposta.
  • Mensagens de erro melhores ou mais detalhadas.
Como novos campos podem ser adicionados a qualquer momento, leia apenas os necessários e ignore chaves desconhecidas, em vez de falhar ao encontrar um campo inesperado.

​
Mudanças incompatíveis

Remover campos, renomear parâmetros, alterar a autenticação ou mudar o comportamento central de endpoints exige uma nova versão, como /v4. Nesse caso:
  • A versão anterior permanece disponível por um período de transição informado claramente.
  • Um guia de migração com mapeamento de campos e alterações estruturais é publicado com antecedência.
  • Os prazos de descontinuação são anunciados no painel e na documentação.

​
Versão legada: v2 (encerrada)

A v2 foi descontinuada e encerrada. A data prevista era 1º de maio de 2026, e seus endpoints agora retornam 410 Gone. Se você tem uma integração com a Sorsa v2, consulte os esquemas da v3 na referência da API e entre em contato com o suporte para ajuda com a migração. O guia de migração da API oficial do X trata de outra API de origem.

​
Próximos passos