Devolver a documentação pro padrão que devs já leem.

O Portal do Desenvolvedor BB cobria 8 APIs públicas: Pix, Cobrança, Contas, Pagamentos, Cartões, Câmbio, Investimentos, Crédito. Cada produto tinha inventado sua estrutura de documentação. O resultado prático foi exatamente o que o cliente reclamava:

"Eu não encontro o que cada API retorna, e não sei onde a documentação está." Frase repetida em uma forma ou outra em quase toda entrevista. Schema de resposta enterrado em pop-up secundário. Busca limitada a uma API por vez. Tempo até a primeira chamada: longo.

Os tickets de suporte estavam saturados com pergunta óbvia — "esse endpoint retorna o quê?" — e a adoção das APIs estava travada. A documentação estava online; só não estava sendo lida.

Eu e o PM sentamos com 9 desenvolvedores integradores — internos e parceiros. A pergunta não foi "o que vocês acham da nossa documentação". Foi: mostre como você lê a documentação de outra API que você usou recentemente.

A diferença é tudo. Observar usuários antes de perguntar pra eles revelou um padrão claro que eles não tinham vocabulário pra articular: Swagger / OpenAPI. Endpoint, método, parâmetros, request, response — sempre na mesma ordem, schema visível na página, sem pop-up.

Eles não estavam pedindo nada novo. Estavam pedindo o que já sabiam ler. Se Stripe, Twilio, GitHub e Mercado Pago leem em Swagger, o BB lê em Swagger também.

Uma página, uma gramática. As 8 APIs compartilham layout, hierarquia e atalho de busca. O que muda é o conteúdo.

{
  "agencia": "1234-5",
  "conta":   "00012345-6",
  "saldo":   15820.40,
  "moeda":   "BRL",
  "atualizadoEm": "2023-08-14T11:32Z"
}

{
  "error": "invalid_token",
  "hint":  "renove via /oauth/refresh"
}

$ curl https://api.bb.com.br/v2/contas/00012345-6/saldo \
   -H "Authorization: Bearer $TOKEN" \
   -H "X-Application-Id: $APP_ID"

1. Não desafiar o padrão sem motivo. Dev é usuário. Tem modelo mental fixo. Se Swagger é a gramática lida em todo lugar, o portal do BB lê em Swagger. A diferenciação não está na forma — está na clareza do conteúdo.
2. Schema visível é contrato. Mostrar o JSON sem clique extra significa que o dev mapeia o próprio código enquanto lê. Esconder schema é esconder o produto.
3. Busca é navegação, não atalho. ⌘K é a forma como dev percorre doc. Endpoint, keyword, código de erro foram pré-requisito, não nice-to-have.
4. Mesma estrutura nas 8 APIs. Visão geral, autenticação, primeiros passos, reference. Onboarding e referência separados — ambos a um clique.

Lançamos o portal reformulado em uma única virada, com redirect das URLs antigas. O time de produto acompanhou a métrica de adoção da API por 90 dias.

Em paralelo: tickets de suporte do tipo "qual o retorno desse endpoint?" caíram fortemente (atribuído pelo time de atendimento). Tempo até primeira chamada bem-sucedida reduzido. A doc passou a fazer o trabalho que precisava fazer.

1. Dev é usuário com padrão mental. Inovar na forma da doc é fricção gratuita. Inovar no conteúdo da doc é onde vale a pena.
2. Documentação é interface — e tem métrica. Quando a doc passa a falar a língua do usuário, a adoção do produto segue. 24% são atribuíveis a uma reorganização, não a uma API nova.
3. Schema visível ≠ schema oculto. A diferença entre uma resposta na página e outra em segundo clique é métrica, não preferência estética.
4. Pesquisa é observar, não perguntar. Os devs não articulavam "queremos Swagger". Mas ao olhar como liam outras docs, o padrão ficou óbvio.