Guia rápido

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

1. Pegue um token

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

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

O token vale 360 segundos — renove com POST /api/v1/authentication/refresh. Detalhes em Autenticação.

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

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:

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

O caso nasce na raia Abertura. Veja a Coleta 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.

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 }
    ]
  }"

{ "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

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.

Confira os envolvidos que a montagem criou antes de seguir:

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

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

{ "researchId": "7d2f8e10-…", "status": "QUEUED" }

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

6. Leia o veredito

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)}'

{ "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.

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.

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.