Developer Portal

Visão geral

• Problema: desenvolvedores enfrentavam dificuldades na integração com as APIs da empresa devido a uma documentação dispersa e pouco intuitiva.

• Objetivo: criar um Developer Portal centralizado que oferecesse uma experiência clara, reduzisse o tempo de integração e melhorasse a adoção das APIs.

• Impacto esperado: agilizar processos de integração, reduzir tickets de suporte e aumentar a adoção das APIs.

Nota sobre NDA: Algumas métricas e informações sensíveis foram alteradas ou omitidas para respeitar acordos de confidencialidade.

✱

O problema

A empresa oferecia diversas APIs para clientes e parceiros, mas o processo de integração era um grande obstáculo. Desenvolvedores relatavam que:

• A documentação estava espalhada e sem um fluxo lógico.

• Faltava clareza nas informações, resultando em dúvidas frequentes.

• O suporte técnico recebia muitos tickets sobre questões básicas que poderiam ser evitadas com uma documentação melhor.

Hipótese: se criássemos um Developer Portal intuitivo e bem documentado, conseguiríamos reduzir a fricção na integração e melhorar a experiência dos desenvolvedores.

✱

Pesquisa e descoberta

Realizamos uma pesquisa qualitativa e quantitativa:

• Entrevistas com desenvolvedores: identificamos principais pontos de dor na navegação e compreensão da documentação.

• Análise de tickets de suporte: descobrimos que a maioria das dúvidas se concentrava em autenticação e chamadas de API.

• Benchmarking com Developer Portals de referência: estudamos boas práticas de empresas líderes no setor.

Principais insights:

• 60% dos desenvolvedores entrevistados relataram dificuldades em encontrar informações sobre autenticação.

• APIs mais complexas tinham menos adoção devido à falta de exemplos práticos.

• Desenvolvedores preferem documentação estruturada com código copiável e playground interativo.

Ideação e solução

Navegação intuitiva e hierarquizada:

• Criamos um menu lateral estruturado para facilitar a busca de informações.

• Melhoramos a arquitetura da informação, agrupando APIs por contexto de uso.

Documentação interativa e com exemplos práticos:

• Adicionamos código copiável e exemplos reais para cada API.

• Criamos uma sandbox interativa para que os desenvolvedores pudessem testar chamadas sem sair da plataforma.

Design e prototipagem

UI Guidelines:

• Tipografias monoespaçadas para facilitar a leitura de código.

• Destaque visual para exemplos práticos, separando teoria e prática.

Testes de usabilidade:

• Rodamos testes com desenvolvedores internos e coletamos feedbacks sobre clareza e navegabilidade.

• Iteramos o design com pequenas melhorias baseadas nas dificuldades apontadas.

✱

Resultado e impacto

Após o lançamento, observamos um impacto significativo na experiência dos desenvolvedores:

• A navegação no portal ficou mais fluida, facilitando a busca por APIs específicas.

• A integração das APIs se tornou mais intuitiva, reduzindo a necessidade de suporte técnico.

• Desenvolvedores relataram uma curva de aprendizado menor, acelerando o tempo de implementação.

Aprendizados:

• O uso de sandbox interativa foi um diferencial positivo e deve ser expandido no futuro.

• Testes com desenvolvedores desde o início foram cruciais para garantir um produto realmente útil.

• Documentação clara e estruturada reduz custos operacionais com suporte técnico.

✱

Manager

O Manager do Developer Portal na plataforma Sensedia centraliza a gestão do portal, permitindo integração com gateways, organização de APIs e APPs, controle de usuários e personalização da interface. Através dele, é possível:

01. Gateways

Permite integrar gateways de outras plataformas à Sensedia, além de importar APIs e APPs já existentes nesses ambientes.

02. Catalog

Gerencia a documentação técnica das APIs. Durante a importação de uma API, a documentação é carregada automaticamente, mas também pode ser adicionada manualmente. O catálogo possibilita edição, visualização e exclusão de conteúdos conforme necessário.

03. Products

Estrutura a documentação das APIs, organizando-as de acordo com as funcionalidades de cada produto, facilitando a navegação e a consulta.

04. Portal

Aqui, é possível definir o conteúdo, aparência e configurações adicionais do Developer Portal. A personalização inclui:

• Identidade visual: upload de logotipos e imagens que compõem a identidade do portal.

• Templates: escolha do modelo ideal para a interface.

• Fontes: definição de tipografia para títulos e textos.

• Cores de fundo: configuração das cores do cabeçalho, corpo e rodapé.

• Cores de botões: ajuste da paleta utilizada nos botões interativos.

05. Guides

Funciona como uma plataforma de documentação aberta, permitindo a criação e disponibilização pública de guias, referências técnicas e outros materiais relevantes para os usuários e parceiros.

06. Developers

Abrange todos os usuários que consomem conteúdo no portal, como desenvolvedores, apps e grupos. Aqui, é possível:

• Gerenciar convites para novos usuários.

• Administrar desenvolvedores registrados e seus acessos.

Portal

O Portal é o ambiente onde todas as informações estruturadas no Gerenciador são disponibilizadas para os usuários. Ele exibe a configuração visual aplicada e permite o acesso às APIs e APPs cadastrados, fornecendo instruções detalhadas sobre seu uso.

01. Homepage

A página inicial do portal serve como ponto de entrada, direcionando os usuários para áreas como catálogo, guias e aplicativos disponíveis.

02. Login / Cadastro / Recuperação de Senha

Tela desenvolvida para garantir uma experiência intuitiva e segura no acesso à plataforma, facilitando a autenticação e a gestão de credenciais.

03. Catálogo

Exibe as APIs e APPs disponíveis, permitindo filtragem por nome ou grupos específicos. Além disso, oferece acesso à documentação detalhada e a ferramentas para testar as funcionalidades das APIs.

04. APPs

Permite visualizar, editar e criar novos APPs, além de consultar APIs associadas e seus respectivos tokens de autenticação.

Conclusão

Este projeto foi mais do que um redesign de documentação, foi a criação de uma plataforma completa para facilitar a integração de APIs.

Principais aprendizados:

• UX para desenvolvedores precisa ser direto, claro e acessível.

• Arquitetura de informação bem estruturada reduz dúvidas e aumenta adoção.

• A colaboração entre design, produto e desenvolvimento é essencial para um resultado eficiente.

Próximos passos:

• Monitorar métricas de adoção e continuar refinando a experiência.

• Expandir a sandbox interativa com novos exemplos e guias avançados.

✱