Versão 2.0 da documentação. APIs NÃO AFETADAS.

Como parte do nosso projeto de expansão e do nosso comprometimento com a qualidade e garantia de funcionamento dos serviços, nossa documentação foi atualizada para a versão 2.0! Esta não é uma mudança que afeta as APIs, mas sim uma atualização que impacta apenas a documentação, seus artigos e suas disposições.

O principal pilar desta versão é garantir que as informações entregues nos artigos estejam fiéis às mudanças ocorridas nos nossos produtos durante o período de um ano entre esta revisão e a última.

Reforço que, conforme consta nos nossos changelogs, realizamos mudanças e ajustes pontuais ao longo dos meses. Entretanto, esta é uma revisão geral e uma remodelação de diversos aspectos da documentação, com o objetivo de atender melhor às necessidades dos nossos produtos em constante crescimento, além de incorporar os feedbacks coletados dos usuários ao longo do ano.

Principais mudanças

Página "Comece aqui"

Entendemos que esta página é a primeira e principal que nosso usuário encontra ao iniciar seus estudos sobre o ecossistema de APIs do BTG Pactual Empresas. Por isso, refizemos esta página do zero, incluindo mais informações e melhorando sua estrutura com base no feedback recebido e nos aprendizados adquiridos ao longo deste ano.

A mudança proporciona uma melhoria considerável na experiência de desenvolvimento nos momentos iniciais da integração.

Home

A página inicial da nossa documentação, antes chamada de "Guias", agora passa a se chamar "Home". Fizemos essa mudança porque a ideia é que, nesta página, se concentrem informações sobre o funcionamento dos produtos, além de guias básicos de implantação para os primeiros passos na construção da integração. Portanto, chamar a página apenas de "Guias" não faz mais sentido.

Nesta página, também removemos artigos não críticos, que não tinham adesão e geravam uma alta necessidade de manutenção a cada pequena mudança nas APIs.

Além disso, alteramos o nome de alguns artigos para que estejam mais alinhados com nosso padrão de nomenclatura. Também revisamos seus conteúdos e garantimos que as referências feitas a eles continuem funcionando, apesar das mudanças.

Nossos artigos sobre os produtos agora se concentram exclusivamente nos aspectos de funcionamento, regras específicas de negócios e casos de uso. Essa mudança foi realizada em conjunto com a criação das fichas técnicas de API, e todos os artigos de produtos contêm um link direto para a ficha técnica correspondente.

APIs

Entendemos que um dos principais fatores que dificultam as integrações em alguns momentos é a falta de clareza quanto ao fluxo necessário para geração do token em cada API e ao escopo necessário para seu consumo. Isso ocorria porque essas informações estavam condensadas com dados não técnicos sobre o funcionamento do produto, em um único artigo.

Optamos, então, por separar as informações e elaborar o que chamamos de ficha técnica de API. As fichas técnicas de API estarão localizadas na API Reference, sob o respectivo produto. Por exemplo, a ficha técnica de boletos estará no handler "Boletos" da API Reference, e abaixo deste handler estarão as chamadas (POST, GET, PUT...), como no passado. Essa mudança nos permite manter as informações técnicas da API junto aos seus endpoints, enquanto as informações não técnicas permanecem separadas no artigo presente na Home.

Uma ficha técnica de API conterá:

O esquema de segurança implementado;
O escopo necessário para consumo;
O fluxo de geração de token;
A máquina de estados (quando aplicável);
Os eventos de webhook, com suas descrições e payloads.

Por fim, removemos todos os botões "try it" dos endpoints, pois não eram compatíveis com nosso servidor de autenticação, o que gerava uma experiência negativa.

Recipes

Removemos temporariamente a aba Recipes. Temos planos para o futuro que envolvem uma repaginação completa da aba e a inclusão de muito material novo e pertinente. No entanto, no momento, essas mudanças dependem de outros fatores internos.

Portanto, por não oferecer uma boa experiência e não ter capacidade imediata de evolução, optamos pela remoção temporária.

Mudanças gerais

Para garantir a qualidade das informações da documentação e a experiência de navegação, fizemos uma revisão do conteúdo, removendo informações desatualizadas e substituindo-as por informações mais recentes.

Incluímos também novas informações para enriquecer alguns artigos, tornando mais claros aspectos que antes não estavam suficientemente explicados para o usuário.