Análise

A Análise cruza o que a Coleta trouxe. Ela roda nove dimensões sobre o caso — cada uma responde uma pergunta e devolve um veredito, com os alertas que o sustentam e a evidência de cada alerta.

A regra que manda no desenho: o modelo decide e explica; a prova é do código. Os alertas saem de regras em código, nunca do modelo — é o que impede um achado inventado. Do modelo vem o juízo e o resumo.

Pedir a análise

curl -X POST "https://services.zarv.com/api/v1/lens/$WORKSPACE_ID/research/$RESEARCH_ID/analyze" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

json

{ "researchId": "7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f", "status": "QUEUED" }

O pedido não tem corpo. Ele responde 202 na hora, e um worker enriquece os envolvidos e roda as dimensões depois — isso leva minutos, e nada disso cabe no tempo de uma requisição HTTP.

O caso vai para a raia Analisando no pedido, e para Analisado ou Análise falhou no fim.

Uma análise por vez, e nunca junto com o envio

Pedir outra análise com uma em andamento é 409. Pedir com o envio dos documentos rodando também é 409: a análise lê o caso que o envio ainda está gravando. Espere documents.status ser DONE.

Pedir a análise de um caso já analisado é permitido: a nova substitui a anterior, e cada dimensão sobrescreve o campo dela.

Uma API que subiu sem o agente de IA responde 503 — não há quem analise.

Acompanhar e ler o resultado

Tudo sai no GET do caso, em analysis:

json

{
  "analysis": {
    "status": "DONE",
    "errorCode": "",
    "startedAt": "2026-11-04T12:40:00Z",
    "finishedAt": "2026-11-04T12:46:12Z",
    "result": {
      "dimdocumental": { "status": "apurado", "verdict": "atencao", "alerts": [ … ], "summary": "…" },
      "dimchronology": { "status": "apurado", "verdict": "compativel", "alerts": [], "summary": "…" },
      "dimpossession": { "status": "nao_apurado", "reason": "o caso é uma colisão: não há perda de posse a apurar", "alerts": [] }
    }
  }
}

`status`	Significado
`""`	O caso nunca foi analisado; `result` é `null`
`QUEUED`	Na fila
`PROCESSING`	Rodando
`DONE`	Terminou
`FAILED`	Parou — o `errorCode` diz por quê

Cada dimensão grava o resultado dela assim que termina. Uma análise em PROCESSING já tem um result legível, com as dimensões que já rodaram — e uma análise que falhou numa dimensão mantém o resultado de todas as outras.

`errorCode`	Significado
`DIMENSIONS_FAILED`	Alguma dimensão falhou; o resultado das outras está gravado
`ANALYSIS_FAILED`	A análise parou por outro motivo: caso sem documento, envolvido inválido, banco
`ATTEMPTS_EXHAUSTED`	A análise derrubou o worker três vezes e não volta à fila

O formato de uma dimensão

Toda dimensão devolve a mesma forma:

json

{
  "status": "apurado",
  "verdict": "atencao",
  "reason": "",
  "alerts": [
    {
      "code": "DOC_OWNER_MISMATCH",
      "level": "atencao",
      "entities": ["PERSON:11144477735"],
      "documents": ["b41c9f27-8d3e-4a16-9c5b-2e7f80a1d3c4"],
      "evidence": ["CRLV: MARIA DA SILVA", "Apólice: JOÃO DA SILVA"],
      "message": "O titular do CRLV não é o segurado da apólice."
    }
  ],
  "summary": "Os documentos fecham entre si, com uma divergência de titularidade a esclarecer."
}

`status`: apurou ou não?

`status`	Significado
`apurado`	A dimensão tinha o que cruzar e cruzou
`nao_apurado`	Faltou dado, fonte ou parte — e o `reason` diz o quê

Não apurar é uma resposta, não um erro. A dimensão de Posse cala numa colisão: não houve perda de posse a apurar, e dizer isso é mais honesto do que inventar um veredito. Uma dimensão que não apurou não diz que está tudo bem — ela diz que não olhou.

`verdict`: o pior nível entre os alertas

`verdict`	Significado
`critico`	O apurado contraria o relato
`atencao`	Há ponto a esclarecer, mas nada contraria o relato
`compativel`	O apurado sustenta o relato

Um alerta critico basta para a dimensão inteira ser critico. Sem nenhum crítico, um atencao basta para ser atencao. Só compativel — ou nenhum alerta — é compativel.

`alerts`: o achado, com a prova

Os alertas vêm do mais grave para o informativo. Cada um traz:

code — o achado, num vocabulário fechado por dimensão (DOC_OWNER_MISMATCH, COVERAGE_PLATE_MISMATCH, …). É por ele que você decide, não pela frase.
entities e documents — a quem e a quais documentos o alerta aponta. É o que permite destacar na tela exatamente a peça em questão.
evidence — o que sustenta o achado, em texto curto: a data, a placa, o nome.
message — a frase que o analista lê.

`summary`

A leitura do caso em uma frase — a única parte escrita pelo modelo.

As nove dimensões

Campo	Dimensão	A pergunta que ela responde
`dimdocumental`	Documental	As peças do caso falam da mesma gente e do mesmo veículo?
`dimchronology`	Cronologia	As datas fecham entre si, e algo aconteceu antes do próprio fato?
`dimcoverage`	Cobertura	O evento caiu na vigência da apólice, e o veículo do sinistro é o veículo segurado?
`dimpossession`	Posse	Houve perda de posse material, e a base, o boletim e as fotos sustentam isso?
`dimimagery`	Imagem	As fotos se sustentam como conjunto — mesma peça, mesma placa, mesma cadeia de custódia?
`dimterritory`	Território	O evento aconteceu na praça de alguma das partes?
`dimeconomic`	Econômica	O valor segurado bate com o valor do veículo, há gravame, o veículo cabe na vida de quem o tem?
`dimnetwork`	Rede de vínculos	A que distância as partes estão umas das outras, e os veículos se ligam por alguém?
`dimphysical`	Física	O dano que aparece nas fotos é o dano que esse evento faria nesse veículo?

Cada uma persegue uma tese de fraude diferente:

Documental — o mesmo CPF com nomes diferentes, a mesma placa com chassis diferentes, quem aciona o seguro sem ser o dono do carro.
Cronologia — a data do fato diverge entre as fontes, há ordem impossível (um documento que descreve o fato datado antes dele, a apólice que só passa a valer depois), ou o aviso veio muito depois do fato.
Cobertura — o sinistro está fora da apólice: fora da vigência, ou a apólice de um carro "emprestada" para o sinistro de outro.
Posse — o veículo não foi subtraído: a perda é declarada mas nenhum documento a descreve, ou o fato foi tentativa (e na tentativa não houve perda).
Imagem — as fotos não são do veículo do caso: outro carro do mesmo modelo, fotos de anúncio, fotos de um sinistro anterior.
Território — o lugar que não se explica: o evento longe de todos, sem motivo para ninguém estar ali; ou exatamente na praça de uma das partes, com a outra tendo viajado até lá.
Econômica — o dono endividado que fabrica ou infla o sinistro para quitar a dívida, ou o veículo que vale muito menos do que a apólice paga.
Rede de vínculos — os dois lados se conhecem: sinistro combinado, com os veículos ligados por endereço, telefone, sociedade ou parentesco.
Física — o dano não bate com a dinâmica declarada: sinistro forjado, dano anterior aproveitado, dano exagerado.

Imagem e Física olham a mesma foto e perguntam coisas diferentes. A Imagem pergunta "é este carro?"; a Física, "é este dano?".

Trate nao_apurado como informação

Uma dimensão responde nao_apurado quando falta o que cruzar — não há boletim de ocorrência, o caso não tem foto, a fonte que mediria aquilo não está disponível. O reason diz o quê, e o cartão do analista deve mostrar isso como está: não olhamos, e não está tudo bem.

O que o Lens enriquece antes de rodar

Antes das dimensões, o worker busca dados externos sobre quem tem função no caso — e só sobre eles. Quem não tem nenhuma dessas funções (o dono do veículo do segurado, o passageiro, a testemunha) não é enriquecido:

Lado	Função	O que o Lens busca
Segurado	o segurado (CPF ou CNPJ)	Zarv ID completo
	o condutor	Zarv ID completo + CNH
	o veículo (`PRINCIPAL`)	Asset completo
Terceiro	o condutor	Zarv ID completo + CNH
	o proprietário (CPF ou CNPJ)	Zarv ID completo
	o veículo (`TERCEIRO_ENVOLVIDO`)	Valor de mercado + histórico de donos

O condutor pode ser o proprietário: é a mesma pessoa com duas funções, e cada consulta é feita uma vez só.

É por isso que a análise leva minutos — ela consulta antes de cruzar —, e é por isso que os papéis dos envolvidos importam tanto: é o papel que diz ao Lens quem é o segurado, quem é o terceiro e qual veículo é qual. Um caso com papéis errados enriquece a pessoa errada.

Esperar a análise

Não há long polling nem webhook: consulte o caso a cada poucos segundos até o status ser terminal.

async function waitForAnalysis(workspaceId, researchId, accessToken) {
  const url = `https://services.zarv.com/api/v1/lens/${workspaceId}/research/${researchId}`;
  for (;;) {
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${accessToken}` },
    });
    const research = await res.json();
    const { status } = research.analysis;
    if (status === "DONE" || status === "FAILED") return research.analysis;
    await new Promise((r) => setTimeout(r, 5000));
  }
}

Com o resultado na mão, a decisão é do analista — e o que ele faz com ela é a Investigação.

Análise ​

Pedir a análise ​

Acompanhar e ler o resultado ​

O formato de uma dimensão ​

status: apurou ou não? ​

verdict: o pior nível entre os alertas ​

alerts: o achado, com a prova ​

summary ​

As nove dimensões ​

O que o Lens enriquece antes de rodar ​

Esperar a análise ​

Análise

Pedir a análise

Acompanhar e ler o resultado

O formato de uma dimensão

`status`: apurou ou não?

`verdict`: o pior nível entre os alertas

`alerts`: o achado, com a prova

`summary`

As nove dimensões

O que o Lens enriquece antes de rodar

Esperar a análise