Contexto
A Qive ingere e estrutura documentos fiscais para empresas. A plataforma é consumida programaticamente (por ERPs, softwares de contabilidade e sistemas parceiros), então a API é uma superfície de produto, não um detalhe interno. Integradores precisam de um lugar que responda a três perguntas: o que eu posso chamar, como eu me autentico e se isso realmente funciona.
Problema
- Sem documentação executável, a pergunta "esse endpoint funciona mesmo?" é respondida tarde, depois que o integrador já escreveu código.
- Autenticação e tratamento de erro são onde as integrações quebram primeiro, e onde uma referência só de texto ajuda menos.
- Toda pergunta não respondida vira um chamado de suporte em vez de uma resposta autosserviço.
Minha responsabilidade
Construí o portal de desenvolvedores: a interface de documentação e o playground interativo de API.
O que está publicado
- Um portal público em developers.qive.com.br, em português, voltado a integradores brasileiros.
- Uma área de documentação em
/docs. - Um playground interativo que executa chamadas de API pelo navegador e mostra a resposta: a parte que transforma uma referência em algo em que o integrador confia.
- Configuração de ambiente injetada na página (
window.__ENV), para endpoints de tracking e de ambiente não ficarem embutidos no bundle em tempo de build.
Como foi construído
- Next.js (App Router) com build em Turbopack: um shell renderizado no servidor mais uma aplicação no cliente.
- Configuração de ambiente injetada em tempo de execução em vez de compilada no bundle, então o mesmo artefato roda contra ambientes diferentes.
Resultado
Um portal público em produção que documenta a API e permite ao integrador testar antes de assumir uma implementação, transformando uma pergunta recorrente de suporte em resposta autosserviço. O impacto está na experiência de integração: as primeiras perguntas são respondidas antes de alguém abrir um chamado.
O que aprendi
- Playground é decisão de produto, não recurso de documentação: ele move a pergunta "funciona mesmo?" para o momento mais barato possível.
- Documentação que roda também é um teste da API: se uma requisição falha no playground, o integrador descobre antes de escrever qualquer código.
- Produtos para desenvolvedores têm regras próprias de UX: o integrador quer a requisição, a resposta e o erro, rápido, sem um muro de cadastro no caminho.