Integração de sistemas
Para quando o mesmo dado é digitado em mais de um sistema e os números não batem entre as áreas.
Serviço
Desenvolvimento de APIs
Projetamos e construímos APIs para que seu sistema seja consumido por aplicativos, parceiros e clientes com segurança, documentação clara e evolução sem quebra de contrato.
O que é desenvolvimento de API
Desenvolvimento de API é o projeto e a construção de uma interface pela qual outros softwares acessam dados e funções de um sistema de forma padronizada. Envolve definir recursos e operações, autenticação, permissões, formato das respostas, limites de uso, versionamento e documentação, para que terceiros consigam integrar sem conhecer o funcionamento interno.
Quando utilizar
Quando sua empresa precisa de uma API própria
- Clientes ou parceiros pedem acesso aos dados do seu sistema e hoje recebem planilhas ou relatórios por e-mail.
- A empresa vai lançar um aplicativo ou um novo front-end e precisa de uma camada de dados única para todos os canais.
- O produto é um SaaS e os clientes exigem API para conectar com as ferramentas deles.
- Outros sistemas acessam diretamente o banco de dados do seu sistema, e qualquer alteração de tabela quebra alguma coisa.
- A API atual cresceu sem padrão, não tem documentação e cada novo integrador depende de suporte da equipe.
- É preciso controlar quem consome o quê, em que volume, e eventualmente cobrar por uso.
Problemas
Problemas que uma API bem projetada resolve
01
Acesso direto ao banco de dados
Quando sistemas externos leem e gravam direto nas tabelas, as regras de negócio são contornadas e qualquer mudança de estrutura vira risco. A API concentra validações e permissões em um único ponto de entrada.
02
Cada integrador exige atendimento manual
Sem documentação e ambiente de testes, toda nova integração começa com reuniões e troca de mensagens com a equipe técnica. Isso atrasa a entrada de parceiros e consome quem deveria estar evoluindo o produto.
03
Mudanças que quebram quem já integra
Alterar o nome de um campo ou o formato de uma resposta sem política de versionamento derruba integrações de clientes em produção. O prejuízo é de confiança: quem integra passa a ver a sua plataforma como instável.
04
Credenciais compartilhadas e sem escopo
Uma única chave com acesso total, repassada entre equipes e fornecedores, impede saber quem fez cada chamada e obriga a trocar tudo quando há vazamento. Credenciais por consumidor, com permissões limitadas, reduzem o alcance de um incidente.
05
Um consumidor derruba todos os outros
Sem limites de uso, um erro de programação de um único cliente, como um laço de chamadas repetidas, pode degradar o serviço para todos. Limitar requisições por consumidor protege a disponibilidade.
06
Lógica duplicada entre site, aplicativo e parceiros
Quando cada canal implementa as próprias regras de preço, estoque ou elegibilidade, os resultados divergem. Uma API única garante que a mesma regra valha para todos os canais.
Benefícios
O que muda com uma API própria
Integração por autoatendimento
Com documentação interativa, exemplos e ambiente de testes, o desenvolvedor do parceiro consegue integrar com pouca ou nenhuma ajuda da sua equipe.
Evolução sem quebra
Uma política de versionamento e de descontinuação permite lançar mudanças enquanto os consumidores antigos continuam funcionando durante o período de transição.
Controle e rastreabilidade de acesso
Cada chamada fica associada a um consumidor identificado, com permissões próprias. É possível revogar um acesso específico sem afetar os demais.
Base para novos canais
Aplicativo, portal do cliente e integrações de parceiros passam a usar a mesma camada, o que reduz o esforço de lançar cada novo canal.
Sistema interno protegido
A API funciona como contrato estável: a estrutura interna do sistema pode ser refatorada sem que os consumidores percebam.
Esse cenário parece com o da sua empresa?
Conte como funciona hoje. A primeira conversa serve para entender o problema.
Processo
Como desenvolvemos uma API
-
01
Levantamento de consumidores e casos de uso
Identificamos quem vai consumir a API, para quê e com qual volume esperado. O resultado é a lista de operações necessárias, priorizada pelo que os consumidores realmente precisam.
-
02
Desenho do contrato antes do código
Especificamos recursos, operações, formatos de requisição e resposta e códigos de erro em um documento de contrato, como uma especificação OpenAPI. Os futuros consumidores podem revisar antes de qualquer implementação.
-
03
Modelo de autenticação e permissões
Definimos como cada consumidor se identifica, quais escopos de acesso existem e como as credenciais são emitidas, renovadas e revogadas.
-
04
Implementação com validação e erros padronizados
Desenvolvemos as operações com validação de entrada, paginação, filtros e mensagens de erro consistentes, que dizem ao integrador o que corrigir.
-
05
Testes automatizados de contrato e de carga
Verificamos que a API responde conforme a especificação e avaliamos o comportamento sob o volume previsto, incluindo a atuação dos limites de uso.
-
06
Documentação e ambiente de testes
Publicamos a documentação de referência, guias de início rápido e um ambiente isolado em que os integradores podem testar sem tocar em dados reais.
-
07
Publicação, monitoramento e política de versões
Colocamos a API em produção com registro de chamadas, métricas de erro e de latência, e formalizamos as regras de versionamento e descontinuação.
Comparativo
REST, GraphQL, webhooks e gRPC
Não existe estilo superior em todos os cenários; a escolha depende de quem consome a API e de como os dados são usados.
| Estilo | Quando faz sentido | Ponto de atenção |
|---|---|---|
| REST | APIs públicas e de parceiros, com recursos bem definidos e necessidade de cache e ampla compatibilidade. | Telas que combinam muitos recursos podem exigir várias chamadas ou operações específicas. |
| GraphQL | Front-ends e aplicativos que precisam montar telas com dados de várias entidades em uma única consulta. | Exige controle de complexidade das consultas; cache e limites de uso são mais trabalhosos. |
| Webhooks | Avisar o consumidor quando algo acontece, evitando que ele consulte a API repetidamente. | É preciso assinar as mensagens, reenviar em caso de falha e documentar que eventos podem chegar repetidos. |
| gRPC | Comunicação interna entre serviços, com alto volume e contratos rígidos. | Pouco prático para consumo direto por navegadores e por integradores externos. |
Quando este serviço não é a melhor escolha
Se a necessidade é conectar sistemas que já possuem APIs, o serviço adequado é integração de sistemas, e não a construção de uma API nova. Também não recomendamos abrir uma API pública enquanto não houver consumidores concretos: projetar para usos hipotéticos costuma gerar operações que ninguém usa e que ainda assim precisam ser mantidas.
Dúvidas
Perguntas frequentes
Qual a diferença entre desenvolver uma API e integrar sistemas?
Desenvolver uma API é criar a porta de entrada do seu próprio sistema, para que outros softwares o acessem. Integrar sistemas é usar APIs que já existem, suas ou de terceiros, para fazer os dados circularem entre eles. Muitos projetos envolvem os dois: construímos a API do sistema principal e depois a usamos nas integrações.
REST ou GraphQL: qual escolher?
REST é a escolha mais segura para APIs consumidas por parceiros externos, pela simplicidade, pelo cache e pela familiaridade dos desenvolvedores. GraphQL tende a compensar quando o principal consumidor é um front-end ou aplicativo com telas ricas, que precisa escolher os campos de cada consulta. É possível oferecer os dois sobre a mesma base de regras.
Como funciona a autenticação de uma API?
Os modelos mais comuns são chaves de API, para comunicação entre servidores, e OAuth 2.0, quando um usuário autoriza um aplicativo a agir em nome dele. Em ambos, cada consumidor recebe credenciais próprias, com escopos que limitam o que pode ser acessado. A escolha depende de quem consome a API e da sensibilidade dos dados.
O que é versionamento de API e por que ele importa?
Versionamento é a regra que define como a API muda sem quebrar quem já integra. Mudanças compatíveis, como adicionar um campo, entram na versão atual; mudanças incompatíveis geram uma nova versão, e a anterior permanece ativa por um período anunciado. Sem essa regra, cada melhoria vira risco para os clientes.
Para que servem os limites de uso (rate limit)?
Os limites de uso definem quantas requisições cada consumidor pode fazer em um intervalo de tempo. Eles protegem a disponibilidade do serviço contra erros de programação e abusos, e permitem diferenciar planos de acesso. A API deve informar o limite e o consumo na própria resposta, para que o integrador se ajuste.
Que documentação é entregue com a API?
A base é a referência gerada a partir da especificação do contrato, com todas as operações, parâmetros, exemplos e erros possíveis. Complementamos com guias de autenticação e de primeiros passos e com o registro de mudanças entre versões. Documentação derivada do contrato tem menos chance de ficar desatualizada em relação ao código.
O que determina o custo de desenvolver uma API?
Os principais fatores são a quantidade de operações, a complexidade das regras por trás delas, o modelo de autenticação, os requisitos de volume e disponibilidade e o nível de documentação e de ambiente de testes. Expor dados de um sistema já bem estruturado é mais simples do que construir a API sobre um legado sem separação entre regras e telas.
Relacionados
Serviços relacionados
SaaS
Para transformar conhecimento de um setor em produto por assinatura, começando por um MVP.
Conteúdo
Conteúdo relacionado
APIs e integrações
8 min de leitura
O que é uma API?
API é o contrato que permite a um software pedir dados ou ações a outro. Veja como funciona, quais são os tipos e onde ela aparece na rotina de uma empresa.
Sobre a Teraserv
A Teraserv Digital é uma empresa brasileira de tecnologia que, desde 2010, desenvolve software, sistemas web, integrações e soluções digitais sob medida para empresas.
Conheça a empresaSeu próximo sistema pode começar com uma conversa.
Conte o problema que você quer resolver. Analisamos o cenário e retornamos com os próximos passos.