Indicações

A API de Indicações permite listar e criar indicações de condutores para infrações conectadas à sua organização. As indicações são gerenciadas no contexto de uma infração específica.

Propriedades

Name
id
Type
number
Description
ID único da indicação.

Name

status

Type

enum

Description

Status atual da indicação.

Valor	Descrição
`pending`	Aguardando ação do condutor indicado.
`accepted`	Indicação aceita pelo condutor indicado.
`filed`	Indicação protocolada.
`expired`	Indicação expirada por falta de ação do condutor indicado.
`rejected`	Indicação rejeitada pelo condutor indicado.
`failed`	Indicação falhou.
`canceled`	Indicação cancelada.

Name
status_reason
Type
string
Description
Motivo do status da indicação.
Name
tax_id
Type
string
Description
CPF do condutor indicado (11 dígitos).
Name
name
Type
string
Description
Nome do condutor indicado.
Name
flow
Type
enum
Description
Fluxo de indicação.
Valor Descrição
automated Automático (processamento automático).
form Formulário (processamento manual).
Name
email
Type
string
Description
E-mail do condutor indicado.
Name
phone
Type
string
Description
Telefone do condutor indicado.
Name
license
Type
string
Description
Número da CNH do condutor indicado. Presente no fluxo form.
Name
id_number
Type
string
Description
Número do RG do condutor indicado. Presente no fluxo form.
Name
id_issuer
Type
string
Description
Órgão emissor do RG (ex: SESP/SP). Presente no fluxo form.
Name
transfer
Type
boolean
Description
Indica se a responsabilidade da infração foi transferida ao condutor via documento de assinatura digital. Quando true, um documento FICI é gerado automaticamente. Presente no fluxo form.
Name
document_token
Type
string
Description
Token do documento de assinatura. Presente no fluxo form.
Name
document_status
Type
string
Description
Status do documento de assinatura. Presente no fluxo form.
Valor Descrição
pending Documento aguardando assinatura.
signed Documento assinado pelo condutor.
refused Documento recusado pelo condutor.
Name
signer_token
Type
string
Description
Token do assinante no documento de assinatura. Presente no fluxo form.
Name
sign_url
Type
string
Description
URL para assinatura do documento. Presente no fluxo form.
Name
document_signed_at
Type
string
Description
Data e hora da assinatura do documento. Presente no fluxo form.
Name
vars
Type
object
Description
Variáveis utilizadas no preenchimento dos templates de documento. Objeto chave-valor onde as chaves são os nomes das variáveis e os valores são strings.
Name
created_at
Type
string
Description
Data e hora de criação da indicação.
Name
updated_at
Type
string
Description
Data e hora da última atualização da indicação.

Valor	Descrição
`automated`	Automático (processamento automático).
`form`	Formulário (processamento manual).

Valor	Descrição
`pending`	Documento aguardando assinatura.
`signed`	Documento assinado pelo condutor.
`refused`	Documento recusado pelo condutor.

GET/v1/traffic-violations/{id}/indications

Listar Indicações

Retorna a lista de indicações de condutor para uma infração de trânsito específica.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID da infração de trânsito.

Request

GET

/v1/traffic-violations/{id}/indications

curl https://api.habilitar.me/v1/traffic-violations/1/indications \
  -H "x-api-key: {token}"

Response - 200

{
  "data": [
    {
      "id": 1,
      "status": "pending",
      "status_reason": null,
      "tax_id": "12345678901",
      "name": "João da Silva",
      "flow": "form",
      "email": "condutor@email.com",
      "phone": "11999999999",
      "license": "12345678901",
      "id_number": "12.345.678-9",
      "id_issuer": "SESP/SP",
      "transfer": true,
      "document_token": "abc123token",
      "document_status": "pending",
      "signer_token": "signer456token",
      "sign_url": "https://assinar.habilitar.me/verificar/abc123token",
      "document_signed_at": null,
      "vars": null,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T14:45:00.000Z"
    }
  ]
}

Response - 404

{
  "error": "Not Found",
  "message": "Traffic violation with id 123 not found"
}

GET/v1/traffic-violations/{id}/indications/{indicationId}

Detalhar Indicação

Retorna os detalhes de uma indicação de condutor específica para uma infração de trânsito.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID da infração de trânsito.
Name
indicationId
Type
number
Required
obrigatório
Description
ID da indicação de condutor.

Request

GET

/v1/traffic-violations/{id}/indications/{indicationId}

curl https://api.habilitar.me/v1/traffic-violations/1/indications/5 \
  -H "x-api-key: {token}"

Response - 200

{
  "data": {
    "id": 5,
    "status": "pending",
    "status_reason": null,
    "tax_id": "12345678901",
    "name": "João da Silva",
    "flow": "form",
    "email": "condutor@email.com",
    "phone": "11999999999",
    "license": "12345678901",
    "id_number": "12.345.678-9",
    "id_issuer": "SESP/SP",
    "transfer": true,
    "document_token": "abc123token",
    "document_status": "pending",
    "signer_token": "signer456token",
    "sign_url": "https://assinar.habilitar.me/verificar/abc123token",
    "document_signed_at": null,
    "vars": {
      "CHARGE_AMOUNT": "195.10",
      "CHARGE_INSTALLMENTS": "3"
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "Indication or traffic violation not found"
}

POST/v1/traffic-violations/{id}/indications

Criar Indicação

Cria uma indicação de condutor para transferir a responsabilidade de uma infração de trânsito.

O processamento ocorre de forma assíncrona — o status da indicação será atualizado conforme o fluxo avança.

Regras de Validação

O status da infração deve ser pending ou citation.
A data atual deve ser anterior ou igual ao prazo de indicação (indication_deadline).
Só é permitida uma indicação pendente por infração (retorna 409 caso já exista).

Fluxo `automated`

A indicação é processada automaticamente junto ao órgão de trânsito via integração direta.

Fluxo `form` (FICI)

Um documento de assinatura digital é gerado e enviado ao condutor indicado por e-mail e WhatsApp. O condutor deve assinar o documento e pode anexar sua CNH Digital. Os campos name, license, id_number e id_issuer são obrigatórios neste fluxo.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID da infração de trânsito.

Corpo da Requisição

Name
tax_id
Type
string
Required
obrigatório
Description
CPF do condutor a ser indicado (11 dígitos).
Name
flow
Type
enum
Description
Fluxo da indicação. Padrão: automated.
Valor Descrição
automated Processamento automático via integração com o órgão de trânsito.
form Formulário FICI com assinatura digital. Requer os campos de identificação do condutor.
Name
email
Type
string
Description
E-mail do condutor indicado. Recomendado para envio de notificações.
Name
phone
Type
string
Description
Telefone do condutor indicado (somente dígitos, com DDD). Recomendado para envio de notificações via WhatsApp.
Name
name
Type
string
Description
Nome completo do condutor indicado. Obrigatório no fluxo form.
Name
license
Type
string
Description
Número de registro da CNH do condutor indicado. Obrigatório no fluxo form.
Name
id_number
Type
string
Description
Número do RG do condutor indicado. Obrigatório no fluxo form.
Name
id_issuer
Type
string
Description
Órgão emissor do RG (ex: SESP/SP). Obrigatório no fluxo form.
Name
transfer
Type
boolean
Description
Indica se a responsabilidade da infração deve ser transferida ao condutor via documento de assinatura digital. Obrigatório no fluxo form. Quando true, o documento FICI é gerado e enviado ao condutor por e-mail e WhatsApp para assinatura.
Name
documents
Type
number[]
Description
IDs dos modelos de documento (document-template) a serem utilizados no envelope de assinatura.
Name
vars
Type
object
Description
Objeto chave-valor com variáveis de preenchimento para os templates de documento. As variáveis são aplicadas a todos os documentos listados em documents. Os valores podem ser string ou number (números são convertidos automaticamente para texto).

Valor	Descrição
`automated`	Processamento automático via integração com o órgão de trânsito.
`form`	Formulário FICI com assinatura digital. Requer os campos de identificação do condutor.

Request

POST

/v1/traffic-violations/{id}/indications

curl -X POST https://api.habilitar.me/v1/traffic-violations/1/indications \
  -H "x-api-key: {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_id": "12345678901",
    "flow": "automated",
    "email": "condutor@email.com",
    "phone": "11999999999"
  }'

Response - 201

{
  "data": {
    "id": 5,
    "status": "pending",
    "status_reason": null,
    "tax_id": "12345678901",
    "name": "João da Silva",
    "flow": "form",
    "email": "condutor@email.com",
    "phone": "11999999999",
    "license": "12345678901",
    "id_number": "12.345.678-9",
    "id_issuer": "SESP/SP",
    "transfer": true,
    "document_token": "abc123token",
    "document_status": "pending",
    "signer_token": "signer456token",
    "sign_url": "https://assinar.habilitar.me/verificar/abc123token",
    "document_signed_at": null,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "Traffic violation with id 1 not found"
}

Response - 409

{
  "error": "Conflict",
  "message": "A pending indication already exists for this traffic violation"
}

Response - 422

{
  "error": "Unprocessable Entity",
  "message": "Indication Not Allowed: indication deadline has passed"
}

POST/v1/traffic-violations/{id}/indications/{indicationId}/cancel

Cancelar Indicação

Cancela uma indicação de condutor pendente. Apenas indicações com status pending podem ser canceladas.

Se houver um documento de assinatura associado no ZapSign que ainda não foi assinado, ele também será cancelado automaticamente.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID da infração de trânsito.
Name
indicationId
Type
number
Required
obrigatório
Description
ID da indicação de condutor.

Request

POST

/v1/traffic-violations/{id}/indications/{indicationId}/cancel

curl -X POST https://api.habilitar.me/v1/traffic-violations/1/indications/5/cancel \
  -H "x-api-key: {token}"

Response - 204

// No content

Response - 404

{
  "error": "Not Found",
  "message": "Indication or traffic violation not found"
}

Response - 409

{
  "error": "Conflict",
  "message": "Only pending indications can be canceled"
}

GET/v1/traffic-violations/{id}/indications/{indicationId}/document

Consultar Documento de Assinatura

Retorna os detalhes e o histórico do documento de assinatura associado a uma indicação de condutor. Disponível apenas para indicações com fluxo form.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID da infração de trânsito.
Name
indicationId
Type
number
Required
obrigatório
Description
ID da indicação de condutor.

Request

GET

/v1/traffic-violations/{id}/indications/{indicationId}/document

curl https://api.habilitar.me/v1/traffic-violations/1/indications/5/document \
  -H "x-api-key: {token}"

Response - 200

{
  "data": {
    "document_token": "abc123token",
    "document_status": "signed",
    "sign_url": "https://assinar.habilitar.me/verificar/abc123token",
    "document": {
      "token": "abc123token",
      "status": "signed",
      "name": "Indicação de Condutor - João da Silva",
      "original_file": "https://storage.habilitar.me/original.pdf",
      "signed_file": "https://storage.habilitar.me/signed.pdf",
      "created_at": "2024-01-15T10:30:00.000Z",
      "last_update_at": "2024-01-16T09:00:00.000Z",
      "signers": [
        {
          "token": "signer456token",
          "status": "signed",
          "name": "João da Silva",
          "email": "condutor@email.com",
          "times_viewed": 2,
          "last_view_at": "2024-01-16T08:55:00.000Z",
          "signed_at": "2024-01-16T09:00:00.000Z"
        }
      ]
    },
    "audit_trail": [
      {
        "created_at": "2024-01-15T10:30:00.000Z",
        "event": "document_created",
        "description": "Documento criado"
      },
      {
        "created_at": "2024-01-16T08:55:00.000Z",
        "event": "document_viewed",
        "description": "Documento visualizado pelo assinante"
      },
      {
        "created_at": "2024-01-16T09:00:00.000Z",
        "event": "document_signed",
        "description": "Documento assinado pelo condutor"
      }
    ]
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "No signing document found for this indication"
}

Eventos de Webhook

Os seguintes eventos são emitidos automaticamente quando indicações são criadas ou atualizadas. Atualizações incluem mudanças de status da indicação e do documento de assinatura.

Quando o documento de assinatura é assinado ou recusado pelo condutor, o campo document_status é atualizado automaticamente via webhook da plataforma de assinatura (ZapSign), e o evento traffic-violation.indication.updated é emitido com os novos dados.

Name
traffic-violation.indication.created
Description
Uma nova indicação foi criada.
Name
traffic-violation.indication.updated
Description
Uma indicação foi atualizada. Inclui atualizações de document_status quando o documento de assinatura é assinado (signed) ou recusado (refused).

Campos de documento no payload

Os seguintes campos estão presentes no payload do webhook quando a indicação utiliza o fluxo form com documento de assinatura:

Name
document_token
Type
string
Description
Token do documento de assinatura na plataforma ZapSign.
Name
document_status
Type
string
Description
Status atual do documento. Valores: pending, signed, refused.
Name
document_signed_at
Type
string
Description
Data e hora da assinatura do documento (ISO 8601). Preenchido quando document_status é signed.

Indicação criada

{
  "type": "traffic-violation.indication.created",
  "data": {
    "id": 1,
    "status": "pending",
    "status_reason": null,
    "tax_id": "12345678901",
    "name": "João da Silva",
    "flow": "form",
    "email": "condutor@email.com",
    "phone": "11999999999",
    "license": "12345678901",
    "id_number": "12.345.678-9",
    "id_issuer": "SESP/SP",
    "transfer": true,
    "document_token": "abc123token",
    "document_status": "pending",
    "signer_token": "signer456token",
    "sign_url": "https://assinar.habilitar.me/verificar/abc123token",
    "document_signed_at": null,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Documento assinado

{
  "type": "traffic-violation.indication.updated",
  "data": {
    "id": 1,
    "status": "pending",
    "status_reason": null,
    "tax_id": "12345678901",
    "name": "João da Silva",
    "flow": "form",
    "email": "condutor@email.com",
    "phone": "11999999999",
    "license": "12345678901",
    "id_number": "12.345.678-9",
    "id_issuer": "SESP/SP",
    "transfer": true,
    "document_token": "abc123token",
    "document_status": "signed",
    "signer_token": "signer456token",
    "sign_url": "https://assinar.habilitar.me/verificar/abc123token",
    "document_signed_at": "2024-01-16T09:00:00.000Z",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-16T09:00:00.000Z"
  }
}

Documento recusado

{
  "type": "traffic-violation.indication.updated",
  "data": {
    "id": 1,
    "status": "pending",
    "status_reason": "Documento recusado pelo signatário",
    "tax_id": "12345678901",
    "name": "João da Silva",
    "flow": "form",
    "email": "condutor@email.com",
    "phone": "11999999999",
    "license": "12345678901",
    "id_number": "12.345.678-9",
    "id_issuer": "SESP/SP",
    "transfer": true,
    "document_token": "abc123token",
    "document_status": "refused",
    "signer_token": "signer456token",
    "sign_url": "https://assinar.habilitar.me/verificar/abc123token",
    "document_signed_at": null,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-16T10:15:00.000Z"
  }
}

Indicações

Propriedades

Listar Indicações

Parâmetros de Rota

Request

Response - 200

Response - 404

Detalhar Indicação

Parâmetros de Rota

Request

Response - 200

Response - 404

Criar Indicação

Regras de Validação

Fluxo automated

Fluxo form (FICI)

Parâmetros de Rota

Corpo da Requisição

Request

Response - 201

Response - 404

Response - 409

Response - 422

Cancelar Indicação

Parâmetros de Rota

Request

Response - 204

Response - 404

Response - 409

Consultar Documento de Assinatura

Parâmetros de Rota

Request

Response - 200

Response - 404

Eventos de Webhook

Campos de documento no payload

Indicação criada

Documento assinado

Documento recusado

Fluxo `automated`

Fluxo `form` (FICI)