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.

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:

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.

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:

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

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:

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:

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.

# 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": "<id da raia Aprovado>" }'

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.

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.

Investigação ​

1. Ler os alertas e decidir o que apurar ​

2. Anexar a evidência que responde ao alerta ​

3. Incluir quem a apuração revelou ​

Declarado × descoberto ​

4. Corrigir o caso ​

5. Reanalisar ​

6. Dar o desfecho ​

O ciclo inteiro ​

O que o Lens guarda da apuração ​