Developers

Aparência

Vai integrar a API REST da Zarv com ajuda de IA? Copie a instrução que aponta o modelo para esta documentação.
Ver a instrução
Você vai integrar a API REST da Zarv. Use a documentação oficial como fonte da verdade.

- Página desta integração: https://developers.zarv.com/api/lens/createResearchEntity
- Autenticação Bearer JWT e hosts: https://developers.zarv.com/setup
- Índice das APIs: https://developers.zarv.com/api
- Índice da documentação em markdown: https://developers.zarv.com/llms.txt
- Documentação completa em um arquivo: https://developers.zarv.com/llms-full.txt

Os specs OpenAPI publicados são a fonte da verdade para rotas e schemas — use o spec da API que você escolher antes de escrever qualquer request.

Antes de escrever qualquer código, leia a página desta integração. Siga exatamente os nomes de campos, endpoints, callbacks e formatos que estiverem documentados — não invente parâmetros nem endpoints, e não deduza comportamento a partir de outras APIs que você conhece. Se algo de que você precisa não estiver na documentação, diga que não está em vez de supor.

Minha tarefa: [ex.: escolher a API certa e fazer a primeira chamada autenticada]

Incluir um envolvido​

POST
/api/v1/lens/{workspaceId}/research/{researchId}/entity

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 tem parentId.
  • A COMPANY só fica sob um VEHICLE.
  • O parentId tem 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 o researchId daquele 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​

BearerAuth

Token Bearer JWT obtido em POST /api/v1/authentication. O workspace do token precisa ser o mesmo do caminho.

Type
HTTP (bearer)

Parameters​

Path Parameters

workspaceId*

O workspace dono do caso. Tem de ser o workspace do token.

Type
string
Required
Example"3f1a2b4c-5d6e-4f70-8a91-b2c3d4e5f607"
Format
"uuid"
researchId*

O id do caso.

Type
string
Required
Example"7d2f8e10-4c3b-4a5d-9e8f-1a2b3c4d5e6f"
Format
"uuid"

Request Body​

application/json
JSON
{
  
"type": "VEHICLE",
  
"value": "TST1A23",
  
"roles": [
  
  
"PRINCIPAL"
  
],
  
"reason": "Veículo segurado, declarado na abertura."
}

Responses​

O envolvido entrou no caso.

application/json
JSON
{
  
"id": "string",
  
"researchId": "string",
  
"parentId": "",
  
"externalId": "",
  
"type": "PERSON",
  
"value": "TST1A23",
  
"roles": [
  
  
"SEGURADO"
  
],
  
"reason": "string",
  
"profile": {
  
  
"additionalProperties": "string"
  
},
  
"manual": true,
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​

Powered by VitePress OpenAPI