---
url: https://developers.zarv.com/api/lens/quickstart.md
description: >-
  Do token ao caso analisado em seis passos: abrir o caso, enviar os documentos,
  acompanhar a leitura, pedir a análise e ler o veredito de cada dimensão.
---

# Guia rápido

Seis passos, do token ao veredito. Cada um leva ao detalhe da etapa correspondente.

## 1. Pegue um token

```sh
curl -X POST "https://services.zarv.com/api/v1/authentication" \
  -H "Content-Type: application/json" \
  -d '{"username": "seu.email@zarv.com", "password": "sua_senha"}'
```

```json
{ "accessToken": "eyJhbGci...", "expires_in": 360 }
```

O token vale **360 segundos** — renove com `POST /api/v1/authentication/refresh`. Detalhes em [Autenticação](/api/lens/authentication).

```sh
export ACCESS_TOKEN="eyJhbGci..."
export WORKSPACE_ID="3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607"
```

O `WORKSPACE_ID` é o do seu token: toda rota do Lens o traz no caminho, e um workspace diferente é `403`.

## 2. Abra o caso

```sh
curl -X POST "https://services.zarv.com/api/v1/lens/$WORKSPACE_ID/research" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "domain": "auto",
    "objective": "sinistro",
    "status": "CREATED",
    "incidentType": "colisao",
    "reportText": "Colisão traseira no cruzamento, sem vítimas."
  }'
```

Guarde o `id` da resposta:

```sh
export RESEARCH_ID="7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f"
```

O caso nasce na raia **Abertura**. Veja a [Coleta](/api/lens/coleta#_1-abrir-o-caso) para o que cada campo decide — principalmente o `incidentType`, que escolhe quais dimensões rodam.

## 3. Mande os documentos

Todos de uma vez, em Base64. Com `agentReader`, o Lens lê cada arquivo; com `autoCreate`, ele monta o caso a partir das leituras — você não precisa declarar envolvido nenhum.

```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\": [
      { \"fileName\": \"bo.pdf\",      \"contentType\": \"application/pdf\", \"base64\": \"$(base64 -i bo.pdf)\",      \"agentReader\": true, \"autoCreate\": true },
      { \"fileName\": \"apolice.pdf\", \"contentType\": \"application/pdf\", \"base64\": \"$(base64 -i apolice.pdf)\", \"agentReader\": true, \"autoCreate\": true },
      { \"fileName\": \"frente.jpg\",  \"contentType\": \"image/jpeg\",      \"base64\": \"$(base64 -i frente.jpg)\",  \"agentReader\": true }
    ]
  }"
```

```json
{ "researchId": "7d2f8e10-…", "status": "QUEUED", "total": 3, "progress": 0 }
```

Até **40 arquivos**, 10 MB cada, 50 MB no total, em PDF, JPEG, PNG ou WebP.

## 4. Acompanhe a leitura

```sh
curl "https://services.zarv.com/api/v1/lens/$WORKSPACE_ID/research/$RESEARCH_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq '.documents | {status, progress}'
```

Repita a cada poucos segundos até `status` virar `DONE`. O que o Lens fez com cada arquivo — e quem ele montou a partir das leituras — está em `documents.results` e `documents.assembly`, explicados na [Coleta](/api/lens/coleta#_4-acompanhar-o-envio).

Confira os envolvidos que a montagem criou antes de seguir:

```sh
curl "https://services.zarv.com/api/v1/lens/$WORKSPACE_ID/research/$RESEARCH_ID/entity" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq '.[] | {type, value, roles, manual}'
```

## 5. Peça 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-…", "status": "QUEUED" }
```

Só funciona com o envio terminado: com `documents.status` em `QUEUED` ou `PROCESSING`, o pedido é `409`.

## 6. Leia o veredito

```sh
curl "https://services.zarv.com/api/v1/lens/$WORKSPACE_ID/research/$RESEARCH_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.analysis.result | to_entries[] | {dimensao: .key, status: .value.status, verdict: .value.verdict, alertas: (.value.alerts | length)}'
```

```json
{ "dimensao": "dimdocumental", "status": "apurado", "verdict": "atencao", "alertas": 1 }
{ "dimensao": "dimchronology", "status": "apurado", "verdict": "compativel", "alertas": 0 }
{ "dimensao": "dimpossession", "status": "nao_apurado", "verdict": "", "alertas": 0 }
```

Cada dimensão traz os alertas com a evidência que os sustenta. O significado de `status`, `verdict` e de cada alerta está na [Análise](/api/lens/analise#o-formato-de-uma-dimensao).

## E depois

Os alertas com `verdict` `critico` ou `atencao` são a lista de trabalho do analista: anexar a evidência que os responde, incluir quem a apuração revelou, reanalisar e dar o desfecho. É a [Investigação](/api/lens/investigacao).

## Erros que você vai encontrar primeiro

| Resposta                                 | O que aconteceu                                                                      |
| ---------------------------------------- | ------------------------------------------------------------------------------------ |
| `401 authenticated user is required`     | O token não carrega usuário — toda escrita precisa de um autor                       |
| `403 research not owner`                 | O `workspaceId` do caminho não é o do token                                          |
| `409 RESEARCH_DOCUMENTS_IN_PROGRESS`     | Você pediu a análise (ou outro envio) com o envio rodando                            |
| `409 VEHICLE_IN_OPEN_RESEARCH`           | A placa já está num caso aberto; o corpo traz o `researchId` — continue naquele caso |
| `413 o envio passa de 50 MB`             | Divida o envio, ou comprima as fotos                                                 |
| `400 files[2]: … precisa do agentReader` | Um arquivo veio sem `type` e sem `agentReader`; o `index` diz qual                   |

A lista completa está na [visão geral](/api/lens/#erros).