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 regra geral, tirada daqui
8. O que a gente não faria
9. 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.

O fluxo é sempre o mesmo:

fonte externa (DJe, via provedor)
   -> 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.

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 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.

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.