O Lens organiza a investigação de um sinistro de seguro auto em três etapas: Coleta (o caso, os envolvidos e os documentos), Análise (as nove dimensões que cruzam o que foi coletado) e Investigação (a diligência que responde aos alertas e o desfecho do caso).
Tudo gira em torno de um caso (research): ele tem envolvidos (entity — pessoa, empresa ou veículo) e documentos (document — o BO, a apólice, a CNH, o CRLV, as fotos do veículo). O caso sempre ocupa uma raia do quadro kanban do workspace, e o Lens o move sozinho a cada acontecimento.
As rotas longas são assíncronas: o envio dos documentos e o pedido de análise respondem 202 e um worker trabalha depois. O andamento das duas sempre sai no GET do caso, em documents e analysis.
Todas as rotas ficam em https://services.zarv.com e usam token Bearer JWT. O workspace do token precisa ser o do caminho.
Contact
Servers
Coleta
Abrir o caso, declarar os envolvidos e enviar os documentos. É a etapa em que o caso ganha matéria: o envio em lote lê cada arquivo com um agente de IA e monta o caso a partir das leituras.
Operations
Listar casos do workspace
Lista os casos do workspace, do mais recentemente editado para o mais antigo, com total do filtro inteiro e a página em data.
Todos os filtros são opcionais e se combinam. kanbanId é a página de uma raia do quadro — é com ele que o front monta cada coluna. A raia Abertura traz também os casos antigos, que nasceram antes de o caso guardar a raia.
search procura pelo value de um envolvido: uma placa (que sempre tem letra) ou um CPF/CNPJ (que só tem dígito). Uma busca nunca acha a outra.
Cada item traz as contagens de filhos (vehicleCount, entityCount, documentCount), que saem da mesma fonte do detalhe — a lista e o card nunca divergem.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"Query Parameters
Filtra pelos casos abertos por este usuário.
"uuid"Filtra pelo domínio do caso (por exemplo, auto).
"auto"Filtra pelo objetivo do caso.
"sinistro"Filtra pelo status do caso.
"CREATED""PROCESSING""COMPLETED""FAILED""CREATED"Placa ou CPF/CNPJ de um envolvido. Devolve os casos em que esse envolvido aparece.
"TST1A23"Devolve só os casos nesta raia do quadro. O total passa a ser o da raia.
"uuid"Tamanho da página. Ausente, zero ou negativo vale 10.
2010Quantos itens pular. Negativo vale zero; além do fim devolve uma página vazia, com o total intacto.
00Responses
A página de casos e o total do filtro.
Abrir um caso
Abre um caso no workspace e o põe na raia Abertura do quadro.
O autor do caso é o usuário do token, nunca o userId do corpo — esse campo é ignorado. Abrir um caso sem usuário autenticado é recusado com 401 antes de qualquer gravação.
incidentType decide quais análises rodam depois: a dimensão de posse só roda em roubo e furto, a de croqui só em colisão. Deixá-lo vazio continua valendo — o fluxo o deduz do relato —, mas um tipo declarado é sempre melhor que um deduzido.
reportTime é o instante do fato. Mande-o com o fuso do lugar do fato: um furto declarado às 23:48 em Ribeirão Pires é 02:48Z do dia seguinte, e quem formatar sem saber onde o fato aconteceu imprime o dia errado.
Idempotência
Mande o header Idempotency-Key com um valor único por caso (um UUID, por exemplo). Repetir a requisição com a mesma chave e o mesmo corpo devolve o caso que já existe, com 200 e o header Idempotent-Replayed: true, sem abrir um segundo. A mesma chave com um corpo diferente responde 409 IDEMPOTENCY_KEY_REUSED.
Sem a chave, duas chamadas abrem dois casos — nunca se deduplica por conteúdo.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Header Parameters
Chave única por caso (um UUID, por exemplo). Repetir a requisição com a mesma chave e o mesmo corpo devolve o caso que já existe, com 200 e Idempotent-Replayed: true.
"6f1c2a9e-4b7d-4e2a-9c3f-0a1b2c3d4e5f"Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"Request Body
Responses
Replay da mesma Idempotency-Key com o mesmo corpo: o caso que já existia, sem abrir outro.
Listar casos de um usuário
Lista os casos abertos por um usuário dentro do workspace, com o mesmo envelope { data, total } da listagem do workspace. O userId do caminho é filtro dentro do workspace autorizado, não identidade: quem autentica continua sendo o token.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O autor dos casos.
"uuid"Query Parameters
Tamanho da página. Ausente, zero ou negativo vale 10.
10Quantos itens pular.
0Responses
A página de casos do usuário e o total.
Consultar um caso
O caso inteiro: o relato, as contagens de filhos, a raia do quadro e — o que mais importa para quem integra — o andamento das duas rotas assíncronas.
documentsé o envio dos documentos: o status, o progresso de 0 a 100, o resultado de cada arquivo (saved,read,read_failedouleft_out, com o motivo) e a montagem do caso (documents.assembly), em que a reconciliação transforma as leituras em envolvidos e preenche o relato.analysisé a análise: o status, o código do erro quando falhou e oresult, com um campo por dimensão (dimdocumental,dimchronology, …).
Caso sem envio tem documents com a mesma forma, vazia; caso sem análise tem analysis.status vazio e result nulo. Nenhuma lista sai null.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Responses
O caso, com o envio dos documentos e a análise.
Editar o caso e movê-lo no quadro
Um PATCH do caso: o campo ausente (ou null) não muda, e string vazia não apaga. status, userId, domain e workspaceId não são campos editáveis — vindos no corpo, são ignorados.
kanbanId move o caso para outra raia do quadro. A raia precisa ser uma linha ACTIVE do quadro deste workspace; qualquer outra coisa é 400. Com o envio dos documentos ou a análise rodando, o movimento é 409: naquele momento, o caso é do worker.
É por aqui que o analista dá o desfecho: mover para Aprovado ou Reprovado (fase DESFECHO), ou devolver o caso para Dados pendentes quando falta material.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Request Body
Responses
O caso depois da edição, já na raia nova.
Apagar um caso
Apaga o caso e tudo que pende dele. É irreversível, e só o dono do caso — o workspace do token — pode apagar.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Responses
O caso foi apagado. Sem corpo.
Listar os documentos do caso
Lista os documentos já gravados no caso, num array.
Use ?content=false sempre que não precisar do arquivo: a listagem leve devolve os mesmos itens sem o base64. Com 40 documentos de até 10 MB, a diferença entre as duas é de centenas de megabytes.
O que os agentes leram de cada arquivo fica no metadata, na chave do agente.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Query Parameters
false devolve a listagem leve, sem o base64 de cada documento. Qualquer outro valor (ou a ausência) devolve o arquivo.
"false""false"Responses
Os documentos do caso.
Enviar os documentos do caso
Envia todos os arquivos do caso de uma vez e responde 202 sem chamar modelo nenhum. Os arquivos ficam na fila e um worker os identifica, lê e grava depois. É a rota que substituiu o antigo create de um arquivo por vez.
O que o worker faz com cada arquivo
- Sem
type, o identificador de documento diz o que o arquivo é (target): apólice, BO, aviso de sinistro, termo de terceiro, CNH, CRLV, foto do local, foto do veículo ouOUTRO. OOUTROfica fora do caso. - Foto de veículo passa também pelo OCR Veículo, e a posição da foto (frente, traseira, lateral, interior, cofre do motor) é que dá o tipo do documento.
- Com
agentReader: true, o OCR do tipo lê o arquivo e grava os campos extraídos nometadatado documento, na chave do agente. - Com
autoCreate: true, a leitura entra na montagem do caso: o agente de reconciliação transforma as leituras em envolvidos e preenche o relato (vejadocuments.assemblynoGETdo caso).autoCreateexigeagentReader— sem leitura não há o que montar.
Limites
| Limite | Valor |
|---|---|
| Arquivos por envio | 40 |
| Tamanho de um arquivo (decodificado) | 10 MB |
| Soma dos arquivos (decodificados) | 50 MB |
| Formatos | application/pdf, image/jpeg, image/png, image/webp |
O corpo inteiro é cortado em cerca de 67,7 MB antes de ser lido — o Base64 dos 50 MB mais folga para o resto do JSON. Passar disso é 413.
Um envio por vez
Há um envio por caso. Mandar outro com um em andamento é 409 RESEARCH_DOCUMENTS_IN_PROGRESS. O andamento sai no GET do caso, em documents.
Um arquivo recusado leva o índice dele no corpo do erro (index), para o front saber qual corrigir sem ler a frase.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Request Body
Responses
O envio entrou na fila.
Consultar um documento
Um documento do caso, com o base64 do arquivo e o metadata — onde ficam os campos que os OCRs extraíram, na chave de cada agente.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"O id do documento.
"b41c9f27-8d3e-4a16-9c5b-2e7f80a1d3c4""uuid"Responses
O documento.
Substituir um documento
Substitui o documento inteiro: type, fileName, contentType e base64 são obrigatórios, e o que não vier no corpo é apagado. Não é um PATCH.
É por aqui que se corrige o tipo que o agente errou, ou se amarra o documento a um envolvido pelo researchEntityId. O metadata é gravado como veio — para preservar o que os OCRs leram, releia o documento e reenvie o metadata inteiro com a sua chave a mais.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"O id do documento.
"b41c9f27-8d3e-4a16-9c5b-2e7f80a1d3c4""uuid"Request Body
Responses
O documento depois da troca.
Apagar um documento
Tira o documento do caso. O que o agente já leu dele continua gravado no resultado do envio e na análise que já rodou — apagar o arquivo não reescreve o passado.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"O id do documento.
"b41c9f27-8d3e-4a16-9c5b-2e7f80a1d3c4""uuid"Responses
O documento foi apagado. Sem corpo.
Listar os envolvidos do caso
Todos os envolvidos do caso, num array: as pessoas, as empresas e os veículos, cada um com os papéis, o cadastro consultado (profile) e o parentId que forma a árvore.
manual diz quem o pôs ali: true é declaração de quem abriu o caso; false é achado da apuração — a diferença é de peso probatório.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Responses
Os envolvidos do caso.
Incluir um envolvido
Põe uma pessoa, uma empresa ou um veículo no caso, com os papéis dela.
A consulta do cadastro
Criar um envolvido consulta um provedor pago e guarda o resultado em profile:
| Tipo | value |
Consulta | Chave em profile |
|---|---|---|---|
PERSON |
CPF | Dataset do Zarv ID v3 (PF) | dataset |
COMPANY |
CNPJ | Dataset do Zarv ID v3 (PJ) | dataset |
VEHICLE |
Placa | Zarv Asset | asset |
O CPF ou o CNPJ é conferido (tamanho e dígito verificador) antes da consulta: um erro de digitação é 400, e não uma consulta cobrada. A consulta vem depois de todas as conferências e antes de gravar — o que seria recusado não é cobrado, e uma consulta que falha não grava nada (502).
As regras da árvore
- O
VEHICLEé sempre raiz: ele não temparentId. - A
COMPANYsó fica sob umVEHICLE. - O
parentIdtem de ser um envolvido deste caso.
Duas regras que evitam caso duplicado
- Dentro do caso: se já existe um envolvido com esse
value, a chamada devolve o que já está lá, sem gravar de novo e sem consultar. - Entre casos: uma placa que já está num caso em aberto do mesmo workspace é recusada com
409 VEHICLE_IN_OPEN_RESEARCH, e o corpo traz oresearchIddaquele caso — é para onde as evidências devem ir.
value é obrigatório no VEHICLE (a placa). Em PERSON e COMPANY o documento é opcional: uma testemunha pode não ter.
O envolvido criado por aqui nasce manual: true — foi declarado, não descoberto. O que a montagem do caso cria a partir das leituras nasce manual: false.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Request Body
Responses
O envolvido entrou no caso.
Consultar um envolvido
Um envolvido do caso, com os papéis, o cadastro consultado e o vínculo com o veículo.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"O id do envolvido.
"5e9a3c71-2b4d-4e8f-a9c0-6d1b7f2e8a35""uuid"Responses
O envolvido.
Editar um envolvido
Um PATCH: muda os papéis, o motivo, o cadastro, os metadados e o vínculo com um veículo do caso.
parentId:nullnão mexe,""desliga o vínculo, um id amarra ao veículo.reason:nullnão mexe,""apaga.valueé imutável. Se vier, tem de ser exatamente o que está gravado; qualquer outro valor é400 IDENTITY_IS_IMMUTABLE. A placa e o CPF/CNPJ são a chave pela qual o Asset, o Zarv ID e as dimensões foram consultados — corrigir é remover e incluir de novo.externalId,typeemanualnão são editáveis e são ignorados no corpo.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"O id do envolvido.
"5e9a3c71-2b4d-4e8f-a9c0-6d1b7f2e8a35""uuid"Request Body
Responses
O envolvido depois da edição.
Remover um envolvido
Tira o envolvido do caso. Remover e incluir de novo é também como se corrige uma placa ou um CPF digitado errado — e a inclusão nova consulta o cadastro outra vez, com a cobrança que vem com ela.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"O id do envolvido.
"5e9a3c71-2b4d-4e8f-a9c0-6d1b7f2e8a35""uuid"Responses
O envolvido foi removido. Sem corpo.
Análise
Rodar as nove dimensões sobre o caso coletado e acompanhar o resultado. O pedido responde 202 e um worker roda a análise; o veredito de cada dimensão sai no GET do caso.
Consultar um caso
O caso inteiro: o relato, as contagens de filhos, a raia do quadro e — o que mais importa para quem integra — o andamento das duas rotas assíncronas.
documentsé o envio dos documentos: o status, o progresso de 0 a 100, o resultado de cada arquivo (saved,read,read_failedouleft_out, com o motivo) e a montagem do caso (documents.assembly), em que a reconciliação transforma as leituras em envolvidos e preenche o relato.analysisé a análise: o status, o código do erro quando falhou e oresult, com um campo por dimensão (dimdocumental,dimchronology, …).
Caso sem envio tem documents com a mesma forma, vazia; caso sem análise tem analysis.status vazio e result nulo. Nenhuma lista sai null.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Responses
O caso, com o envio dos documentos e a análise.
Pedir a análise do caso
Põe a análise do caso na fila e responde 202 na hora. Não tem corpo.
Um worker dentro da API enriquece o segurado e o terceiro (ZarvID e Asset) e roda as nove dimensões sobre o caso montado — os documentos, as leituras e os envolvidos. Cada dimensão grava o resultado dela assim que termina, então uma análise parcial já é legível. Isso leva minutos: nada disso cabe no tempo de uma requisição HTTP.
O andamento e o resultado saem no GET do caso, em analysis. O caso vai para a raia Analisando no pedido, e para Analisado ou Análise falhou no fim.
Uma análise por vez. Pedir outra 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. Pedir uma análise num caso já analisado é permitido — ela substitui a anterior, e cada dimensão sobrescreve o campo dela.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Responses
A análise entrou na fila.
Investigação
A etapa depois da análise: anexar a evidência que responde a um alerta, incluir o envolvido que a apuração revelou, pedir uma nova análise e mover o caso para o desfecho (Aprovado ou Reprovado).
Editar o caso e movê-lo no quadro
Um PATCH do caso: o campo ausente (ou null) não muda, e string vazia não apaga. status, userId, domain e workspaceId não são campos editáveis — vindos no corpo, são ignorados.
kanbanId move o caso para outra raia do quadro. A raia precisa ser uma linha ACTIVE do quadro deste workspace; qualquer outra coisa é 400. Com o envio dos documentos ou a análise rodando, o movimento é 409: naquele momento, o caso é do worker.
É por aqui que o analista dá o desfecho: mover para Aprovado ou Reprovado (fase DESFECHO), ou devolver o caso para Dados pendentes quando falta material.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Request Body
Responses
O caso depois da edição, já na raia nova.
Pedir a análise do caso
Põe a análise do caso na fila e responde 202 na hora. Não tem corpo.
Um worker dentro da API enriquece o segurado e o terceiro (ZarvID e Asset) e roda as nove dimensões sobre o caso montado — os documentos, as leituras e os envolvidos. Cada dimensão grava o resultado dela assim que termina, então uma análise parcial já é legível. Isso leva minutos: nada disso cabe no tempo de uma requisição HTTP.
O andamento e o resultado saem no GET do caso, em analysis. O caso vai para a raia Analisando no pedido, e para Analisado ou Análise falhou no fim.
Uma análise por vez. Pedir outra 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. Pedir uma análise num caso já analisado é permitido — ela substitui a anterior, e cada dimensão sobrescreve o campo dela.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Responses
A análise entrou na fila.
Enviar os documentos do caso
Envia todos os arquivos do caso de uma vez e responde 202 sem chamar modelo nenhum. Os arquivos ficam na fila e um worker os identifica, lê e grava depois. É a rota que substituiu o antigo create de um arquivo por vez.
O que o worker faz com cada arquivo
- Sem
type, o identificador de documento diz o que o arquivo é (target): apólice, BO, aviso de sinistro, termo de terceiro, CNH, CRLV, foto do local, foto do veículo ouOUTRO. OOUTROfica fora do caso. - Foto de veículo passa também pelo OCR Veículo, e a posição da foto (frente, traseira, lateral, interior, cofre do motor) é que dá o tipo do documento.
- Com
agentReader: true, o OCR do tipo lê o arquivo e grava os campos extraídos nometadatado documento, na chave do agente. - Com
autoCreate: true, a leitura entra na montagem do caso: o agente de reconciliação transforma as leituras em envolvidos e preenche o relato (vejadocuments.assemblynoGETdo caso).autoCreateexigeagentReader— sem leitura não há o que montar.
Limites
| Limite | Valor |
|---|---|
| Arquivos por envio | 40 |
| Tamanho de um arquivo (decodificado) | 10 MB |
| Soma dos arquivos (decodificados) | 50 MB |
| Formatos | application/pdf, image/jpeg, image/png, image/webp |
O corpo inteiro é cortado em cerca de 67,7 MB antes de ser lido — o Base64 dos 50 MB mais folga para o resto do JSON. Passar disso é 413.
Um envio por vez
Há um envio por caso. Mandar outro com um em andamento é 409 RESEARCH_DOCUMENTS_IN_PROGRESS. O andamento sai no GET do caso, em documents.
Um arquivo recusado leva o índice dele no corpo do erro (index), para o front saber qual corrigir sem ler a frase.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Request Body
Responses
O envio entrou na fila.
Incluir um envolvido
Põe uma pessoa, uma empresa ou um veículo no caso, com os papéis dela.
A consulta do cadastro
Criar um envolvido consulta um provedor pago e guarda o resultado em profile:
| Tipo | value |
Consulta | Chave em profile |
|---|---|---|---|
PERSON |
CPF | Dataset do Zarv ID v3 (PF) | dataset |
COMPANY |
CNPJ | Dataset do Zarv ID v3 (PJ) | dataset |
VEHICLE |
Placa | Zarv Asset | asset |
O CPF ou o CNPJ é conferido (tamanho e dígito verificador) antes da consulta: um erro de digitação é 400, e não uma consulta cobrada. A consulta vem depois de todas as conferências e antes de gravar — o que seria recusado não é cobrado, e uma consulta que falha não grava nada (502).
As regras da árvore
- O
VEHICLEé sempre raiz: ele não temparentId. - A
COMPANYsó fica sob umVEHICLE. - O
parentIdtem de ser um envolvido deste caso.
Duas regras que evitam caso duplicado
- Dentro do caso: se já existe um envolvido com esse
value, a chamada devolve o que já está lá, sem gravar de novo e sem consultar. - Entre casos: uma placa que já está num caso em aberto do mesmo workspace é recusada com
409 VEHICLE_IN_OPEN_RESEARCH, e o corpo traz oresearchIddaquele caso — é para onde as evidências devem ir.
value é obrigatório no VEHICLE (a placa). Em PERSON e COMPANY o documento é opcional: uma testemunha pode não ter.
O envolvido criado por aqui nasce manual: true — foi declarado, não descoberto. O que a montagem do caso cria a partir das leituras nasce manual: false.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"Request Body
Responses
O envolvido entrou no caso.
Editar um envolvido
Um PATCH: muda os papéis, o motivo, o cadastro, os metadados e o vínculo com um veículo do caso.
parentId:nullnão mexe,""desliga o vínculo, um id amarra ao veículo.reason:nullnão mexe,""apaga.valueé imutável. Se vier, tem de ser exatamente o que está gravado; qualquer outro valor é400 IDENTITY_IS_IMMUTABLE. A placa e o CPF/CNPJ são a chave pela qual o Asset, o Zarv ID e as dimensões foram consultados — corrigir é remover e incluir de novo.externalId,typeemanualnão são editáveis e são ignorados no corpo.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id do caso.
"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f""uuid"O id do envolvido.
"5e9a3c71-2b4d-4e8f-a9c0-6d1b7f2e8a35""uuid"Request Body
Responses
O envolvido depois da edição.
Quadro
As raias do quadro kanban do workspace, nas três fases (COLETA, ANALISE e DESFECHO). O quadro nasce pronto, com nove raias, na primeira leitura.
Listar as raias do quadro
As raias do quadro do workspace, num array na ordem do quadro: primeiro a fase (COLETA, ANALISE, DESFECHO), depois o order dentro da fase e, no empate, a criação. Não há paginação — o quadro tem poucas raias.
O quadro nasce na primeira leitura. Um workspace que nunca leu o quadro recebe as nove raias padrão gravadas nesta chamada, com o autor system:
| Fase | Raias |
|---|---|
COLETA |
Abertura · Dados pendentes · Dados inconsistentes · Pronto para análise |
ANALISE |
Analisando · Análise falhou · Analisado |
DESFECHO |
Reprovado · Aprovado |
Os ids das nove são estáveis: derivam do workspace, da fase e do nome, então são os mesmos em toda leitura. Duas chamadas simultâneas gravam cada raia uma única vez.
Use o id da raia no ?kanbanId= da listagem de casos para montar cada coluna, e no kanbanId do PUT do caso para mover um caso.
Raias INACTIVE continuam na lista: esconder é decisão do cliente.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"Responses
As raias do quadro, na ordem.
Consultar uma raia
Uma raia do quadro do workspace. Uma raia de outro workspace responde 403, como um caso de outro workspace.
Authorizations
Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.
Parameters
Path Parameters
O workspace dono do caso. Tem de ser o workspace do token.
"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607""uuid"O id da raia.
"uuid"Responses
A raia.