Externos

Componentes externos são serviços que você chama, mas não opera: uma API de terceiros, um provedor de pagamento, um provedor de e-mail. Muitas vezes são a parte mais lenta e menos previsível de uma requisição, têm seus próprios limites de taxa e suas quedas, e você não pode escalá-los nem consertá-los. Projetar em volta deles é sobretudo contenção: timeouts para que um provedor lento não segure suas threads, retries seguros porque são idempotentes, filas para que o usuário não espere por eles e conciliação, porque a visão deles sobre o mundo e a sua às vezes vão discordar.

No BoxOffice, payment é um adaptador em volta de um provedor de pagamento externo, notification envia os ingressos por um provedor de e-mail e catalog importa dados de eventos das APIs dos produtores.

flowchart LR
    O[serviço order] -->|timeout + circuit breaker + chave de idempotência| PAY[Provedor de pagamento]
    PAY -.webhook: pagamento confirmado.-> WH[endpoint de webhook] --> O
    O -->|evento OrderConfirmed| Q[(Fila)] --> N[workers de notificação] --> EM[Provedor de e-mail]
    C[importador do catálogo] -->|com limite de taxa e cache| TP[API do produtor]
    R[job noturno de conciliação] --> PAY
    R --> DB[(Banco de pedidos)]

3rd Party API

O que é. Qualquer API operada por outra empresa da qual o seu sistema depende: mapas e geocodificação, verificação de identidade, frete, feeds de eventos de produtores, clima, provedores de LLM. Você recebe um contrato (documentação, um SLA se tiver sorte, limites de taxa, um preço por chamada) e nada mais: sem acesso às métricas deles, sem controle sobre os deploys deles.

Quando usar.

• Compre em vez de construir quando a capacidade não é o seu diferencial e o provedor a faz melhor (mapas, score de fraude, cálculo de impostos).
• Quando há efeitos regulatórios ou de rede que você não consegue reproduzir (bandeiras de cartão, verificação de identidade).

Quando não usar (ou cuidado).

• Num caminho síncrono voltado ao usuário, cada chamada externa soma sua latência e sua disponibilidade: 99,9% × 99,5% (provedor) ≈ 99,4% para a requisição inteira. Prefira chamadas assíncronas, cache ou pré-cálculo.
• Aprisionamento ao fornecedor: envolva o provedor numa interface sua (um adaptador) para poder trocá-lo ou acrescentar um segundo.
• Proteção de dados: o que você envia (dados pessoais) sai do seu controle; confira os contratos e minimize os campos.

Números-chave.

Modos de falha.

• Respostas lentas esgotam suas threads e se propagam para cima (o clássico cenário cascading-failure) → timeouts, circuit breaker, bulkhead (um pool separado por provedor).
• Queda → fallback (dados em cache, uma funcionalidade degradada, um segundo provedor), enfileirar o trabalho para depois.
• Limite de taxa (429) → limitar a taxa do lado do cliente abaixo da cota, backoff respeitando o Retry-After, lotes, cache.
• Mudanças incompatíveis na API → fixar versões, testes de contrato, acompanhar avisos de descontinuação.
• Retry storms que pioram a queda do provedor e fazem você ser bloqueado → backoff exponencial com jitter, orçamento de retries.

No playground. thirdparty é um nó externo de chamada com grande variância de latência (lognormal, mediana de 150 ms com sigma alto), uma cota do provedor quota (padrão 1.000 req/s; requisições acima dela falham com 429) e quedas aleatórias mais frequentes que as dos nós internos. Proteja a aresta que o chama com timeoutMs, retries com backoff exp+jitter, circuitBreaker e um fallback. Cenários: cascading-failure, retry-storm.

Produtos reais.

Saiba mais: Computação › Integrações · Confiabilidade › Padrões · Estimativas › Matemática da disponibilidade · Hands-on 9

Payment

O que é. Um provedor de serviços de pagamento (PSP) cobra cartões, carteiras e pagamentos instantâneos em seu nome e transfere o dinheiro para a sua conta. Você nunca guarda números de cartão: o provedor entrega ao navegador um formulário hospedado ou tokeniza o cartão, e o seu backend só vê um token. O fluxo usual tem duas metades: uma requisição síncrona para criar ou confirmar um pagamento (que pode devolver "pendente") e um webhook assíncrono do provedor com o status final (aprovado, recusado, reembolsado, contestado). No Brasil, os pagamentos instantâneos via Pix seguem o mesmo formato: você cria uma cobrança (um QR code) e a confirmação chega como notificação.

Quando usar.

• Sempre, quando há dinheiro de verdade: processar cartões por conta própria significa escopo PCI DSS, contratos com adquirentes e tratamento de fraude.
• O serviço payment do BoxOffice é um adaptador: ele esconde o provedor atrás de uma pequena API interna (authorize, capture, refund, tratador de webhook), para que o provedor possa ser trocado ou um segundo possa ser acrescentado.

Quando não usar (ou cuidado).

• Nunca trate um timeout como falha: a cobrança pode ter sido feita. Repita só com a mesma chave de idempotência, ou consulte o status do pagamento.
• Nunca confie no redirecionamento do navegador ("pagamento OK") como prova: confirme pelo webhook (verificando a assinatura) ou por uma consulta de status no servidor.
• Nunca mantenha uma transação de banco ou um lock de assento aberto enquanto espera o provedor: segure o assento com expiração (hold_until), chame o provedor e depois confirme.
• Nunca coloque dados de cartão em logs, eventos ou analytics.

Números-chave.

Modos de falha.

• Cobrança em dobro — o cliente ou o seu serviço repete após um timeout sem chave de idempotência → uma chave de idempotência por tentativa de pagamento (por exemplo, derivada do id do pedido), guardada com o resultado.
• Webhook perdido, ou que chega antes de a linha do pedido existir → guarde os webhooks primeiro e processe de forma idempotente; um job de conciliação compara diariamente (ou de hora em hora) os seus pedidos com o relatório do provedor.
• Queda do provedor às 10:00 → circuit breaker, um estado "pagamento pendente" com a reserva do assento estendida, um segundo provedor para eventos críticos, comunicação clara.
• Estados inconsistentes — pago no provedor, mas o pedido foi cancelado localmente (ou o contrário) → uma saga com compensações (reembolsar, liberar o assento) e a conciliação como rede de segurança.
• Fraude e chargebacks → as ferramentas antifraude do provedor, limites de velocidade por usuário e por cartão, 3-D Secure.

No playground. payment é um nó externo de chamada com grande variância de latência (mediana de 400 ms), uma cota do provedor quota (padrão 500 req/s) e quedas aleatórias; o cenário payment-system mostra retries sem idempotência criando cobranças duplicadas, e o cenário flash-sale mostra o pagamento virando o gargalo quando a venda abre. Use timeoutMs, retries com exp+jitter, circuitBreaker e um fallback ("pagamento pendente") na aresta que vem de order. Cenários: payment-system, flash-sale, cascading-failure.

Produtos reais.

Saiba mais: Computação › Integrações · Estudo de caso: sistema de pagamentos · Mensageria › Padrões · Hands-on 9

Email

O que é. Um provedor de entrega de e-mail envia mensagens em seu nome por uma infraestrutura com reputação gerenciada e informa o que aconteceu (entregue, devolvido, marcado como spam) por webhooks ou eventos. Enviar é fácil; a entregabilidade é a parte difícil: autenticar o seu domínio (SPF, DKIM, DMARC), manter baixas as taxas de devolução e de reclamação, aquecer endereços de envio novos e respeitar os descadastramentos. E-mails transacionais (ingressos, recibos, redefinição de senha) e de marketing costumam ficar em fluxos separados, para que uma campanha ruim não prejudique a entrega dos ingressos.

Quando usar.

• Mensagens transacionais: o BoxOffice envia o ingresso e o recibo depois do OrderConfirmed, redefinições de senha, avisos de mudança no evento.
• Sempre de forma assíncrona: o pedido está confirmado quando o commit acontece, não quando o e-mail sai. Uma fila e os workers de notification fazem o envio.

Quando não usar (ou cuidado).

• Nunca envie e-mail dentro da transação de compra ou na thread da requisição: a latência e as quedas do provedor virariam as do usuário.
• Não opere seus próprios servidores de e-mail para envios em produção, a menos que esse seja o seu negócio: reputação de IP leva muito tempo para ser construída.
• Valem os limites de envio e as taxas por segundo do provedor: uma venda relâmpago que confirma 60.000 pedidos em 15 minutos dá ~67 e-mails por segundo, que precisam caber na cota da conta (peça aumentos com antecedência).
• E-mail não é garantido nem instantâneo; para avisos urgentes, combine canais (push, SMS) e mostre o ingresso no app.

Números-chave.

Modos de falha.

• Queda ou estrangulamento do provedor → a fila absorve; os workers repetem com backoff; um segundo provedor para os e-mails transacionais críticos.
• E-mails duplicados — entrega at-least-once da fila → consumidor idempotente com chave (id do pedido, modelo).
• Cair no spam → SPF/DKIM/DMARC, fluxos separados para transacional e marketing, higiene das listas.
• Mensagem venenosa (endereço inválido, erro no modelo) trava a fila → dead-letter queue após N tentativas, alertas.
• Perda silenciosa → acompanhar os eventos do provedor (entregue/devolvido) e oferecer "reenviar ingresso" no app.

No playground. email é um nó externo de chamada (mediana de 250 ms) com uma cota do provedor quota (padrão 100 envios/s) e quedas ocasionais; coloque-o atrás de nós queue e worker para que a latência e as falhas dele virem backlog, e não erros para o usuário. Cenários: notification-system, async-queue, flash-sale.

Produtos reais.

Saiba mais: Computação › Integrações · Estudo de caso: sistema de notificações · Mensageria › Semântica · Computação › Notifications · Hands-on 7