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/smartflow/
- 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]
v1.0.0

Zarv SmartFlow API​

Download OpenAPI Document

API para conduzir um fluxo do SmartFlow passo a passo, como um agente conversacional: descubra o fluxo, crie o lead, envie cada resposta e siga a nextStepUrl de cada resposta até a decisão. Os passos de captura (facematch e CNH) são entregues por link hospedado.

Servers​

https://services.zarv.comProdução

Fluxo​

Descoberta da definição do fluxo

Operations​

GET/api/v1/smartflow/flows/{flowId}

Descobrir fluxo​

GET
/api/v1/smartflow/flows/{flowId}

Retorna a definição do fluxo: os passos habilitados na ordem canônica (steps), quais deles são capturas com link hospedado (handoffSteps) e os campos personalizados (fields). A ordem dos passos é fixa pelo produto; um fluxo varia apenas em quais passos possui. flowId é o id do próprio fluxo, não a chave pública do embed.

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Parameters​

Path Parameters

flowId*

Identificador do fluxo (flowId).

Type
string
Required

Responses​

Definição do fluxo.

application/json
JSON
{
  
"flowId": "string",
  
"steps": [
  
  
[
  
  
  
"basic",
  
  
  
"email",
  
  
  
"phone",
  
  
  
"custom",
  
  
  
"facematch",
  
  
  
"driver-license"
  
  
]
  
],
  
"handoffSteps": [
  
  
[
  
  
  
"facematch",
  
  
  
"driver-license"
  
  
]
  
],
  
"fields": [
  
  
{
  
  
  
"id": "f_k3n8p2q7",
  
  
  
"type": "text",
  
  
  
"label": "Matrícula",
  
  
  
"required": true,
  
  
  
"maxLength": 20,
  
  
  
"options": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
]
}

Playground​

Authorization
Variables
Key
Value

Samples​

Iniciar lead​

POST
/api/v1/smartflow/leads

Cria um lead no fluxo informado e retorna o primeiro passo e a nextStepUrl a chamar. O campo externalId funciona como chave de idempotência: repetir a chamada com o mesmo valor retorna o lead já criado. Se prefill trouxer dados de identidade (name, nationalId, birthDate), é obrigatório enviar acceptedTerms: true; caso contrário a resposta é 400 com o código terms_required. Os campos utm e metadata são gravados no lead e devolvidos nas leituras de status e no webhook.

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Request Body​

application/json
JSON
{
  
"flowId": "string",
  
"externalId": "string",
  
"acceptedTerms": true,
  
"prefill": {
  
  
"name": "string",
  
  
"nationalId": "string",
  
  
"birthDate": "string",
  
  
"phone": "string",
  
  
"email": "string"
  
},
  
"utm": {
  
  
"additionalProperties": "string"
  
},
  
"metadata": {
  
  
"additionalProperties": "string"
  
}
}

Responses​

Lead criado (ou lead existente, quando externalId já foi usado).

application/json
JSON
{
  
"leadId": "lead_01HZX",
  
"status": "in_progress",
  
"step": "email",
  
"nextStep": "phone",
  
"nextStepUrl": "/api/v1/smartflow/leads/lead_01HZX/phone",
  
"progress": 40,
  
"finished": false
}

Playground​

Authorization
Body

Samples​

Consultar status do lead​

GET
/api/v1/smartflow/leads/{id}

Retorna o estado atual do lead: o envelope padrão acrescido de decision (status e data da decisão, quando já houver) e metadata (os metadados enviados na criação).

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

Identificador do lead (leadId).

Type
string
Required

Responses​

Estado atual do lead.

application/json
JSON
{
  
"leadId": "lead_01HZX",
  
"status": "in_progress",
  
"step": "email",
  
"nextStep": "phone",
  
"nextStepUrl": "/api/v1/smartflow/leads/lead_01HZX/phone",
  
"progress": 40,
  
"finished": false,
  
"decision": {
  
  
"status": "approved",
  
  
"decidedAt": "string"
  
},
  
"metadata": {
  
  
"additionalProperties": "string"
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​

Enviar dados básicos​

POST
/api/v1/smartflow/leads/{id}/basic

Envia nome completo, data de nascimento, CPF e o aceite dos termos. O servidor valida, grava e avança o lead para o próximo passo.

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

Identificador do lead (leadId).

Type
string
Required

Request Body​

application/json
JSON
{
  
"fullName": "string",
  
"birthDate": "string",
  
"nationalId": "string",
  
"hasAcceptedTerms": true
}

Responses​

Lead avançado; retorna o envelope padrão com o próximo passo.

application/json
JSON
{
  
"leadId": "lead_01HZX",
  
"status": "in_progress",
  
"step": "email",
  
"nextStep": "phone",
  
"nextStepUrl": "/api/v1/smartflow/leads/lead_01HZX/phone",
  
"progress": 40,
  
"finished": false
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​

Enviar e-mail​

POST
/api/v1/smartflow/leads/{id}/email

Registra o e-mail do lead e emite um código de verificação (OTP) para ele. O código deve ser confirmado em email/confirm.

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

Identificador do lead (leadId).

Type
string
Required

Request Body​

application/json
JSON
{
  
"email": "string"
}

Responses​

Lead avançado; retorna o envelope padrão com o próximo passo.

application/json
JSON
{
  
"leadId": "lead_01HZX",
  
"status": "in_progress",
  
"step": "email",
  
"nextStep": "phone",
  
"nextStepUrl": "/api/v1/smartflow/leads/lead_01HZX/phone",
  
"progress": 40,
  
"finished": false
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​

Confirmar e-mail​

POST
/api/v1/smartflow/leads/{id}/email/confirm

Valida o código (OTP) recebido pelo lead por e-mail.

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

Identificador do lead (leadId).

Type
string
Required

Request Body​

application/json
JSON
{
  
"code": "123456"
}

Responses​

Lead avançado; retorna o envelope padrão com o próximo passo.

application/json
JSON
{
  
"leadId": "lead_01HZX",
  
"status": "in_progress",
  
"step": "email",
  
"nextStep": "phone",
  
"nextStepUrl": "/api/v1/smartflow/leads/lead_01HZX/phone",
  
"progress": 40,
  
"finished": false
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​

Enviar telefone​

POST
/api/v1/smartflow/leads/{id}/phone

Registra o telefone do lead e emite um código de verificação (OTP) para ele. O código deve ser confirmado em phone/confirm. Não há atalho sem OTP: o telefone é verificado da mesma forma que o e-mail.

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

Identificador do lead (leadId).

Type
string
Required

Request Body​

application/json
JSON
{
  
"phone": "+5511999999999"
}

Responses​

Lead avançado; retorna o envelope padrão com o próximo passo.

application/json
JSON
{
  
"leadId": "lead_01HZX",
  
"status": "in_progress",
  
"step": "email",
  
"nextStep": "phone",
  
"nextStepUrl": "/api/v1/smartflow/leads/lead_01HZX/phone",
  
"progress": 40,
  
"finished": false
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​

Confirmar telefone​

POST
/api/v1/smartflow/leads/{id}/phone/confirm

Valida o código (OTP) recebido pelo lead no telefone.

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

Identificador do lead (leadId).

Type
string
Required

Request Body​

application/json
JSON
{
  
"code": "123456"
}

Responses​

Lead avançado; retorna o envelope padrão com o próximo passo.

application/json
JSON
{
  
"leadId": "lead_01HZX",
  
"status": "in_progress",
  
"step": "email",
  
"nextStep": "phone",
  
"nextStepUrl": "/api/v1/smartflow/leads/lead_01HZX/phone",
  
"progress": 40,
  
"finished": false
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​

Enviar endereço​

POST
/api/v1/smartflow/leads/{id}/address

Envia o endereço do lead. O servidor valida, grava e avança o lead para o próximo passo.

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

Identificador do lead (leadId).

Type
string
Required

Request Body​

application/json
JSON
{
  
"street": "string",
  
"number": "string",
  
"zip": "string",
  
"city": "string",
  
"state": "string",
  
"country": "string"
}

Responses​

Lead avançado; retorna o envelope padrão com o próximo passo.

application/json
JSON
{
  
"leadId": "lead_01HZX",
  
"status": "in_progress",
  
"step": "email",
  
"nextStep": "phone",
  
"nextStepUrl": "/api/v1/smartflow/leads/lead_01HZX/phone",
  
"progress": 40,
  
"finished": false
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​

Enviar campo personalizado​

POST
/api/v1/smartflow/leads/{id}/custom/{fieldId}

Grava um único campo personalizado por chamada, com mescla por id (não substitui os demais). A resposta traz nextCustomField com o próximo campo pendente; o step permanece custom até que todos os campos obrigatórios estejam preenchidos e só então avança. Os campos disponíveis vêm de fields em getFlow.

Campos do tipo file são enviados como multipart/form-data com o arquivo na parte file (os demais tipos usam JSON { "value": ... }). O arquivo é validado (máx. 10MB e tipo MIME conforme os grupos do campo) e armazenado; a chave do objeto vira o valor do campo. Erros: file_required, file_too_large, file_type_not_allowed (400) e upload_failed (502).

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

Identificador do lead (leadId).

Type
string
Required
fieldId*

Identificador do campo personalizado (por exemplo, f_k3n8p2q7).

Type
string
Required

Request Body​

JSON
{
  
"value": "string"
}

Responses​

Lead avançado; retorna o envelope padrão com o próximo passo.

application/json
JSON
{
  
"leadId": "lead_01HZX",
  
"status": "in_progress",
  
"step": "email",
  
"nextStep": "phone",
  
"nextStepUrl": "/api/v1/smartflow/leads/lead_01HZX/phone",
  
"progress": 40,
  
"finished": false,
  
"nextCustomField": {
  
  
"id": "f_k3n8p2q7",
  
  
"type": "text",
  
  
"label": "Matrícula",
  
  
"required": true
  
}
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​

Obter link de facematch​

GET
/api/v1/smartflow/leads/{id}/facematch-link

Quando o próximo passo é facematch, retorna o envelope padrão com handoffUrl: um link hospedado de captura (não é iframe nem SDK) para enviar ao usuário. A captura ocorre no dispositivo dele (câmera) e a conclusão é sinalizada de forma assíncrona pelo webhook lead.face.completed; depois disso, retome o fluxo.

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Path Parameters

id*

Identificador do lead (leadId).

Type
string
Required

Responses​

Envelope com o link de captura.

application/json
JSON
{
  
"leadId": "lead_01HZX",
  
"status": "in_progress",
  
"step": "email",
  
"nextStep": "phone",
  
"nextStepUrl": "/api/v1/smartflow/leads/lead_01HZX/phone",
  
"progress": 40,
  
"finished": false,
  
"handoffUrl": "string"
}
Authorization
Variables
Key
Value

Obter link de CNH​

GET
/api/v1/smartflow/leads/{id}/driver-license-link

Quando o próximo passo é driver-license, retorna o envelope padrão com handoffUrl: um link hospedado de captura da CNH para enviar ao usuário. A conclusão é sinalizada de forma assíncrona pelo webhook lead.cnh.completed; depois disso, retome o fluxo.

Authorizations​

Authentication v2

For more details, see Authentication v2

Type
HTTP (bearer)

Path Parameters

id*

Identificador do lead (leadId).

Type
string
Required

Responses​

Envelope com o link de captura.

application/json
JSON
{
  
"leadId": "lead_01HZX",
  
"status": "in_progress",
  
"step": "email",
  
"nextStep": "phone",
  
"nextStepUrl": "/api/v1/smartflow/leads/lead_01HZX/phone",
  
"progress": 40,
  
"finished": false,
  
"handoffUrl": "string"
}
Authorization
Variables
Key
Value
Powered by VitePress OpenAPI