Como criar uma API para parceiros e clientes integrarem

Em algum momento, um distribuidor, um cliente grande ou um parceiro de tecnologia faz a pergunta: "vocês têm API?". Hoje os pedidos chegam por planilha no e-mail, o status é consultado por telefone e alguém da sua equipe passa a tarde digitando o que o parceiro já tinha digitado do lado de lá.

A resposta apressada costuma ser pegar um endpoint que o próprio sistema já usa, gerar um token e mandar para o parceiro. Funciona com o primeiro. No terceiro, a sua equipe vira suporte técnico de três empresas e qualquer mudança interna quebra a integração de alguém.

Este texto trata a API pública pelo que ela é: um produto com usuários externos, e não uma porta aberta no sistema.

Quando abrir uma API faz sentido (e quando não faz)

Faz sentido quando a troca de dados com terceiros é recorrente e tem volume. Parceiros que enviam pedidos todo dia, clientes que consultam estoque ou status de entrega, revendas que puxam catálogo. Se o parceiro é canal de venda, a API vira vantagem comercial: é mais fácil trabalhar com quem integra.

Faz sentido quando o outro lado tem equipe técnica. API é para sistema conversar com sistema. Se o parceiro não tem ninguém para escrever a integração, ela não vai acontecer.

Não faz sentido, ainda, quando:

• São dois ou três parceiros com volume baixo. Uma troca de arquivos agendada, com layout definido, resolve com menos esforço.
• Os parceiros não têm TI. Eles precisam de uma tela, não de uma API. Um portal do cliente B2B com pedidos, boletos e segunda via atende melhor.
• Os dados internos estão desorganizados. A API expõe a bagunça para fora, e ela volta como chamado para você.

API pública é produto, não um endpoint a mais

A diferença entre uma API interna e uma pública é quem controla o outro lado. Na interna, a mesma equipe muda o servidor e o cliente no mesmo deploy. Na pública, o código do parceiro já está em produção e você não pode alterá-lo. Cada campo publicado vira uma promessa.

Por isso, uma API para terceiros costuma ter componentes que a interna nunca precisou:

E todo produto precisa de um dono: alguém que decide o que entra na próxima versão, responde pela política de depreciação e acompanha os indicadores. API sem dono envelhece mal.

Desenho do contrato: recursos, erros e paginação

Modele a API em termos do negócio do parceiro, não das suas tabelas. O parceiro quer "pedido", "item", "status de entrega". Não quer flg_sit_2 nem o ID sequencial do seu banco. A camada de API funciona como uma fachada: por trás dela pode estar um ERP, um sistema novo ou um antigo. Se for um sistema sem interface de integração, o texto sobre como integrar um sistema legado que não tem API mostra como alimentar essa fachada.

Algumas decisões de contrato evitam muita dor depois:

• Consistência de nomes e formatos. Datas em ISO 8601 com fuso horário, valores monetários sem ponto flutuante (decimal como texto ou inteiro em centavos), identificadores estáveis que nunca são reaproveitados.
• Erros que dizem o que fazer. Use os códigos HTTP corretamente: 4xx quando o problema está na requisição do parceiro (não adianta tentar de novo sem corrigir), 5xx quando o problema é seu (tentar de novo pode resolver), 429 quando o limite estourou. No corpo, um formato padronizado com um código legível por máquina, uma mensagem para humanos e o campo afetado. O RFC 9457 (Problem Details for HTTP APIs) é uma boa referência para esse formato.
• Paginação por cursor. Em listas que mudam durante a leitura, paginação por número de página pula ou repete registros. O cursor evita isso.
• Consulta incremental. Um filtro "alterados desde" é o que o parceiro precisa para sincronizar sem baixar tudo de novo a cada rodada.
• Idempotência nas escritas. O parceiro envia uma chave única ao criar o pedido. Se a rede cair e ele reenviar, nada é duplicado.

Comece pequeno. Dois ou três recursos bem desenhados valem mais que trinta endpoints. Adicionar depois é fácil; remover é caro.

Versionamento sem quebrar quem já integrou

A regra é simples de enunciar: mudanças compatíveis entram na versão atual; mudanças incompatíveis exigem uma versão nova. O difícil é saber o que é compatível.

Na prática, funciona assim:

• Versão na URL (/v1/, /v2/) é o modelo mais simples de entender e depurar. Versão em cabeçalho também funciona. Escolha um e mantenha.
• Política de depreciação por escrito: quanto tempo de aviso antes de desligar uma versão, quanto tempo as duas convivem e como o parceiro é avisado.
• Saiba quem usa o quê. Com credencial por parceiro, você enxerga quem ainda chama a versão antiga e fala com essas empresas antes de desligar.
• Contrato como fonte da verdade. Uma especificação OpenAPI versionada junto com o código, com testes que falham quando uma alteração quebra o contrato publicado. Isso tira a decisão do "acho que não quebra nada".

Oriente os parceiros a ignorar campos desconhecidos e tolerar valores novos. Isso amplia o que você pode evoluir sem versão nova.

Autenticação e credenciais por parceiro

Cada parceiro tem a própria credencial. Nunca um token compartilhado, nunca o login de um funcionário. Assim dá para revogar um parceiro sem afetar os outros, aplicar limites individuais e saber quem fez cada operação.

As opções mais comuns, do mais simples ao mais rigoroso:

• Chave de API. Simples para integração entre servidores. Exige HTTPS, armazenamento como hash do seu lado e exibição do segredo uma única vez.
• OAuth 2.0 com client credentials. O parceiro troca suas credenciais por um token de curta duração, com escopos. Um token vazado expira sozinho.
• TLS mútuo com certificados. Os dois lados se autenticam por certificado. É comum em integrações financeiras; ecossistemas regulados como o Open Finance Brasil usam certificados digitais e TLS mútuo entre participantes.

Independentemente do mecanismo:

• Escopos de menor privilégio. O parceiro que só consulta status não precisa criar pedidos.
• Rotação sem parada. Permita duas credenciais ativas ao mesmo tempo, para o parceiro trocar a chave sem interromper a integração.
• Autorização por objeto. Autenticar não basta: cada requisição precisa verificar se aquele pedido pertence àquele parceiro. Trocar um ID na URL e ver dados de outra empresa é uma das falhas mais frequentes, detalhada no texto sobre os erros mais comuns de segurança em APIs. Se a API faz parte de uma plataforma com vários clientes, o isolamento vem da arquitetura, como mostramos em SaaS multi-tenant e isolamento de dados.

Se a API expõe dados pessoais, a LGPD (Lei 13.709/2018) entra no desenho: o compartilhamento precisa de base legal, o contrato com o parceiro deve definir responsabilidades e o princípio da necessidade vale aqui também. Exponha só o que o caso de uso exige.

Limites de uso e proteção contra abuso

Limite de uso não é desconfiança. É proteção contra o bug do parceiro: um laço infinito, uma sincronização que baixa o catálogo inteiro a cada minuto. Sem limite, esse bug vira lentidão na tela da sua equipe comercial.

O que costuma funcionar:

• Limite por credencial, não por IP. Vários parceiros podem sair pelo mesmo IP, e um parceiro pode sair por vários.
• Resposta clara ao estourar. Código 429 com o cabeçalho Retry-After e cabeçalhos informando quanto da cota resta. O parceiro ajusta o ritmo sem abrir chamado.
• Limites diferentes por tipo de operação. Consulta de status é leve; exportação de histórico é pesada. Tratar tudo igual sufoca o uso legítimo ou libera o abusivo.
• Proteção do sistema interno. Tamanho máximo de requisição e de página, tempo limite nas consultas, cache para leituras e fila para escritas, para que um pico da API não chegue direto ao ERP.

Ambiente de testes e documentação que se explica

Sandbox é obrigatório. Um ambiente separado, com o mesmo contrato da produção, credenciais próprias e dados fictícios, onde o parceiro cria pedidos sem faturar nada e simula cenários como pedido recusado ou item sem estoque. E nunca com dados pessoais reais.

A documentação decide se o parceiro integra sozinho ou liga para você. O mínimo:

• Guia de início que leva da criação da credencial à primeira chamada bem-sucedida.
• Referência gerada a partir da especificação OpenAPI, para nunca divergir do comportamento real.
• Exemplos reais de requisição e resposta, inclusive de erro, e um catálogo de erros com o que fazer em cada caso.
• Guias por caso de uso: "como enviar um pedido", "como receber atualizações de status".
• Changelog, política de versões e limites, em lugar visível.

Trate cada dúvida de suporte como um defeito da documentação. E padronize a entrada: cadastro, credencial de sandbox, roteiro de homologação com os cenários obrigatórios e só então a credencial de produção.

Webhooks para avisar o parceiro em vez de ele perguntar

Sem webhooks, o parceiro descobre mudanças perguntando "o pedido já faturou?" a cada poucos minutos, para cada pedido. Desperdício dos dois lados, com informação atrasada. Com webhooks, você chama o endereço do parceiro quando o evento acontece: pedido aprovado, nota fiscal emitida, entrega realizada.

Webhook bem feito tem alguns cuidados:

• Assinatura da mensagem (por exemplo, HMAC com um segredo por parceiro), para ele confirmar que a chamada veio de você.
• Retentativa com espera crescente quando o endereço do parceiro está fora do ar.
• Entrega "pelo menos uma vez". O mesmo evento pode chegar duas vezes, então cada evento leva um identificador único para o parceiro descartar duplicadas.
• Ordem não garantida. Inclua data e versão do recurso no evento, para o parceiro não sobrescrever um estado novo com um antigo.
• Painel de entregas, com histórico, motivo das falhas e reenvio manual.
• Desativação com aviso após falhas repetidas, em vez de insistir para sempre.

Mantenha a consulta incremental ("alterados desde") como rede de segurança. Se um webhook se perder, o parceiro reconcilia sem depender de você.

O que costuma dar errado quando é feito às pressas

• Expor a API interna do próprio sistema. Ela foi feita para o seu front-end e muda junto com ele.
• Token único para todos os parceiros. Um vazamento obriga a trocar a credencial de todo mundo.
• "Depois a gente versiona." A primeira mudança incompatível vira negociação com cada parceiro.
• Documentação em PDF enviada por e-mail, desatualizada na semana seguinte.
• Erros genéricos, como "erro interno" para dado inválido, que viram chamado.
• Sem logs por parceiro. Quando ele diz que enviou e não chegou, ninguém consegue verificar.

Como medir se a API está cumprindo o papel

• Tempo do cadastro até a primeira chamada bem-sucedida no sandbox, e até a produção.
• Chamados de suporte por parceiro integrado, que devem cair conforme a documentação amadurece.
• Taxa de erros 4xx por parceiro, que aponta confusão no contrato, separada dos 5xx, que são problema seu.
• Disponibilidade, latência e webhooks entregues na primeira tentativa.
• Parceiros ainda em versões depreciadas.
• Volume que migrou do canal manual (planilha, e-mail, telefone) para a API.

Passo a passo para abrir a sua API

1. Liste parceiros e casos de uso concretos: o que cada um precisa fazer e com que frequência.
2. Desenhe o menor contrato que resolve esses casos e escreva a especificação antes de programar.
3. Valide o contrato com um parceiro piloto, ainda no papel.
4. Defina por escrito autenticação, escopos, limites e política de versões.
5. Construa a camada de API como fachada sobre os sistemas internos, com logs por parceiro.
6. Publique sandbox e documentação junto com a primeira versão, não depois.
7. Homologue com o piloto e transforme cada dúvida em documentação.
8. Abra para os demais parceiros com entrada padronizada e acompanhe os indicadores.

Do contrato ao primeiro parceiro em produção

Na Pervian Tech, começamos por um diagnóstico: quem são os parceiros, o que eles precisam fazer e de onde saem os dados hoje. A partir disso desenhamos o contrato e o validamos com um parceiro piloto antes de construir, e seguimos por fases (diagnóstico, protótipo do contrato, primeira versão em produção com o piloto, evolução). O cronograma é definido depois do diagnóstico.

Cada API é construída sob medida para os sistemas que você já usa, e o investimento é definido sob consulta, depois de entender o contexto. Esse trabalho faz parte da nossa atuação em arquitetura de software. Se os seus parceiros já estão pedindo uma API, conte o cenário para a gente.