APIs, integração de sistemas e arquitetura de soluções digitais para o Banco do Brasil – Agente de Tecnologia

Fundamentos de APIs REST em soluções digitais

Uma API (Application Programming Interface) é um “contrato” que permite que sistemas conversem de forma padronizada. Em soluções digitais bancárias, APIs são usadas para expor funcionalidades (consultar saldo, listar transações, iniciar pagamentos) com controle de acesso, rastreabilidade e previsibilidade de comportamento.

No estilo REST (Representational State Transfer), a API organiza o acesso a recursos (entities do domínio) por meio de URLs e usa métodos HTTP para indicar a ação. O foco é manipular representações do recurso (geralmente JSON) e manter a comunicação stateless (cada requisição carrega o necessário para ser processada).

Recursos e URIs (endereços)

Um recurso é algo identificável: clientes, contas, transacoes, cartoes. Boas práticas comuns:

• Use substantivos no plural: /clientes, /contas.
• Use identificadores na rota: /clientes/{id}.
• Evite verbos na URL (o verbo é o método HTTP): prefira POST /pagamentos em vez de /criarPagamento.
• Padronize filtros e paginação via query string: ?status=ATIVO&page=1&size=20.

Métodos HTTP e semântica

• GET: consulta (não deve alterar estado). Ex.: GET /contas/123/saldo.
• POST: cria ou inicia processamento. Ex.: POST /pagamentos.
• PUT: substitui o recurso por completo (idempotente). Ex.: PUT /clientes/10.
• PATCH: atualização parcial. Ex.: PATCH /clientes/10.
• DELETE: remove (ou marca como removido). Ex.: DELETE /beneficiarios/55.

Idempotência é central em integrações bancárias: uma operação idempotente pode ser repetida sem efeitos colaterais adicionais. Em cenários com retry (reenvio), isso evita duplicidades.

Códigos de status HTTP: interpretação e uso correto

O status HTTP comunica o resultado de forma padronizada. Em prova e na prática, é comum avaliar se o status condiz com a operação.

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

Principais códigos

• 200 OK: sucesso com resposta (ex.: GET com corpo).
• 201 Created: recurso criado (ex.: POST criando pagamento). Idealmente retorna Location com a URL do novo recurso.
• 202 Accepted: requisição aceita para processamento assíncrono (útil quando há fila/evento).
• 204 No Content: sucesso sem corpo (ex.: DELETE bem-sucedido).
• 400 Bad Request: erro de validação/formato (campos faltando, tipo inválido).
• 401 Unauthorized: falta autenticação (token ausente/expirado).
• 403 Forbidden: autenticado, mas sem permissão (escopo/role insuficiente).
• 404 Not Found: recurso não existe (ou não visível ao chamador).
• 409 Conflict: conflito de estado (ex.: tentativa de criar algo duplicado, ou versão desatualizada).
• 422 Unprocessable Entity: dados semanticamente inválidos (varia por padrão adotado).
• 429 Too Many Requests: limite de requisições excedido (rate limit).
• 500 Internal Server Error: falha inesperada no servidor.
• 503 Service Unavailable: indisponibilidade temporária (manutenção, sobrecarga).

Exemplo prático: criação de pagamento

Requisição:

POST /v1/pagamentos HTTP/1.1
Host: api.exemplo.bb
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: 7b1b2b2a-2c2a-4d5a-9f1d-1c2d3e4f5a6b

{
  "contaDebitoId": "123",
  "favorecidoId": "789",
  "valor": 150.75,
  "moeda": "BRL",
  "descricao": "Pagamento de serviço"
}

Resposta (criado):

HTTP/1.1 201 Created
Location: /v1/pagamentos/9981
Content-Type: application/json

{
  "pagamentoId": "9981",
  "status": "CRIADO",
  "criadoEm": "2026-01-15T10:20:30Z"
}

Resposta (validação):

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "erro": "VALIDACAO",
  "mensagem": "Campo 'valor' deve ser maior que zero",
  "campos": [
    {"campo": "valor", "problema": "minimo"}
  ]
}

Versionamento de APIs

Versionar é essencial para evoluir a API sem quebrar integrações. Em ambiente bancário, mudanças precisam ser previsíveis, com janela de migração e compatibilidade.

Estratégias comuns

• Versão na URL: /v1/contas, /v2/contas. Simples de operar e documentar.
• Versão por header: ex.: Accept: application/vnd.bb.contas.v1+json. Útil para granularidade, mas aumenta complexidade.

Boas práticas

• Evite mudanças “breaking” na mesma versão (remover campos, mudar significado).
• Adicione campos de forma compatível (consumidores devem ignorar campos desconhecidos).
• Planeje descontinuação com prazo e monitoramento de uso.

Autenticação e autorização em APIs

Autenticação responde “quem é você?”. Autorização responde “o que você pode fazer?”. Em integrações bancárias, é comum separar claramente esses conceitos e aplicar o princípio do menor privilégio.

Padrões e mecanismos frequentes

• Bearer Token (ex.: tokens JWT ou opacos): enviado no header Authorization: Bearer ....
• OAuth 2.0 (conceitual): define fluxos para obter tokens e escopos (permissões). Ex.: escopo pagamentos:criar.
• mTLS (mutual TLS): autentica também o cliente via certificado, comum em integrações sistema-a-sistema.
• API Key: simples, mas geralmente insuficiente sozinha para cenários sensíveis; costuma ser combinada com outros controles.

Exemplo: autorização por escopo

Se um cliente tem token válido, mas sem escopo para criar pagamento, a API deve responder 403:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "erro": "ACESSO_NEGADO",
  "mensagem": "Escopo insuficiente: requer pagamentos:criar"
}

Passo a passo prático: como “ler” uma chamada autenticada

• 1) Verifique se há Authorization e se o formato é esperado (Bearer, certificado, etc.).
• 2) Confirme se o token está válido (expiração) e se pertence ao cliente correto (audience/issuer, quando aplicável).
• 3) Cheque autorização: escopos/roles e regras de negócio (ex.: conta pertence ao cliente?).
• 4) Garanta rastreabilidade: inclua/propague um Correlation-Id para logs e auditoria.

Contratos de API e OpenAPI (nível conceitual)

O contrato define como consumir a API: endpoints, parâmetros, formatos de request/response, autenticação, erros e exemplos. Um contrato bem definido reduz ambiguidades e falhas de integração.

OpenAPI é uma especificação para descrever APIs REST de forma padronizada (normalmente em YAML/JSON). Conceitualmente, ela documenta:

• Rotas e métodos (ex.: POST /pagamentos).
• Parâmetros (path, query, header) e validações.
• Esquemas de dados (campos, tipos, obrigatoriedade).
• Códigos de status e modelos de erro.
• Requisitos de segurança (ex.: OAuth2, Bearer).

Em integrações críticas, o contrato serve como referência para testes, validação e governança (mudanças devem ser controladas).

Integração síncrona vs assíncrona

Integração síncrona (request/response) é direta: um sistema chama o outro e espera a resposta. Integração assíncrona usa filas/eventos: o produtor envia uma mensagem e o consumidor processa depois, desacoplando disponibilidade e tempo de resposta.

Quando usar síncrono

• Consultas imediatas (ex.: obter saldo, listar transações).
• Operações que precisam de resposta imediata ao usuário (com cuidado para latência).

Quando usar assíncrono (filas/eventos)

• Processos demorados (ex.: conciliações, enriquecimento de dados, antifraude com múltiplas etapas).
• Necessidade de absorver picos (buffer de mensagens).
• Maior resiliência a indisponibilidade temporária do consumidor.

Conceitos essenciais em filas/eventos

• Producer: publica mensagem/evento.
• Broker: infraestrutura de mensageria (fila/tópico).
• Consumer: processa mensagens.
• At-least-once: entrega pode ocorrer mais de uma vez; exige idempotência no consumidor.
• Dead Letter Queue (DLQ): mensagens que falharam repetidamente vão para análise/reprocessamento.

Exemplo conceitual de evento

Após criar um pagamento, o sistema publica um evento para outros domínios (notificação, conciliação, antifraude):

{
  "eventId": "e-12345",
  "type": "PagamentoCriado",
  "occurredAt": "2026-01-15T10:20:31Z",
  "data": {
    "pagamentoId": "9981",
    "contaDebitoId": "123",
    "valor": 150.75,
    "moeda": "BRL"
  }
}

Note que o evento carrega dados suficientes para os consumidores, mas deve evitar excesso de informação sensível. Em ambiente bancário, minimização de dados e classificação da informação são práticas importantes.

Padrões de arquitetura: camadas e microserviços (nível conceitual)

Arquitetura em camadas

Organiza responsabilidades em níveis (ex.: apresentação, aplicação/serviço, domínio, dados/integração). Benefícios:

• Separação de responsabilidades e manutenção mais previsível.
• Testabilidade e padronização.

Risco comum: camadas muito acopladas ou “anêmicas” (regras espalhadas), o que dificulta evolução.

Microserviços (conceitual)

Divide o sistema em serviços menores, cada um com responsabilidade clara e comunicação via APIs/eventos. Benefícios:

• Escalabilidade por componente (escala o que mais demanda).
• Implantação independente (quando bem governado).

Custos/complexidades:

• Mais chamadas remotas (latência e falhas parciais).
• Observabilidade e rastreamento distribuído se tornam obrigatórios.
• Consistência de dados entre serviços pode exigir padrões como sagas/compensações (conceitual).

Desempenho e confiabilidade em integrações

Impactos de desempenho

• Latência: cada chamada remota adiciona tempo; encadeamentos longos degradam UX e aumentam timeout.
• Payload: respostas grandes aumentam tempo de rede e processamento; prefira paginação e campos necessários.
• Cache: para dados de leitura frequente e baixa volatilidade (com cuidado para consistência).

Impactos de confiabilidade

• Timeouts: devem ser definidos; sem timeout, o chamador pode ficar preso e esgotar recursos.
• Retries: reenvio em falhas transitórias; deve ser limitado e com backoff para não amplificar incidentes.
• Circuit breaker (conceitual): interrompe chamadas a um serviço instável para proteger o sistema.
• Idempotência: essencial para POST/ações financeiras quando há retry.
• Rate limiting: protege a API de abuso e picos; pode retornar 429.

Passo a passo prático: checklist de uma integração robusta

• 1) Defina timeouts (conexão e resposta) e limites de tamanho de payload.
• 2) Planeje retries apenas para erros transitórios (ex.: 503) e use backoff.
• 3) Garanta idempotência em operações críticas (Idempotency-Key ou lógica por identificador de negócio).
• 4) Padronize erros (código interno, mensagem, detalhes por campo) sem vazar dados sensíveis.
• 5) Propague Correlation-Id para rastrear ponta a ponta.
• 6) Monitore SLIs (latência, taxa de erro, saturação) e estabeleça limites operacionais.

Exercícios de interpretação de endpoints (estilo concurso)

Exercício 1: identificar recurso, ação e idempotência

Considere o endpoint: POST /v1/contas/123/bloqueios com corpo {"motivo":"SUSPEITA_FRAUDE"}.

• a) Qual é o recurso principal?
• b) O método HTTP indica criação de quê?
• c) Se houver retry por timeout, qual risco existe? Como mitigar?

Exercício 2: status code correto

Uma API recebe GET /v1/clientes/999 e o cliente não existe. Qual status é mais adequado: 400, 404 ou 409? Justifique.

Exercício 3: autenticação vs autorização

Uma requisição chega com token válido, mas sem permissão para acessar GET /v1/contas/123/extrato. Qual status deve ser retornado: 401 ou 403? Explique a diferença.

Exercício 4: versionamento e compatibilidade

Na resposta de GET /v1/contas/123, a API adicionou o campo "apelido". Isso quebra consumidores? Em que situação poderia quebrar?

Questões sobre boas práticas de integração em ambientes bancários

Questão 1

Em uma operação de criação de pagamento via POST, qual prática reduz o risco de duplicidade quando o cliente reenvia a requisição por instabilidade de rede?

• A) Retornar sempre 200
• B) Usar Idempotency-Key e garantir idempotência no servidor
• C) Aumentar o payload de resposta
• D) Remover validações para reduzir latência

Questão 2

Qual alternativa melhor descreve o uso de 202 Accepted?

• A) Requisição inválida
• B) Requisição autenticada, mas proibida
• C) Requisição aceita para processamento posterior (assíncrono)
• D) Recurso não encontrado

Questão 3

Um consumidor de fila pode receber a mesma mensagem mais de uma vez. Qual propriedade o processamento deve ter para manter consistência?

• A) Ser não determinístico
• B) Ser idempotente
• C) Ser sempre síncrono
• D) Ser sem autenticação

Questão 4

Qual combinação tende a aumentar confiabilidade em chamadas entre serviços?

• A) Sem timeout + retries ilimitados
• B) Timeout definido + retries com backoff + circuit breaker (conceitual)
• C) Payloads maiores + sem paginação
• D) Remover rate limiting

Questão 5

Sobre contratos de API, assinale a alternativa mais adequada:

• A) Contrato é opcional; basta o código funcionar
• B) Contrato descreve endpoints, dados, erros e segurança, reduzindo ambiguidades de integração
• C) Contrato serve apenas para front-end
• D) Contrato impede versionamento