Como transformar o feed de publicações em eventos de faturamento por uso
Um guia técnico para modelar payloads, relacionar nomes monitorados a contratos e criar regras confiáveis de cobrança por uso.
Conheça o Pocket Jurídico
Neste artigo10 seções
- Por que transformar o feed de publicações em eventos de faturamento por uso
- O modelo conceitual: fato processual, uso medido e cobrança
- Como desenhar o fluxo de faturamento por uso em seis etapas
- Quais campos uma publicação precisa ter para gerar cobrança automática
- Regras de negócio para evitar cobranças duplicadas
- Como o Pocket Jurídico pode participar dessa arquitetura
- O que registrar quando a IA enriquece uma publicação
- Mini esquema para ligar nomes e termos monitorados ao faturamento
- Métricas e logs para auditar o faturamento por uso
- Erros comuns ao implantar cobrança por uso
Por que transformar o feed de publicações em eventos de faturamento por uso
Transformar o feed de publicações em eventos de faturamento por uso permite cobrar de forma proporcional ao volume efetivamente monitorado, em vez de aplicar um preço fixo difícil de explicar. Para escritórios, departamentos jurídicos e plataformas jurídicas, essa abordagem aproxima o custo da operação real: nomes, termos, processos, consultas enriquecidas e recursos de inteligência artificial podem gerar registros financeiros rastreáveis.
O desafio começa quando uma mesma movimentação aparece em mais de uma fonte, é reprocessada após uma falha ou recebe novos documentos posteriormente. Sem uma identidade estável para cada evento, o sistema pode cobrar duas vezes, deixar consumo sem registro ou criar divergências entre o feed, o ERP e o relatório financeiro.
Uma arquitetura confiável separa três conceitos: o fato processual recebido, o uso que pode ser tarifado e o lançamento financeiro. Essa separação facilita ajustes de preço, contestação de cobranças e evolução do produto sem alterar o histórico original.
O desenho também precisa respeitar a natureza sensível dos dados jurídicos. A Lei Geral de Proteção de Dados Pessoais deve orientar finalidade, acesso, retenção e compartilhamento de informações presentes em publicações, processos e documentos.
O modelo conceitual: fato processual, uso medido e cobrança
O primeiro passo é definir o que exatamente representa uma unidade de uso. Uma publicação recebida pode ser a unidade principal, mas o contrato também pode considerar nomes monitorados, termos, processos validados, documentos capturados, resumo produzido por IA ou chamadas de API realizadas.
Uma regra simples é considerar como evento tarifável a combinação entre uma ocorrência processual válida, um item monitorado e uma conta contratante. Assim, uma publicação encontrada para o termo “Empresa Alfa” pode gerar um evento para o cliente correspondente, enquanto uma segunda entrega tecnicamente idêntica deve apenas atualizar o estado do mesmo evento.
A unidade de cobrança precisa ser compreensível para quem administra o contrato. “Publicação processada” é mais fácil de auditar do que uma métrica genérica como “unidade técnica”. Quando houver recursos adicionais, eles devem aparecer separados, por exemplo: publicação validada, extração de prazo e resumo gerado.
Para evitar confusão entre conteúdo e preço, mantenha no evento o valor calculado, a versão da tabela de preços e os critérios que levaram ao cálculo. Uma alteração contratual futura não deve reescrever o preço aplicado a eventos antigos.
A documentação da especificação HTTP ajuda a estruturar respostas, métodos e códigos de erro da API. Na prática, o faturamento por uso também depende de uma boa semântica de sucesso, repetição e falha nas chamadas.
Como desenhar o fluxo de faturamento por uso em seis etapas
- 1
Defina a unidade tarifável
Escolha se a cobrança será baseada em nomes e termos monitorados, publicações entregues, processos validados, chamadas de API ou recursos de IA. Documente inclusões, exclusões, cancelamentos e o momento em que o consumo passa a ser considerado válido.
- 2
Crie uma identidade estável para a ocorrência
Use um identificador da fonte, combinado com tribunal, processo, data, tipo de movimentação e item monitorado quando necessário. O identificador deve permanecer igual mesmo que o evento seja reenviado, enriquecido ou consultado novamente.
- 3
Relacione o monitoramento ao contrato
Cada nome ou termo precisa apontar para uma conta, contrato, centro de custo e regra de preço. Quando houver múltiplos escritórios terceirizados, preserve também a origem operacional e o responsável pela carteira.
- 4
Publique o evento em uma fila ou barramento
Evite calcular a cobrança dentro da mesma transação que captura a publicação. Uma fila permite repetir o processamento com segurança, controlar picos e separar a disponibilidade do monitoramento da disponibilidade do ERP.
- 5
Faça a deduplicação antes do lançamento
Consulte uma chave idempotente antes de gerar o registro financeiro. Se ela já existir, retorne o evento original ou atualize apenas campos permitidos, sem criar novo consumo.
- 6
Reconcilie feed, eventos e fatura
Ao fechar o período, compare a quantidade de ocorrências válidas, eventos tarifados e itens exportados ao sistema financeiro. Toda diferença deve produzir uma fila de exceção com motivo e responsável.
Quais campos uma publicação precisa ter para gerar cobrança automática
Um payload útil para faturamento precisa carregar dados processuais, contexto comercial e informações de processamento. Não é necessário enviar o texto integral para o ERP em todos os casos, especialmente quando o sistema financeiro só precisa comprovar o consumo. O conteúdo completo pode permanecer protegido na plataforma jurídica, com referência segura para consulta autorizada.
Um exemplo reduzido de evento de publicação seria:
{
"event_id": "evt_01JZ8K2P7Q4M",
"event_type": "publicacao.processada",
"occurred_at": "2026-09-30T13:42:18Z",
"source": {
"provider": "pocket_juridico",
"court": "TJSP",
"journal": "Diário da Justiça Eletrônico",
"source_reference": "tjsp-20260930-88421"
},
"case": {
"process_number": "1000000-00.2026.8.26.0100",
"instance": "primeiro_grau",
"movement_type": "intimacao"
},
"monitoring": {
"item_id": "mon_7842",
"item_type": "termo",
"item_value": "Empresa Alfa",
"account_id": "acc_204",
"contract_id": "ctr_2026_018"
},
"usage": {
"billable": true,
"unit": "publicacao_validada",
"quantity": 1,
"price_table_version": "2026-09-v3"
},
"integrity": {
"deduplication_key": "sha256:9f2c...",
"content_hash": "sha256:71ab..."
}
}
O campo source_reference identifica a ocorrência na origem. Já deduplication_key representa a identidade usada pelo faturamento. Em alguns contratos, o mesmo processo pode ser localizado por mais de um termo, então a regra precisa definir se isso gera um consumo ou apenas uma associação adicional à mesma publicação.
O campo billable não deve ser preenchido apenas porque houve captura. Ele deve refletir regras como validação do processo, correspondência confirmada, cobertura contratada e ausência de cancelamento. Separar “capturado”, “validado” e “faturável” evita que falsos positivos sejam lançados automaticamente.
Para mapear campos com segurança, consulte também o guia para sincronizar campos de publicações judiciais com ERP e CRM. A mesma disciplina de nomenclatura reduz erros quando o destino é um ERP, CRM, sistema jurídico ou plataforma própria.
Regras de negócio para evitar cobranças duplicadas
A duplicidade normalmente nasce de quatro situações: reenvio após timeout, entrega por fontes diferentes, atualização de uma publicação e associação da mesma ocorrência a vários termos. Tratar todos esses casos como simples duplicatas pode apagar informação legítima; tratá-los como novos consumos pode inflar a fatura.
Uma estratégia segura usa uma chave composta e uma política explícita. Por exemplo, origem + referência da publicação + processo + tipo de movimentação + unidade tarifável. Se a origem não fornecer um identificador confiável, utilize um hash normalizado de campos estáveis, removendo espaços extras, diferenças de maiúsculas e variações irrelevantes de formatação.
A chave idempotente deve ser persistida com estado, data de criação, versão da regra e identificador do lançamento financeiro. Estados comuns são recebido, validado, faturável, exportado, contestado e cancelado. O processamento repetido pode avançar um estado, mas não deve voltar silenciosamente nem gerar uma segunda cobrança.
Considere também uma janela de reconciliação. Se uma publicação chegar sem número de processo e for completada algumas horas depois, o sistema deve permitir vincular o segundo registro ao primeiro. Um prazo de 24 horas, por exemplo, pode ser adequado em determinada operação, mas deve ser validado com base no comportamento real das fontes.
O evento de atualização não precisa ser cobrado novamente. Ele pode registrar usage.quantity: 0, relacionar-se ao evento original e guardar a alteração para auditoria. Já um novo ato processual, com nova referência e consequência operacional distinta, deve receber outro identificador.
Essa lógica complementa uma arquitetura de integração bem definida. O conteúdo sobre push, consulta periódica ou integração orientada a eventos ajuda a escolher o mecanismo de entrega, mas a decisão de faturamento depende da identidade e do estado de cada ocorrência.
Como o Pocket Jurídico pode participar dessa arquitetura
Em uma operação baseada no Pocket Jurídico, o feed funciona como a camada operacional onde a publicação é recebida, validada e enriquecida antes de ser enviada ao sistema interno. A plataforma monitora nomes, termos e processos em diferentes diários e tribunais, identifica o processo e organiza o contexto para reduzir consultas manuais.
O evento enviado ao ERP ou CRM pode conter somente os metadados necessários para faturamento, enquanto o usuário autorizado acessa a publicação, o histórico, os documentos e os comentários no ambiente jurídico. Essa separação reduz a exposição de dados e evita replicar o conteúdo integral em cada sistema corporativo.
Uma implementação comum utiliza um adaptador entre o feed e o ERP. Esse adaptador recebe o evento, valida o contrato, consulta a tabela de monitoramentos, aplica a regra de preço, grava a chave idempotente e publica o lançamento no destino. Salesforce, TOTVS, softwares jurídicos e plataformas próprias podem receber estruturas diferentes sem alterar o evento de origem.
Quando a equipe usa MCP jurídico, o fluxo pode acrescentar dados derivados antes da cobrança de recursos de IA. Um agente conectado com autorização adequada pode solicitar ao ChatGPT, Claude ou Gemini a extração de prazo e o resumo da publicação, retornando o resultado com modelo, versão do prompt, confiança e indicação de revisão humana.
O MCP jurídico para conectar IA a processos e publicações deve ser tratado como camada de acesso controlado, não como autorização automática para decisões financeiras. A extração de um prazo pode gerar um evento de uso de IA, mas a publicação original continua sendo a fonte de evidência e o advogado deve revisar informações críticas.
O que registrar quando a IA enriquece uma publicação
- ✓Identidade da publicação de origem, identificador do processo e conta contratante, para que o uso de IA possa ser relacionado ao evento processual sem expor dados desnecessários.
- ✓Tipo de operação executada, como resumo, extração de prazo, classificação de urgência ou sugestão de tarefa. Cada operação deve ter uma unidade de cobrança clara e independente.
- ✓Modelo utilizado, fornecedor, versão do prompt ou instrução, data e duração da chamada. Esses dados ajudam a explicar variações de custo e a reproduzir uma investigação.
- ✓Resultado da validação, incluindo revisão humana, correção feita pelo usuário e decisão de aceitar, rejeitar ou refazer a análise. Uma nova execução precisa ter seu próprio identificador.
- ✓Indicação de falha, indisponibilidade, limite de uso ou resposta incompleta. Não cobre automaticamente uma chamada que não produziu o resultado contratado, salvo se essa condição estiver prevista no contrato.
- ✓Política de privacidade aplicada ao conteúdo. A documentação oficial sobre o protocolo MCP deve ser complementada por controles internos de autenticação, autorização, registro e retenção.
Mini esquema para ligar nomes e termos monitorados ao faturamento
O vínculo comercial começa no cadastro do item monitorado, não no momento em que a publicação chega. Cada nome ou termo deve possuir um identificador interno, status, conta proprietária, contrato vigente e regra de preço. Evite usar o texto do termo como chave, pois ele pode ser alterado sem que o histórico deixe de existir.
Um esquema mínimo pode conter as tabelas conta, contrato, monitoramento, regra_preco, evento_uso e lancamento. A tabela monitoramento relaciona monitoring_id a account_id e contract_id; evento_uso guarda a ocorrência e a unidade tarifável; lancamento registra o resultado da exportação para o sistema financeiro.
Exemplo de relacionamento:
{
"monitoring_id": "mon_7842",
"account_id": "acc_204",
"contract_id": "ctr_2026_018",
"cost_center": "juridico-contencioso",
"billing_rule": {
"unit": "publicacao_validada",
"included_quantity": 500,
"overage_price": 0.18,
"valid_from": "2026-09-01",
"valid_to": "2026-09-30"
}
}
Se um escritório terceirizado atende vários clientes, não misture contratante, responsável pela execução e proprietário do processo. Esses papéis podem ser diferentes e precisam aparecer separadamente para permitir rateio, prestação de contas e controle de acesso.
O período de vigência também merece atenção. Uma publicação capturada no último dia do mês e validada no mês seguinte pode ser contabilizada pela data de ocorrência, pela data de validação ou pela data de entrega. A escolha deve constar no contrato e ser aplicada de forma consistente.
Métricas e logs para auditar o faturamento por uso
A auditoria precisa responder três perguntas: o que aconteceu, por que foi tarifado e como o valor chegou à fatura. Para isso, registre o identificador da publicação, a chave de deduplicação, o contrato, a versão da regra, o horário de cada etapa e o resultado da exportação.
As métricas operacionais mais úteis incluem quantidade de publicações capturadas, percentual validado, eventos faturáveis, duplicidades bloqueadas, falhas de entrega, tempo entre captura e lançamento e divergências na reconciliação. Um painel pode separar dados por tribunal, carteira, cliente, tipo de monitoramento e período.
Também acompanhe a taxa de eventos sem vínculo comercial. Esse indicador revela nomes ou termos cadastrados sem contrato vigente, alterações incompletas de carteira e falhas de sincronização com o ERP. Um evento sem conta não deve desaparecer nem ser lançado em um cliente provável.
Para análise financeira, compare consumo incluído, excedente, recursos de IA e créditos cancelados. Em uma carteira com 10 mil processos, uma pequena taxa de duplicidade pode produzir centenas de lançamentos indevidos ao longo do mês, especialmente quando há reprocessamentos em lote.
O guia de KPIs para integrar publicações por API oferece uma base para medir latência, perdas e reconciliação. Para evidência jurídica e operacional, mantenha trilhas imutáveis ou protegidas contra alteração, com acesso restrito e retenção compatível com a política da organização.
Erros comuns ao implantar cobrança por uso
- ✓Cobrar toda captura antes da validação do processo. Isso transforma falsos positivos e registros incompletos em reclamações financeiras.
- ✓Usar o número do processo como única chave. Um mesmo processo pode gerar várias movimentações legítimas, e uma publicação pode chegar sem número completo na primeira tentativa.
- ✓Permitir que cada sistema calcule o preço. Quando feed, middleware e ERP aplicam fórmulas diferentes, a reconciliação se torna manual e frágil.
- ✓Sobrescrever eventos antigos quando um contrato muda. O histórico deve conservar a tabela de preços e a versão da regra aplicada no momento do uso.
- ✓Enviar o texto integral para todos os destinos. O ERP geralmente precisa do consumo e da referência, não de uma cópia irrestrita da publicação.
- ✓Cobrar tentativas de IA sem distinguir sucesso, falha e repetição. Chamadas refeitas por erro técnico devem ser relacionadas ao evento original e tratadas conforme a política contratual.
- ✓Ignorar contestação e estorno. Um evento cancelado precisa manter o vínculo com o evento original, o motivo, o usuário responsável e a data da alteração.
Perguntas Frequentes
Quais campos de uma publicação são essenciais para gerar um evento de cobrança automático?▼
Os campos essenciais são identificador da origem, tribunal ou diário, data da ocorrência, número do processo quando disponível, tipo de movimentação, item monitorado, conta, contrato e unidade tarifável. Também é recomendável registrar a chave de deduplicação, a versão da regra de preço e o estado do processamento. O texto integral pode ser mantido na plataforma jurídica e referenciado por um identificador seguro.
Como evitar cobranças duplicadas quando vários alertas chegam sobre a mesma movimentação?▼
Crie uma chave idempotente baseada em campos estáveis da ocorrência, como referência da fonte, processo, tipo de movimentação e unidade de uso. Persista essa chave antes de gerar o lançamento financeiro e faça com que reenvios retornem o evento existente. Para publicações que chegam incompletas e depois são atualizadas, use uma janela de reconciliação e estados de processamento, em vez de criar uma nova cobrança automaticamente.
É possível cobrar por resumo ou extração de prazo feita por inteligência artificial?▼
Sim, desde que o contrato defina a operação como unidade de uso e diferencie uma publicação processada de uma chamada de inteligência artificial. O evento deve registrar modelo, fornecedor, versão da instrução, resultado e eventual revisão humana. Falhas técnicas, tentativas repetidas e correções precisam seguir uma política clara para não gerar cobrança inesperada.
Como mapear nomes e termos monitorados para clientes e contratos em um ERP?▼
Use um identificador interno imutável para cada nome ou termo e relacione-o às tabelas de conta, contrato, centro de custo e regra de preço. Não use apenas o texto do termo, porque ele pode mudar e causar perda de histórico. O mapeamento deve indicar vigência, status, responsável operacional e tratamento para itens sem contrato ativo.
Qual é a diferença entre uma publicação capturada, validada e faturável?▼
Capturada significa que o sistema recebeu um registro de alguma fonte. Validada indica que a ocorrência foi relacionada ao processo ou monitoramento correto e passou pelos critérios de qualidade definidos. Faturável é a ocorrência que, além de válida, está coberta por um contrato e atende à unidade de cobrança, sem duplicidade ou exclusão prevista.
Quais métricas devem ser registradas para auditar cobranças por uso?▼
Registre volume capturado, volume validado, eventos faturáveis, duplicidades bloqueadas, falhas de entrega, tempo de processamento e diferenças na reconciliação. Para cada evento, mantenha identificador, chave idempotente, conta, contrato, regra de preço, versão e histórico de estados. Métricas de exceção, como eventos sem vínculo comercial e lançamentos cancelados, são especialmente úteis para encontrar problemas antes do fechamento.
O evento de faturamento deve conter o texto completo da publicação judicial?▼
Na maioria das integrações, não é necessário. O evento pode conter metadados, identificador da publicação, hash, referência segura e os dados mínimos para comprovar o consumo, enquanto o texto permanece no ambiente jurídico com controle de acesso. O conteúdo integral deve ser compartilhado apenas quando houver finalidade operacional, autorização e proteção compatíveis com a sensibilidade dos dados.