TLDR;

Adicionar um campo JSON (por exemplo custom_data ou metadata) no modelo base para que cada recurso possa armazenar identificadores e campos de integração sem inflar o esquema principal. Trate atualizações desse JSON como operações de patch: aceitar pares chave/valor para adicionar/atualizar, chave com null para remover a chave específica e objeto vazio para limpar tudo, assim não é preciso enviar o objeto completo. No SQLAlchemy, coloque o campo JSON não nulo (padrão {}) na declarative base e sobrescreva/implemente um método apply_patch genérico que aplique essas regras para todos os modelos via herança.

Resumo

Quando você cria uma API REST genérica, demandas de integração fazem o esquema crescer com campos específicos de clientes (IDs de CRM, referências de armazém etc.), tornando-o bagunçado. Uma solução simples e elegante, usada pelo Stripe, é adicionar um campo JSON de metadata/custom_data aos modelos, permitindo que cada cliente armazene chave–valor arbitrária. Para que isso se comporte como um campo normal, a implementação deve suportar: inclusão no create, atualizações parciais sem sobrescrever tudo, remoção de chaves enviando null e limpeza total enviando um objeto vazio. No FastAPI com SQLAlchemy isso fica mais limpo adicionando o campo ao declarative base (herança) e definindo um método apply_patch que aplica patches ao objeto; ele trata o caso de dicionário vazio (limpa), percorre pares chave–valor, remove chaves com valor None usando pop, e substitui/insere valores normalmente, usando uma cópia temporária antes de persistir. Esse padrão evita duplicação de lógica nas rotas, mantém o modelo centralizado e oferece um comportamento previsível e flexível para integrações sem poluir o domínio principal. O campo é definido como não nulo para garantir sempre um objeto, e apply_patch é chamado automaticamente ao atualizar, centralizando a lógica e evitando duplicação nas rotas, reduzindo manutenção e riscos de regressão operacionais futuros.