Integração externa: quando a resposta certa é PHP

Neste post

1. O problema que a integração resolve
2. Por que não foi para o mesmo lugar do resto
3. 1. Endereço estável
4. 2. Custo
5. 3. Tolerância a lentidão
6. O desenho que mantém isso seguro
7. A parte difícil não é buscar, é gravar duas vezes
8. A regra geral, tirada daqui
9. O que a gente não faria
10. Resumo

O Jurislux é um ERP jurídico: clientes, processos, prazos, agenda, documentos, financeiro, apontamento de horas e relatórios. Flutter no aplicativo, Firebase no back-end — a mesma stack de todo o resto do portfólio.

Com uma exceção: a integração com publicações judiciais é PHP, num servidor compartilhado.

Escrito assim, parece incoerência ou preguiça. É nem uma coisa nem outra, e o raciocínio vale para qualquer integração com sistema de terceiro.

O problema que a integração resolve

Publicação em diário oficial é o recurso mais crítico de qualquer software jurídico. Prazo perdido não é inconveniente: é responsabilidade profissional, e o cliente do Jurislux é advogado autônomo ou escritório pequeno — gente que não tem um departamento para conferir o diário à mão.

O fluxo é sempre o mesmo:

fonte externa (DJe, via Escavador)
   -> coletar periodicamente
   -> normalizar
   -> vincular ao processo e ao cliente certos
   -> gerar prazo na agenda
   -> avisar

Nenhuma dessas etapas é interativa. Nenhuma depende de usuário. E a primeira delas conversa com um sistema que a gente não controla.

Vale sublinhar o que isso significa para o desenho: não existe ninguém olhando quando o coletor roda. Recurso interativo tem um usuário que percebe quando algo falha e aperta de novo. Recurso de fundo não tem. Todo defeito nele é silencioso por padrão, e é essa característica — não a linguagem — que deveria guiar a escolha.

Por que não foi para o mesmo lugar do resto

Três razões, em ordem de peso.

1. Endereço estável

Vários serviços de dados esperam requisição vinda de um endereço conhecido, e alguns condicionam credencial a isso. Ambiente serverless não dá essa garantia sem configuração adicional — e configuração adicional para contornar uma premissa do fornecedor é dívida desde o primeiro dia.

Um servidor com endereço fixo resolve isso por existir.

2. Custo

O coletor roda em intervalo fixo, com volume previsível. Function cobra por invocação e por tempo de execução; hospedagem já paga e ociosa cobra o mesmo independentemente de rodar ou não.

Para carga baixa e regular, o segundo modelo é mais barato — e "mais barato" num estúdio pequeno é o mesmo que "viável".

3. Tolerância a lentidão

Consulta a sistema público é lenta e irregular. Function tem limite de tempo de execução, e contornar isso significa quebrar o trabalho em pedaços, orquestrar, tratar retomada — infraestrutura para um problema que não existia.

Um script sem limite rígido de tempo simplesmente espera.

O desenho que mantém isso seguro

A parte importante não é onde o PHP roda. É onde ele não fica.

[ PHP ] -> le a fonte externa
        -> normaliza
        -> grava no Firestore
                        |
                        v
[ Flutter ] <- le do Firestore (unica fonte de leitura)

O coletor escreve. O aplicativo lê. Eles não se falam.

Isso tem três consequências práticas:

O coletor não está no caminho crítico. Se ele parar, ninguém perde acesso ao que já foi coletado. O sintoma é ausência de novidade, não indisponibilidade.

O aplicativo não conhece a fonte. Trocar de provedor de dados é reescrever o coletor, sem tocar no aplicativo. A fronteira é o formato gravado, não o fornecedor.

A falha é observável. Como a gravação carimba data e origem, um painel de "última coleta bem-sucedida" responde a única pergunta que importa nesse recurso: estou vendo tudo que chegou?

Num recurso onde silêncio pode significar prazo perdido, ausência de erro não é sinal de saúde. Só um carimbo de última execução bem-sucedida é.

A parte difícil não é buscar, é gravar duas vezes

Coletor que roda em intervalo fixo vai, mais cedo ou mais tarde, rodar duas vezes sobre a mesma janela de dados. As causas são banais e inevitáveis: a execução anterior demorou mais que o intervalo, a rede caiu no meio da gravação, alguém reiniciou o processo, o fornecedor devolveu a mesma publicação em duas consultas.

Se cada execução simplesmente insere o que encontrou, o resultado é publicação duplicada — e publicação duplicada num software jurídico vira prazo duplicado na agenda. O usuário abre o sistema e vê o mesmo compromisso duas vezes, com datas que podem divergir depois de qualquer edição.

A saída não é tentar garantir que o coletor rode só uma vez. É aceitar que ele vai rodar duas e fazer com que isso não importe: a gravação usa um identificador derivado da própria publicação, de modo que a segunda escrita substitui a primeira em vez de acrescentar.

A regra geral, tirada daqui

O erro de leitura sobre padronização de stack é achar que ela significa uma tecnologia. Ela significa uma forma de resolver cada tipo de problema.

A última linha é a que costuma ser desrespeitada. Integração externa é o único lugar do sistema onde as regras não são suas. Insistir na sua tecnologia preferida ali é pagar para adaptar o seu mundo ao mundo alheio, sem receber nada em troca.

E o critério para não virar bagunça é curto:

Tecnologia nova entra por fronteira, nunca por preferência. E entra com um contrato escrito de onde ela começa e onde ela termina.

No Jurislux esse contrato é uma frase: o coletor grava no Firestore no formato X, e não faz mais nada. Enquanto isso for verdade, a existência dele é um detalhe de implementação.

O que a gente não faria

Duas coisas, para ser específico sobre os limites:

Não colocaríamos regra de negócio no coletor. Vincular publicação ao processo certo é regra do produto, e ela pertence ao mesmo lugar das outras regras. O coletor traz e normaliza — o resto é do sistema.

Não deixaríamos o aplicativo consultar o coletor. No momento em que o aplicativo faz uma requisição direta ao PHP, ele passa a depender de um servidor compartilhado para funcionar, e todas as vantagens listadas acima viram desvantagens.

Não repetiríamos o arranjo por hábito. Ele existe porque três premissas do fornecedor apontavam na mesma direção. Se o próximo fornecedor autenticar por token e aceitar chamada de qualquer origem, a razão de ser do servidor desaparece — e manter o PHP ali seria exatamente a preferência disfarçada de arquitetura que a seção anterior condena.

Resumo

• Integração com sistema de terceiro é a única fronteira onde as premissas não

são suas. Respeite-as em vez de contorná-las.

• Endereço estável, custo previsível e tolerância a lentidão foram as três razões

concretas.

• O coletor escreve, o aplicativo lê, e eles não se falam. É isso que mantém o

arranjo seguro.

• Falha silenciosa em recurso de prazo é inaceitável: registre última execução

bem-sucedida, não apenas erros.

• Stack única significa uma forma de resolver cada tipo de problema, não uma

tecnologia para tudo.

• Tecnologia nova entra por fronteira, com contrato escrito. Nunca por

preferência.

Perguntas frequentes

Por que não fazer a integração numa Cloud Function?

Poderia, e para muitas integrações é o certo. Nesse caso pesaram três coisas: o serviço externo esperava requisição de um endereço estável, o volume era previsível e baixo, e já havia hospedagem paga e ociosa. Function cobra por invocação e por tempo; um script que roda de hora em hora num servidor que já está ligado custa zero a mais.

Isso não vira ponto único de falha?

Vira, e é por isso que ele não fica no caminho crítico. O papel dele é buscar e gravar; a leitura pelo aplicativo continua sendo do Firestore. Se o coletor parar, ninguém fica sem acessar o que já foi coletado — só para de chegar coisa nova, e isso é visível num painel de última execução.

Vale ter três tecnologias num produto pequeno?

Vale quando cada uma resolve uma fronteira diferente: aplicativo, tempo real e integração com terceiro. O que não vale é ter três formas de fazer a mesma coisa. A pergunta certa não é quantas tecnologias existem, é quantas fronteiras existem.