A sobreposição de fuso reduz o tempo de feedback, mas proximidade não cria significado compartilhado automaticamente. Times distribuídos entregam APIs confiáveis quando decisões viram contratos, exemplos, testes, ownership e evidências que continuam claras depois da reunião.
Reserve as horas compartilhadas para comportamento ambíguo, tradeoffs, segurança, incidentes e reviews difíceis. Status, contexto, testes e handoffs de rotina devem ser artefatos assíncronos.
A reunião termina com contrato atualizado, decisão, owner, condição de conclusão e perguntas abertas. Caso contrário, o próximo fuso recomeça pela memória.
OpenAPI cria contrato independente de linguagem. Deve definir auth, operações, requests, responses, exemplos, erros e ambientes. Gere clients e mocks quando útil, mas mantenha validação runtime e contract tests.
O contrato também explica retries, duplicatas, visibilidade, consistência eventual e campos imutáveis. Essas regras ficam próximas da spec e são testadas em CI.
Use timestamps RFC 3339 com offset para instantes e timezone nomeada quando a regra depende da hora civil. Dinheiro precisa de moeda e decimal explícitos. Idioma usa BCP 47; exibição usa bibliotecas CLDR.
Não envie 1,234.56 ou 1.234,56 como valor formatado. Não interprete 06/07/2026 sem formato. IDs fiscais, CEP, estado, telefone, nome e endereço precisam de campos de domínio, não de um layout único.
Vocabulário técnico compartilhado ajuda, mas textos, suporte, exemplos, avisos e termos de domínio precisam de revisão regional. Português brasileiro, espanhol latino-americano e premissas dos EUA não são intercambiáveis.
Separe IDs de máquina de labels localizados, registre locale, mantenha catálogos e teste plural, moeda e datas.
RFC 9457 define Problem Details. Use problem type estável, status, title, detalhe seguro, referência, violações de campo, retryability e códigos de domínio. Consumers não devem parsear prosa.
Defina erro retriable, correção do usuário, reauth, conflito ou suporte. A UI localiza a partir de códigos estáveis.
Prefira mudanças aditivas. Remoção, mudança de tipo/semântica, campo obrigatório, default e validação mais rígida são breaking até prova em contrário.
Deprecation tem owner, substituto, telemetry, guia, prazo e rollback. Contract diff e consumer tests bloqueiam quebra acidental.
PR ou design inclui problema, contract diff, exemplos, impacto de segurança/privacidade, migration, testes, traces/screenshots, rollout, rollback, perguntas e decisão exata.
Use draft PR cedo, CODEOWNERS para responsabilidade e checks obrigatórios. PR pequeno deve caber em uma sessão focada.
Defina owners para comportamento de produto, API, dados, SDK, infra, segurança, regras regionais e produção. Dono do repo não é automaticamente dono da decisão de negócio.
Escalonamento segue impacto e expertise, não geografia.
CI responde antes do review: OpenAPI válido, compatibilidade, exemplos, clients, contract tests, migrations, locales e segurança. Gaps objetivos não devem consumir overlap.
Checks obrigatórios precisam ser determinísticos e rápidos. Suites lentas rodam em paralelo ou ambiente staged com gates.
| Artefato/decisão | Owner | Reviewer | Gate automático | Falha sem isso |
|---|---|---|---|---|
| Lifecycle e edge cases | Produto/domínio. | Operação regional e engenharia. | Cenários e state-machine tests. | Times implementam significados diferentes. |
| OpenAPI e exemplos | Provider. | Consumers e segurança. | Lint, schema, compatibility diff e client build. | Mismatches aparecem tarde. |
| Locale, tempo, dinheiro e identidade | Domínio/localização. | Representantes EUA/PT-BR/ES. | Fixtures de locale, timezone, decimal e endereço. | Código correto produz comportamento regional errado. |
| Auth e autorização | Segurança/plataforma. | Provider, consumer, privacidade e operação. | Policy tests, negativos, secret scan e threat-model delta. | Acesso depende de premissas ocultas. |
| Migration e compatibilidade | Dados/API. | Consumers afetados. | Migration, rollback, diff e old-client suite. | Release quebra região fora da reunião. |
| Release e incident readiness | Service owner. | Suporte, operação e stakeholders. | Canary, dashboards, alert test e rollback. | API chega sem responder ou evidência. |
Handoff informa objetivo, evidência concluída, PR/branch, ambiente, blocker, decisão, risco, owner, próximo passo e expectativa. “Trabalhei no endpoint” não basta.
Em incidente, inclua severidade, regiões, início, baseline, timeline, hipóteses, mudanças, mitigação, comandos, métricas e próximo check.
Meça contrato pronto até primeiro sucesso do consumer, espera de review, change failure, defeito de contrato escapado, rollback, detecção/recuperação, redução de suporte e adoção regional.
Commits, linhas, reuniões, mensagens e horas online medem visibilidade, não valor.
Use least privilege em repo, cloud, banco e APIs. Separe credenciais, use identidade curta, audite ações, proteja dados de teste e remova acessos ao fim da alocação.
Defina residência, transferência, logging e suporte antes da implementação. Use fixtures sanitizadas e dados sintéticos.
Teste daylight saving nos EUA, países sem a mesma transição, fim do mês, feriados, cruzamento UTC, decimais, moedas, acentos, nomes longos, sobrenomes compostos, endereços, documentos, telefones e erros localizados.
Contract tests rodam em provider e consumer. Sandbox precisa de estados reais, não só happy path.
Eu criaria um template com OpenAPI, JSON Schema, exemplos, catálogo Problem Details, ADRs, ownership, clients, contract tests, fixtures regionais, compatibility checks, release checklist, dashboards, runbook e handoff.
Um portal mostraria owners, consumers, versões, deprecations, SLOs, mudanças, decisões, sandbox e incidentes, reduzindo status meetings.
Nearshore funciona quando o overlap acelera julgamento e artefatos duráveis carregam execução. O objetivo não é todos online juntos; é tornar comportamento, ownership, evidência e próximo passo visíveis.
Artigo sobre engenharia nearshore de APIs entre times dos EUA e América Latina, incluindo overlap de fuso, OpenAPI contract-first, localização, tempo e dinheiro, review assíncrono, CODEOWNERS, CI, compatibilidade, handoff de incidentes, segurança, testes regionais e métricas.