Skip to content

Guia BA

Primeira Vez Trabalhando com uma API

Os conceitos de API que um Analista de Negócios realmente precisa entender.

Surya · 8 de agosto de 2026 · 4 min de leitura · 9 práticas

APIs

Para Business Analysts novos em trabalho de integração, BAs escrevendo um requisito relacionado a API pela primeira vez, Product Owners que trabalham de perto com times técnicos e Qualquer um que finge entender "endpoint" e "payload" sem perguntar.

Na primeira vez que alguém junta "endpoint", "payload", "401" e "retry logic" na mesma frase, APIs podem soar bem mais complicadas do que realmente são. Tire tudo isso e uma API é isto: o Sistema A pede algo ao Sistema B, usando um contrato que os dois lados já combinaram. Isso já é o suficiente para começar. Você não precisa construir uma. Você precisa saber o que perguntar quando outra pessoa está construindo uma para o seu requisito.

01

Conceito 01

Uma API é um sistema pedindo algo a outro

Tire o jargão e essa é a ideia inteira.

Não tem mistério nenhum aqui. O sistema pediu: "me dá a operação T12345." O outro sistema devolveu um dado estruturado descrevendo ela. A maior parte do que você vai lidar como BA fica exatamente nesse nível.

O fluxo

Sistema A pedeusando um contrato combinadoSistema B responde

Por que isso ajuda

Assim que essa estrutura parecer comum, o resto do vocabulário é só dar nome às partes de algo que você já entende.

GET /trades/T12345

Resposta:
{
  "tradeId": "T12345",
  "status": "MATCHED",
  "quantity": 1000
}
02

Conceito 02

Endpoint, requisição, resposta — os três únicos substantivos que você realmente precisa

Tudo o mais é detalhe em cima desses três.

Resumo

  • Endpoint — o endereço específico que você está chamando
  • Requisição — o que você envia, incluindo o que você está pedindo
  • Resposta — o que volta e o que isso significa

Por que isso ajuda

Quando uma conversa começa a afundar em siglas, essas três palavras geralmente bastam para trazer ela de volta para algo que você consegue acompanhar.

03

Conceito 03

O método diz que tipo de pedido é esse

GET, POST, PUT/PATCH, DELETE não são curiosidade — eles dizem o que o requisito faz com o dado.

Resumo

  • GET — ler algo, nada muda
  • POST — criar algo novo
  • PUT / PATCH — atualizar algo que já existe
  • DELETE — remover algo

Por que isso ajuda

"Isso lê o dado ou muda ele?" é uma das primeiras perguntas úteis em qualquer discussão de requisito de API, e o método geralmente responde isso em uma palavra.

04

Conceito 04

Códigos de status são o sistema te contando o que aconteceu

Você não precisa decorar todos eles. Você precisa reconhecer a diferença entre alguns.

Resumo

  • 200 — funcionou, aqui está seu dado
  • 201 — criado com sucesso
  • 400 — a própria requisição estava errada
  • 401 — você não está autenticado
  • 403 — você está autenticado, mas não tem permissão
  • 404 — essa coisa não existe
  • 409 — conflita com algo que já existe
  • 500 — o outro sistema quebrou, não você

Por que isso ajuda

Um 401 e um 403 são falhas diferentes com donos diferentes — uma é um problema de login, a outra é uma permissão que alguém decidiu de propósito. Essa distinção muda quem resolve.

05

Conceito 05

Todo campo é obrigatório ou opcional — decida qual, de propósito

Um campo silenciosamente opcional é um requisito que ninguém realmente escreveu.

Resumo

  • Quais campos são obrigatórios para a requisição funcionar?
  • O que acontece se um campo opcional estiver ausente na resposta?
  • O que acontece se um obrigatório estiver ausente — rejeitar, ou chutar?

Por que isso ajuda

"O campo geralmente está lá" não é o mesmo que "o campo é obrigatório." O desenvolvimento vai construir de acordo com o que você realmente escreveu.

06

Conceito 06

Autenticação e autorização são duas perguntas diferentes

"Quem é você?" e "o que você pode fazer?" são constantemente jogados no mesmo saco. Não são a mesma checagem.

Comparação

Autenticação

Prova quem está chamando — um login, um token, uma chave.

Autorização

Decide o que quem está chamando pode fazer, depois de comprovado quem é.

Por que isso ajuda

Quem chama pode estar autenticado e mesmo assim não autorizado — logado corretamente, e ainda sem permissão para ver essa operação específica.

07

Conceito 07

Retries e duplicatas são uma conversa de requisitos, não só técnica

"Só tenta de novo" é uma decisão, mesmo quando ninguém quis que fosse.

A palavra técnica para "seguro de repetir sem efeitos colaterais" é idempotência. Você não precisa da palavra. Você precisa da pergunta: se isso for enviado duas vezes por acidente, alguma coisa ruim acontece duas vezes?

Resumo

  • Essa requisição pode ser reenviada com segurança se der timeout?
  • O que acontece se a mesma requisição exata chegar duas vezes?
  • Um retry poderia criar a mesma operação uma segunda vez?

Por que isso ajuda

Essa é a pergunta que falta na maioria dos requisitos de API — não porque é difícil, mas porque é fácil assumir que a resposta é obviamente sim.

08

Conceito 08

Descubra quem mais depende da resposta antes de ela mudar

Uma resposta de API é uma promessa para todo mundo que já consome ela, não só para você.

Resumo

  • Quem mais chama isso hoje?
  • O que quebra para eles se um campo for renomeado ou removido?
  • Isso é uma versão nova, ou uma mudança quebrando uma já existente?

Por que isso ajuda

"A gente só precisa adicionar um campo" geralmente é seguro. "A gente precisa mudar o que um campo existente significa" geralmente não é — e a diferença importa para pessoas com quem você talvez nunca converse diretamente.

09

Conceito 09

Planeje para o momento em que o outro sistema não responder

Um requisito que só descreve uma API funcionando ainda não descreveu a API.

The shift

O requisito assume que a API sempre responde, instantaneamente e corretamente.
O que acontece se a API estiver indisponível?
O que acontece se der timeout?
O que o usuário vê enquanto espera, e depois que desistimos?

Por que isso ajuda

Essa é a lacuna que vira um relatório de incidente de produção seis meses depois, geralmente começando com "a gente nunca discutiu de verdade o que acontece se..."

Você não precisa construir a API.

Você precisa saber o que perguntar sobre ela.

Todo requisito de API se reduz ao mesmo punhado de perguntas: o que está sendo pedido, o que volta, o que acontece quando falha e quem mais depende dessa resposta continuar igual.

Leve isso com você

Checklist de Requisito de API para BAs

CHECKLIST DE REQUISITO DE API PARA BAS

PROPÓSITO
Para que serve essa API, em uma frase?

CONSUMIDOR
Quem chama essa API?
Quando, e com que frequência?

ENDPOINT
O que está sendo pedido?

MÉTODO
GET, POST, PUT/PATCH, ou DELETE?

CAMPOS DA REQUISIÇÃO
Qual informação é enviada?
Quais campos são obrigatórios?

VALIDAÇÃO
O que torna uma requisição inválida?

RESPOSTA
O que volta?
O que cada campo significa?

CÓDIGOS DE STATUS
Quais códigos são esperados?
O que cada um significa para este requisito específico?

ERROS
Quais respostas de erro são possíveis?
O que o usuário deveria ver em cada caso?

AUTENTICAÇÃO
Como quem está chamando é identificado?

AUTORIZAÇÃO
O que quem está chamando pode fazer, especificamente?

TIMEOUT
O que acontece se a resposta demorar demais?

RETRY
A requisição pode ser reenviada com segurança?

DUPLICATAS
O que acontece se a mesma requisição chegar duas vezes?

CONSUMIDORES DOWNSTREAM
Quem mais depende dessa resposta?

AUDITORIA
Essa chamada precisa ser registrada?

MONITORAMENTO
Como vamos saber se essa API começar a falhar?

VERSIONAMENTO
Isso é uma versão nova, ou uma mudança em uma já existente?

Receba novos guias em primeira mão.