--- url: https://developers.zarv.com/api/lens/investigacao.md description: >- Etapa de Investigação do Lens: responder aos alertas da análise com nova evidência, incluir quem a apuração revelou, reanalisar e dar o desfecho ao caso. --- # Investigação A análise não decide o caso: ela diz o que **não fecha**. A Investigação é a etapa em que o analista persegue cada alerta — junta a evidência que o responde, inclui quem a apuração revelou, reanalisa com o caso mais completo e, no fim, dá o desfecho. ::: info Esta etapa usa as rotas que você já conhece A Investigação **não tem rotas próprias**. Ela é feita com as mesmas rotas da Coleta e da Análise, usadas com outra intenção: anexar evidência, incluir envolvido, pedir nova análise e mover o caso no quadro. O que muda é o momento e o porquê. ::: ## 1. Ler os alertas e decidir o que apurar O ponto de partida é o `analysis.result` do caso: cada dimensão com `verdict` `critico` ou `atencao` traz alertas, e cada alerta já aponta **a quem** (`entities`) e **a quais documentos** (`documents`) ele se refere, com a evidência que o sustenta. ```json { "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." } ``` Esse alerta tem uma diligência óbvia: quem é Maria, e por que o carro dela está na apólice de João? A resposta pode ser trivial (são casados, há procuração) ou ser o caso inteiro. Uma dimensão `nao_apurado` também pede trabalho: ela diz **o que faltou**. Faltou boletim de ocorrência? Peça o boletim e reanalise. ## 2. Anexar a evidência que responde ao alerta Use o mesmo envio de documentos, com o tipo `TASK_EVIDENCE` — o tipo livre para material coletado em resposta a uma diligência — e um `metadata` que amarra a evidência ao alerta: ```sh curl -X POST "https://services.zarv.com/api/v1/lens/$WORKSPACE_ID/research/$RESEARCH_ID/document" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "files": [{ "type": "TASK_EVIDENCE", "fileName": "procuracao.pdf", "contentType": "application/pdf", "base64": "...", "metadata": { "alerta": "DOC_OWNER_MISMATCH", "nota": "Procuração da titular ao segurado, reconhecida em cartório em 2024." } }] }' ``` O `metadata` é seu: o Lens o guarda como veio. Use-o para registrar **a que alerta a evidência responde** e **o que ela mostra** — é o que transforma um PDF solto num passo de apuração rastreável. Documentos que não são `TASK_EVIDENCE` também entram aqui: o boletim que faltava, a apólice completa, as fotos que não vieram na Coleta. Com `agentReader: true`, o OCR lê a peça nova, e a próxima análise já a cruza. ::: warning Um envio por vez Mandar um envio com outro em andamento é `409 RESEARCH_DOCUMENTS_IN_PROGRESS`. Espere `documents.status` ser `DONE` antes de mandar a próxima leva. E cuidado com `autoCreate` aqui: ele manda a montagem reescrever envolvidos e campos do caso a partir das leituras. Numa diligência, o normal é **não** usá-lo — o caso já está montado e revisado. ::: ## 3. Incluir quem a apuração revelou A pessoa que aparece no meio da investigação — o sócio, o parente, a oficina, o condutor que não estava declarado — entra pelo `POST .../entity`, com o papel que a apuração encontrou: ```sh curl -X POST "https://services.zarv.com/api/v1/lens/$WORKSPACE_ID/research/$RESEARCH_ID/entity" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "PERSON", "value": "111.444.777-35", "roles": ["REDE_FAMILIAR_CONJUGE"], "parentId": "5e9a3c71-2b4d-4e8f-a9c0-6d1b7f2e8a35", "reason": "Titular do CRLV, cônjuge do segurado. Procuração anexada em 04/11." }' ``` Os papéis de rede existem para isso — `REDE_FAMILIAR` e seus graus (`REDE_FAMILIAR_PAI`, `REDE_FAMILIAR_MAE`, `REDE_FAMILIAR_FILHO`, `REDE_FAMILIAR_IRMAO`, `REDE_FAMILIAR_CONJUGE`), `REDE_SOCIO`, `REDE_REU_JUNTO` e `CRIMINOSO` —, e é deles que a dimensão **Rede de vínculos** vive. Use `REDE_FAMILIAR` só quando o grau não for conhecido. Para a empresa que atendeu o veículo, os papéis de empresa: `FUNILARIA`, `MECANICA`, `LOCADORA` (só em `COMPANY`). ::: tip Escreva o `reason` `reason` é texto livre de até 2.000 caracteres: **por que** este envolvido está no caso. Num caso que vira disputa, é o campo que explica a um terceiro, meses depois, o que o analista sabia e quando. ::: ### Declarado × descoberto O campo `manual` separa dois pesos probatórios diferentes: | `manual` | Quem pôs ali | | -------- | ----------------------------------------------- | | `true` | **Declarado** — alguém o incluiu pela API | | `false` | **Descoberto** — a montagem do caso o encontrou | "O segurado disse que havia uma testemunha" e "a leitura do BO revelou um terceiro" não são a mesma coisa, e o Lens não as mistura. ## 4. Corrigir o caso O `PUT` do caso é um PATCH — só o que vier no corpo muda: ```sh curl -X PUT "https://services.zarv.com/api/v1/lens/$WORKSPACE_ID/research/$RESEARCH_ID" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "reportText": "Colisão traseira no cruzamento, sem vítimas. O condutor é o cônjuge da titular do veículo.", "doubts": ["A procuração cobre a data do fato?"] }' ``` `doubts` são as perguntas que o caso ainda precisa responder — a lista de pendências da apuração, visível a quem pegar o caso depois. `status`, `userId`, `domain` e `workspaceId` não são editáveis; vindos no corpo, são ignorados. ## 5. Reanalisar Com a evidência nova e os envolvidos novos, peça a análise outra vez: ```sh curl -X POST "https://services.zarv.com/api/v1/lens/$WORKSPACE_ID/research/$RESEARCH_ID/analyze" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` A análise nova **substitui** a anterior: cada dimensão sobrescreve o campo dela em `analysis.result`, e o código do erro, as tentativas e as horas são zerados. O caso volta para **Analisando** e, no fim, para **Analisado**. Se o `DOC_OWNER_MISMATCH` do exemplo continuar aparecendo, a procuração não resolveu o que o alerta aponta — a divergência de titularidade é um fato dos documentos. O que a diligência muda é a **leitura** que o analista faz dela, e é por isso que o desfecho é humano. ## 6. Dar o desfecho O desfecho do caso é um **movimento no quadro**: mover o caso para uma raia da fase `DESFECHO`. ```sh # as raias do workspace, com os ids curl "https://services.zarv.com/api/v1/lens/$WORKSPACE_ID/kanban" \ -H "Authorization: Bearer $ACCESS_TOKEN" # aprovar o caso curl -X PUT "https://services.zarv.com/api/v1/lens/$WORKSPACE_ID/research/$RESEARCH_ID" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "kanbanId": "" }' ``` | Destino | Fase | Quando | | ------------------- | ---------- | ----------------------------------------------------------------- | | **Aprovado** | `DESFECHO` | A apuração fecha: o caso segue para pagamento | | **Reprovado** | `DESFECHO` | A apuração não sustenta o sinistro como declarado | | **Dados pendentes** | `COLETA` | Falta material; o caso volta para a Coleta até a evidência chegar | A raia tem de ser uma linha `ACTIVE` do quadro **deste** workspace — qualquer outra coisa é `400`. Com o envio ou a análise rodando, o movimento é `409`: naquele momento, o caso é do worker. ::: info A raia nunca decide nada Ela **reflete** o que já aconteceu. Nenhuma regra do Lens lê a raia para decidir se um caso pode ser analisado ou editado — essa decisão é sempre do campo próprio (o status do envio, o da análise). Mover um caso para "Aprovado" não fecha nada por baixo: é o registro da decisão que o analista tomou. ::: ## O ciclo inteiro ``` ┌───────────────────────────────────────────────┐ │ │ análise ──▶ alertas ──▶ diligência ──▶ reanálise ────┘ │ ▼ desfecho: Aprovado · Reprovado ou volta: Dados pendentes ``` Não há limite de voltas: um caso pode ser analisado, complementado e reanalisado quantas vezes a apuração exigir. Cada análise sobrescreve a anterior, mas **os documentos e os envolvidos se acumulam** — e com eles o lastro do que foi apurado. ## O que o Lens guarda da apuração | Onde | O que registra | | --------------------- | ----------------------------------------------------------------- | | `document.metadata` | A que alerta a evidência responde, e o que ela mostra (campo seu) | | `entity.reason` | Por que aquele envolvido está no caso | | `entity.manual` | Se ele foi declarado ou descoberto | | `research.doubts` | As perguntas ainda em aberto | | `research.reportText` | O relato, como o analista o entende agora | | `analysis.result` | O veredito, os alertas e a evidência da **última** análise | | `kanbanId` | Onde o caso parou | Tudo o que se escreve pela API é auditado com o usuário do token — por isso uma escrita sem usuário autenticado é recusada com `401` antes de tocar no banco.