--- url: https://developers.zarv.com/api/lens/analise.md description: >- Etapa de Análise do Lens: as nove dimensões que cruzam o caso coletado, o veredito de cada uma, os alertas com evidência e como acompanhar o resultado. --- # 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 ```sh 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. ::: warning 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?". ::: tip 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. ```js 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](/api/lens/investigacao)**.