Início do Bloco D (APIs e integrações). Foco: você lê documentação de API do cliente e identifica oportunidades de integração pro Team Studio, sabe defender escolhas (REST vs GraphQL) sem cair em dogma, e configura webhooks que não perdem evento.

Pré-requisito: Semana 1 (SQL) ajuda mas não é obrigatória. Tempo estimado: 3-4 horas de leitura + 1 hora de exercício. Output prático: você lê documentação API do cliente em 10 min e propõe pelo menos 2 pontos de integração relevantes pro Team Studio.

Por que essa semana importa

API é como sistemas modernos se comunicam. Sem entender REST/GraphQL/webhooks, você não consegue: - Propor integração realista do Team Studio com sistema do cliente - Avaliar se API do cliente é boa ou se vai dar trabalho - Garantir que agentes Team Studio não perdem eventos - Negociar SLA realista quando integração é parte do entregue

Cliente que diz:

"Nossa API é REST, documentada em OpenAPI 3.1, tem rate limit de 1000 req/min por API key, GraphQL pra alguns endpoints internos, webhooks pra notificar mudanças assinados com HMAC-SHA256"

...está te dizendo 8 coisas importantes. Sem repertório, você assenta. Com repertório, você responde: "Perfeito. Pra agentes WhatsApp seu time vai precisar webhook quando pedido for criado. Vou consumir REST. Vou implementar HMAC validation e dead-letter queue local pra retries."

Bônus: webhooks são onde MAIS oportunidades de Team Studio aparecem. "Agente que processa cada evento X" é venda fácil pra quase qualquer negócio digital.

1. O modelo mental: o que é uma API

API (Application Programming Interface) é o "contrato" pelo qual dois sistemas se falam. Tem 3 paradigmas principais hoje:

  1. REST: dominante, baseado em HTTP + recursos como URLs
  2. GraphQL: alternativa moderna, cliente pede só o que quer
  3. gRPC: alta performance pra serviço-a-serviço (menos comum em APIs públicas)

Plus: webhooks (callbacks) e streaming (Server-Sent Events, WebSocket).

Pra entender qual usa quando, primeiro entenda os princípios: - Cliente quer buscar dado: paradigma síncrono (REST/GraphQL/gRPC) - Cliente quer ser notificado de evento: webhook (server avisa) ou polling (cliente pergunta repetidamente)

2. REST em detalhe

REST (Representational State Transfer) foi proposto por Roy Fielding em 2000. Virou padrão de fato após 2010 com o boom de APIs web.

2.1 Princípios fundamentais

Recursos: cada "coisa" no sistema é um recurso com URL única.

/users          ← coleção de usuários
/users/123      ← usuário específico
/users/123/orders ← pedidos do usuário 123
/orders/456     ← pedido específico

Verbos HTTP: ação a fazer no recurso.

Verbo Significado Idempotente?
GET Buscar Sim
POST Criar Não (cada POST cria recurso novo)
PUT Substituir Sim (mesma operação dá mesmo resultado)
PATCH Atualizar parcial Geralmente sim
DELETE Apagar Sim (já tá apagado, deletar de novo dá mesmo resultado)

Status codes: respostas padronizadas.

  • 2xx Sucesso: 200 OK, 201 Created, 204 No Content
  • 3xx Redirect: 301 Moved Permanently, 302 Found, 304 Not Modified
  • 4xx Erro do cliente: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity, 429 Too Many Requests
  • 5xx Erro do servidor: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout

2.2 Anatomia de request/response

GET /api/users/123 HTTP/1.1
Host: api.empresa.com
Authorization: Bearer eyJhbGc...
Accept: application/json

----

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=60

{
  "id": 123,
  "nome": "Ana Silva",
  "email": "ana@email.com",
  "created_at": "2024-01-15T10:30:00Z"
}

2.3 Boas práticas REST

Resource naming: substantivos no plural. Não verbos. - ✅ GET /users ou GET /users/123 - ❌ GET /getUser?id=123 ou POST /createUser

Aninhamento limitado: profundidade máxima de 2-3 níveis. - ✅ /users/123/orders (2 níveis) - ❌ /companies/45/departments/12/teams/8/users/123/orders/456 (6 níveis, pesadelo)

Paginação consistente:

GET /users?page=2&per_page=20
GET /users?cursor=abc123&limit=20  (cursor-based, melhor pra escala)

Filtros via query params:

GET /users?status=active&created_after=2024-01-01

Versionamento: na URL OU header. - URL: /v1/users, /v2/users (mais comum, mais visível) - Header: Accept: application/vnd.empresa.v2+json (mais elegante mas obscuro)

Erros estruturados:

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Email inválido: 'foo@'",
    "field": "email",
    "details": "Email deve conter @ e domínio"
  }
}

2.4 OpenAPI / Swagger - documentação padrão

OpenAPI Specification (antes "Swagger") é o padrão pra documentar APIs REST. Arquivo YAML/JSON descreve todos os endpoints, parâmetros, respostas.

Benefícios: - Documentação gerada automaticamente (Swagger UI, Redoc) - SDKs gerados em várias linguagens - Mock servers a partir da spec - Testes contract automatizados

Sinal de empresa madura: API tem OpenAPI atualizada e validada no CI/CD.

Pergunta de reunião:

"Vocês têm OpenAPI da API? Tá atualizada com o que tá em produção?"

2.5 HATEOAS (raramente cobrado)

HATEOAS (Hypermedia As The Engine Of Application State) é princípio "REST puro" onde respostas incluem links pra próximas ações:

{
  "id": 123,
  "name": "Ana",
  "_links": {
    "self": "/users/123",
    "orders": "/users/123/orders",
    "update": "/users/123"
  }
}

Na prática: 95% das APIs REST IGNORAM HATEOAS. Não se preocupe muito com isso.

3. GraphQL - alternativa moderna

GraphQL foi criado pelo Facebook em 2012, open-sourced em 2015. Resolve problemas específicos do REST:

  • Over-fetching: REST retorna objeto completo, cliente queria só nome
  • Under-fetching: cliente precisa fazer 5 requests pra montar tela
  • API evolution: REST exige versionar pra mudar contrato

3.1 Como funciona

Cliente envia QUERY descrevendo exatamente os campos que quer:

query {
  user(id: 123) {
    nome
    email
    orders(last: 5) {
      id
      total
      items {
        product { name }
        quantity
      }
    }
  }
}

Server responde:

{
  "data": {
    "user": {
      "nome": "Ana Silva",
      "email": "ana@email.com",
      "orders": [
        { "id": 1, "total": 250, "items": [...] }
      ]
    }
  }
}

Cliente pediu nome, email, 5 últimos pedidos com itens. Server entregou exatamente isso. Sem campos demais, sem campos de menos.

3.2 Schema

GraphQL tem schema fortemente tipado:

type User {
  id: ID!
  nome: String!
  email: String!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
  status: OrderStatus!
  items: [OrderItem!]!
}

enum OrderStatus {
  PENDING
  PAID
  SHIPPED
  DELIVERED
}

type Query {
  user(id: ID!): User
  users(limit: Int = 20): [User!]!
}

type Mutation {
  createOrder(userId: ID!, items: [OrderItemInput!]!): Order!
}

Tipos fortes = melhor autocomplete, validação, documentação automática.

3.3 Quando GraphQL vence vs quando perde

Vence: - Frontend complexo com múltiplas telas que precisam de combinações diferentes de dados - Múltiplos clientes (web, mobile, admin) com necessidades diferentes - Time grande de frontend que quer flexibilidade - Microservices: GraphQL gateway agrega múltiplas APIs

Perde: - API pública usada por terceiros (REST é mais conhecido) - Cacheamento HTTP simples (GraphQL não cacheia bem em CDN) - Time pequeno (REST é mais simples) - Casos onde requests são bem padronizados

3.4 Implementações populares

  • Apollo Server / Apollo Client: combo dominante, ecossistema rico
  • Relay (Facebook): client mais sofisticado, requer disciplina
  • Hasura: gera GraphQL automaticamente sobre Postgres
  • GraphQL Yoga: alternativa leve a Apollo

3.5 N+1 problem

Problema clássico de GraphQL: query pede users { orders { items } } e implementação faz N queries no banco (1 pra users, N pra orders de cada user, M pra items de cada order).

Solução: DataLoader (Facebook), batching automático.

Sinal de empresa madura usando GraphQL: usa DataLoader, não tem N+1 problem.

4. gRPC (brevemente)

gRPC é framework de RPC criado pelo Google em 2015. Usa Protocol Buffers (Protobuf) pra serialização binária.

Vantagens: - 5-10x mais rápido que JSON (serialização binária) - Type-safe via .proto files - Streaming bidirecional nativo - Ótimo pra microservices internos

Desvantagens: - Browser não suporta nativamente (precisa gRPC-Web proxy) - Menos ferramentas pra debug - Curva de aprendizado

Quando usar: comunicação entre microserviços, sistemas de alta performance, APIs internas.

Quando NÃO usar: APIs públicas que terceiros vão consumir (REST/GraphQL são mais amigáveis).

5. Webhooks vs Polling

Quando server quer NOTIFICAR cliente que algo aconteceu, tem duas opções:

5.1 Polling

Cliente pergunta server "tem novidade?" repetidamente.

Cliente → Server: tem novidade?
Server → Cliente: não
[espera 30s]
Cliente → Server: tem novidade?
Server → Cliente: não
[espera 30s]
Cliente → Server: tem novidade?
Server → Cliente: sim, pedido 123 mudou pra "pago"

Pros: - Simples (só HTTP requests) - Cliente controla frequência - Não precisa servidor publicamente acessível

Cons: - Desperdiça recursos (99% das vezes a resposta é "nada") - Latência (até 30s no exemplo) - Não escala (1000 clientes pollando = 33 req/s do nada)

5.2 Webhooks (callbacks)

Cliente registra URL no server. Quando evento acontece, server CHAMA essa URL.

[registro inicial]
Cliente → Server: registra webhook em https://meu-app.com/webhook
Server → Cliente: ok

[depois, quando evento acontece]
Server → Cliente (POST em /webhook): pedido 123 mudou pra "pago"
Cliente → Server: 200 OK

Pros: - Real-time (latência de segundos, não minutos) - Eficiente (só comunica quando há evento) - Escala bem

Cons: - Cliente precisa servidor publicamente acessível - Server precisa retry logic se cliente cair - Cliente precisa validar autenticidade

5.3 Anatomia de webhook BEM FEITO

Webhook ingênuo é fácil de fazer mas dá problema. Webhook profissional tem:

1. Assinatura HMAC: server assina payload com chave secreta. Cliente valida.

POST /webhook HTTP/1.1
Content-Type: application/json
X-Signature: sha256=a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e

{"event": "order.paid", "order_id": 123}

Cliente recebe, calcula HMAC do body com chave compartilhada, compara com header. Se não bater, REJEITA.

Sem isso: atacante pode mandar webhook fake e disparar ações maliciosas no cliente.

2. Idempotência: cada evento tem ID único. Cliente armazena IDs processados, ignora duplicatas.

{
  "event_id": "evt_a3f5b9",
  "event": "order.paid",
  "order_id": 123,
  "timestamp": "2026-05-25T10:00:00Z"
}

Se server reenviar mesmo evento (porque cliente respondeu lento), cliente reconhece duplicata.

3. Retry logic: server tenta de novo se cliente retornar erro ou timeout.

Padrão de retry comum (exponential backoff): - Tentativa 1: imediato - Tentativa 2: 30s depois - Tentativa 3: 5 min depois - Tentativa 4: 30 min depois - Tentativa 5: 2h depois - ... - Tentativa 10: desiste, manda pra DLQ

4. Dead Letter Queue (DLQ): eventos que falharam após N retries vão pra fila pra revisão manual.

5. Timeout curto: cliente precisa responder em poucos segundos. Resposta longa = retry desnecessário. Padrão moderno: cliente devolve 200 imediatamente, processa em background.

5.4 Padrões importantes

At-least-once vs Exactly-once delivery: - At-least-once: cada evento entregue 1+ vezes. Cliente precisa lidar com duplicatas (idempotência). - Exactly-once: cada evento entregue 1 vez. Mais difícil de implementar.

99% dos webhooks usam at-least-once. Idempotência é OBRIGATÓRIA.

Webhook signing secrets vs HMAC: - Signing secret: chave compartilhada usada pra HMAC - Rotacionar periodicamente (a cada 6-12 meses)

Replay attacks: atacante captura webhook real e reenvia depois. - Mitigação: header timestamp + verificar que não é antigo (> 5 min)

5.5 Onde Team Studio entra

90% dos casos de uso de agentes envolvem REAGIR a webhook:

  • Pedido criado no e-commerce → agente manda WA personalizado
  • Cliente cancela assinatura no Stripe → agente reativa fluxo de retenção
  • Lead preenche formulário → agente faz qualificação automática
  • Email recebido com termo X → agente cria task interno
  • Mensagem WhatsApp → agente responde

Sem webhooks, agentes precisariam pollar a cada minuto. Caro e atrasado.

Sinal de empresa moderna: oferece webhooks pra principais eventos.

Pergunta de reunião:

"Quais eventos você oferece webhook? Webhook é assinado? Tem retry e DLQ?"

6. Rate limiting

Servers limitam quantas requests cada cliente pode fazer. Sem isso, um cliente abusivo pode derrubar o sistema.

6.1 Algoritmos comuns

Token bucket: cliente tem "balde de tokens". Cada request consome 1. Refill X tokens/segundo. - Permite picos curtos (usa balde acumulado) - Padrão mais popular

Leaky bucket: balde drena a taxa fixa. Requests adicionam ao balde. Se enche, rejeita. - Smooth (sem picos) - Usado em situações específicas

Fixed window: 100 req/min, contador reseta a cada minuto. - Simples mas pode ter "thundering herd" no início de cada janela

Sliding window: janela móvel de 1 min, conta últimos 60s. - Mais justo, evita thundering herd - Mais caro de implementar

6.2 Resposta HTTP padrão

Quando excede limite:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716625800

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Cliente bem feito respeita Retry-After e espera.

6.3 Sinal de API madura

API moderna tem: - Rate limit por API key (não por IP, que é instável) - Documentação clara dos limites por plano - Headers informativos (X-RateLimit-*) - Status 429 estruturado - Suporte a burst (token bucket)

7. Cinco perguntas que destravam reunião sobre APIs

7.1 "API é REST, GraphQL ou gRPC? Tem OpenAPI documentada?"

Por que importa: define como Team Studio se conecta. OpenAPI atualizada = empresa madura.

7.2 "Quais eventos têm webhook? São assinados? Têm retry?"

Por que importa: revela maturidade. Webhook sem assinatura = inseguro. Webhook sem retry = perde eventos.

7.3 "Rate limits por API key? Limites por plano?"

Por que importa: define se Team Studio cabe no plano atual ou precisa upgrade.

7.4 "Versionamento de API? Como vocês deprecam endpoints?"

Por que importa: API sem versionamento = quebra integração quando muda. Sinal de imaturidade.

7.5 "Como vocês detectam abuso de API ou queries lentas?"

Por que importa: revela observability da API. Empresa madura monitora isso.

8. Exercício prático

Cenário: cliente Team Studio. SaaS B2B (R$ 20M ARR) que vende ERP pra restaurantes. Diz:

"Temos API REST documentada em Swagger. Webhook pra alguns eventos mas é simples (sem assinatura, sem retry). Cliente final acessa nosso ERP via web. Queremos integrar agentes Team Studio que conversem com clientes finais via WhatsApp sobre dados deles (pedidos, faturas). Como vocês veem isso?"

Pratique: 1. Liste 5 perguntas técnicas pra mapear como integrar 2. Identifique 3 fragilidades nos webhooks atuais que precisam ser corrigidas antes 3. Esboce arquitetura da integração (REST + webhooks) 4. Identifique 1 oportunidade adicional pra Team Studio dentro disso

(Sugestões no fim.)

9. Material extra

Leitura essencial: - "REST API Design Rulebook" (Mark Massé) - clássico, leitura em 2 horas - "Web API Design: The Missing Link" (Brian Mulloy) - guia da Apigee, 30 páginas - "How to Design Webhooks That Don't Suck" (qualquer blog técnico recente)

Documentação de referência (boas APIs pra estudar): - Stripe API (https://stripe.com/docs/api) - gold standard de REST - GitHub API - Twilio API - GraphQL.org docs

Vídeos: - "REST vs GraphQL" (vários canais, ~15 min) - "Webhook Patterns" - busca no YouTube

Hands-on (2 horas): - Use Postman ou Insomnia pra fazer requests pra API pública (Stripe test mode é grátis) - Implemente um webhook simples (Node.js Express) que recebe POST e loga - Use ngrok pra expor seu webhook local pra Stripe/GitHub testar

10. Sugestões pro exercício prático (veja só depois de tentar)

5 perguntas técnicas:

  1. "Quais endpoints REST eu vou consumir? Listagem dos principais (pedidos, faturas, cliente)."
  2. "Rate limit por API key? Quanto tráfego de Team Studio aguentam (estimar X req/min)?"
  3. "Quais eventos têm webhook hoje? Quais eventos eu preciso que tenham (que não têm ainda)?"
  4. "Como autenticamos? API key, OAuth, basic auth?"
  5. "Tem ambiente de staging com dados de teste? Posso desenvolver sem afetar produção?"

3 fragilidades em webhooks atuais:

  1. Sem assinatura HMAC: atacante pode forjar webhook. Team Studio implementaria validação mas server precisa enviar com HMAC primeiro.
  2. Sem retry: se Team Studio cair 1 segundo, perde evento. Server precisa ter retry com exponential backoff + DLQ.
  3. Sem idempotência: se server reenviar, Team Studio dispara ação duplicada (manda WA duas vezes). Server precisa enviar event_id único.

Antes de integrar, cliente precisa endurecer webhooks. Team Studio pode oferecer ajudar com isso (escopo extra do contrato).

Arquitetura proposta:

ERP do cliente
    ↓ webhooks (assinados, com retry)
Team Studio (server)
    ↓ valida HMAC, valida idempotência, processa evento
Agente IA decide ação
    ↓
WhatsApp do cliente final (via Evolution API)

Cliente final responde
    ↓
Agente IA precisa de info do ERP
    ↓
Team Studio chama REST do ERP (com API key)
    ↓
Resposta processada, agente continua conversa

Oportunidade adicional:

Agente "qualidade de webhooks": monitora taxa de sucesso, latência e duplicatas dos webhooks do ERP. Quando algo destoa, alerta time deles. ERP melhora produto, Team Studio entrega valor que não estava no contrato original. Setup: 2 semanas. Não cobra extra mas vira credibilidade pra extensão de contrato no futuro.

11. Próxima semana

A Semana 9 fecha o Bloco D (APIs e Integrações) com autenticação corporativa: identidade vs autenticação vs autorização, OAuth 2.0 com fluxo Authorization Code e PKCE, OpenID Connect, SAML 2.0 enterprise, SSO com Active Directory/Entra ID, JWT em detalhe (claims, validação, armadilhas), secrets management com Vault. Inclui cenário healthcare com dados sensíveis e LGPD.