Indicações

A API de Indicações permite listar e criar indicações de condutores para infrações. 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.
`review`	Documento assinado por todos os signatários; em revisão interna de documentação antes de protocolar.
`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.
`voided`	Impedida pelo órgão de trânsito.
`canceled`	Indicação cancelada.

Name
status_reason
Type
string
Description
Motivo do status da indicação.
Name
status_label
Type
string
Description
Rótulo personalizado do status, definido pela sua organização. null quando nenhuma regra corresponde ao status atual.
Name
status_description
Type
string
Description
Descrição em linguagem natural do status, definida pela sua organização. null quando nenhuma regra corresponde ao status atual.
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
external
Type
boolean
Description
Indica que a indicação foi criada fora do nosso sistema. Quando true, a indicação é apenas observada e seu status é monitorado automaticamente.
Name
document_token
Type
string
Description
Token do documento de assinatura. Presente no fluxo form.

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

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 por todos os signatários no ZapSign. Quando esse estado é atingido, o `status` da indicação transita automaticamente para `review` (revisão interna).
`refused`	Documento recusado pelo condutor.
`expired`	Documento expirado sem assinatura no prazo configurado no ZapSign.

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
requester_email
Type
string
Description
E-mail do solicitante da indicação.
Name
requester_phone
Type
string
Description
Telefone do solicitante da indicação.
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.

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,
      "status_label": null,
      "status_description": 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,
      "external": false,
      "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,
    "status_label": null,
    "status_description": 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,
    "external": false,
    "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).
Name
requester_email
Type
string
Description
E-mail do solicitante da indicação.
Name
requester_phone
Type
string
Description
Telefone do solicitante da indicação.

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,
    "status_label": "Aguardando assinatura",
    "status_description": "A indicação foi criada e aguarda a assinatura do condutor.",
    "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,
    "external": false,
    "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 todos os signatários assinam o documento, document_status transita para signed e o status da indicação transita automaticamente para review.

Name
traffic-violation.indication.created
Description
Uma nova indicação foi criada.
Name
traffic-violation.indication.updated
Description
Uma indicação foi atualizada.

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, expired.
Name
document_signed_at
Type
string
Description
Data e hora em que o último signatário concluiu a assinatura (ISO 8601).

Indicação criada

{
  "type": "traffic-violation.indication.created",
  "data": {
    "id": 1,
    "status": "pending",
    "status_reason": null,
    "status_label": null,
    "status_description": 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,
    "external": false,
    "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"
  }
}

Indicação em revisão (review)

{
  "type": "traffic-violation.indication.updated",
  "data": {
    "id": 1,
    "status": "review",
    "status_reason": null,
    "status_label": null,
    "status_description": 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,
    "external": false,
    "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",
    "status_label": null,
    "status_description": 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,
    "external": false,
    "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

Indicação em revisão (review)

Documento recusado

Fluxo `automated`

Fluxo `form` (FICI)