Infrações - 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	CNH Digital	FICI
`pending`	Aguardando processamento interno.
`review`	Documentação em revisão interna antes do protocolo no órgão autuador.	—	Documentação assinada em revisão interna antes do protocolo no órgão autuador.
`accepted`	Indicação concluída.	O condutor aceitou e as penalidades são transferidas.	O órgão autuador deferiu a indicação.
`filed`	Indicação submetida e aguardando retorno.	Aguardando a aceitação pelo condutor no app CNH do Brasil.	Formulário protocolado, aguardando o parecer do órgão autuador.
`expired`	Prazo da indicação ultrapassado.
`rejected`	Indicação rejeitada.	Rejeitada pelo condutor.	Rejeitada pelo órgão autuador.
`failed`	Falha no processamento. O motivo fica em status_reason.
`voided`	Impedida pelo órgão de trânsito. O motivo fica em status_reason.
`canceled`	Indicação cancelada.

Name

status_reason

Type

enum | null

Description

Motivo do status da indicação. null quando não há motivo.

Valor	Descrição
`deadline_exceeded`	Prazo para indicação ultrapassado.
`already_indicated`	Condutor já foi indicado para essa infração.
`account_disconnected`	Conta desconectada.
`recognition_registered`	Reconhecimento do cometimento já registrado.
`suspended_or_canceled`	Infração suspensa ou cancelada.
`indication_pending`	Já existe indicação de real infrator pendente.
`offender_recognized`	Infrator já reconheceu o cometimento.
`driver_not_found`	CPF informado sem conta.

Name
status_reason_description
Type
string | null
Description
Motivo do status da indicação. null quando não há motivo.
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
cancelable
Type
boolean
Description
Indica se a indicação pode ser cancelada agora. true no fluxo automated quando o status é pending ou filed, e no fluxo form quando o status é pending ou review. Nos demais casos o cancelamento responde 409.
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_reason_description": null,
      "status_label": null,
      "status_description": null,
      "tax_id": "12345678901",
      "name": "João da Silva",
      "flow": "form",
      "email": "[email protected]",
      "phone": "11999999999",
      "license": "12345678901",
      "id_number": "12.345.678-9",
      "id_issuer": "SESP/SP",
      "transfer": true,
      "external": false,
      "cancelable": 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 - 403

{
  "error": "Forbidden",
  "message": "User is inactive for this organization"
}

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_reason_description": null,
    "status_label": null,
    "status_description": null,
    "tax_id": "12345678901",
    "name": "João da Silva",
    "flow": "form",
    "email": "[email protected]",
    "phone": "11999999999",
    "license": "12345678901",
    "id_number": "12.345.678-9",
    "id_issuer": "SESP/SP",
    "transfer": true,
    "external": false,
    "cancelable": 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 - CNH Digital

Cria uma indicação de condutor para transferir a responsabilidade de uma infração de trânsito. A indicação é processada automaticamente junto ao órgão de trânsito via integração direta.

Regras de Validação

Só é possível processar uma indicação, ao mesmo tempo, por infração. Caso a infração já tenha uma indicação em processamento, e seja necessário mudar o condutor indicado, é necessário cancelar a indicação atual e criar uma nova.

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
Required
obrigatório
Description
Fluxo da indicação. Use automated.

Sandbox

No ambiente sandbox, o último dígito do CPF (tax_id) determina o status final da indicação.

Último dígito	`status`
`0`	`accepted`
`1`	`filed`
`2`	`expired`
`3`	`rejected`
`4`	`failed`
`5` a `9`	`canceled`

Resposta

Name
data.id
Type
number
Description
ID da indicação.
Name
data.status
Type
enum
Description
Status da indicação. Na criação, pending.
Name
data.status_reason
Type
enum | null
Description
Motivo do status. Usa os mesmos valores de status_reason. null na criação.
Name
data.status_reason_description
Type
string | null
Description
Motivo do status da indicação. null na criação.
Name
data.status_label
Type
string | null
Description
Rótulo do status definido pela organização. null quando nenhuma regra corresponde.
Name
data.status_description
Type
string | null
Description
Descrição do status definida pela organização. null quando nenhuma regra corresponde.
Name
data.tax_id
Type
string
Description
CPF do condutor indicado (11 dígitos).
Name
data.flow
Type
enum
Description
Fluxo da indicação. Sempre automated.
Name
data.external
Type
boolean
Description
true quando a indicação foi criada fora da API. Neste endpoint, false.
Name
data.created_at
Type
string
Description
Data e hora de criação, no formato ISO-8601.
Name
data.updated_at
Type
string
Description
Data e hora da última atualização, no formato ISO-8601.

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"
  }'

Response - 201

{
  "data": {
    "id": 5,
    "status": "pending",
    "status_reason": null,
    "status_reason_description": null,
    "status_label": null,
    "status_description": null,
    "tax_id": "12345678901",
    "flow": "automated",
    "external": false,
    "cancelable": true,
    "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"
}

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

Cria uma indicação de condutor para transferir a responsabilidade de uma infração de trânsito. Um documento de assinatura digital é gerado para o condutor indicado. O condutor deve assinar o documento.

Regras de Validação

Só é possível processar uma indicação, ao mesmo tempo, por infração. Caso a infração já tenha uma indicação em processamento, e seja necessário mudar o condutor indicado, é necessário cancelar a indicação atual e criar uma nova.
Quando driver_id é informado, a empresa da infração deve ter cadastrado um documento de tipo representative com status diferente de invalid, expired e rejected. Caso contrário a API responde 422 com mensagem específica.
Quando driver_id é informado, a empresa da infração deve ter cadastrado um documento de tipo representation com status diferente de invalid, expired e rejected. Caso contrário a API responde 422 com mensagem específica. A validação de cada tipo é independente.

Parâmetros de Rota

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

Corpo da Requisição

Name
driver_id
Type
number
Required
obrigatório
Description
ID positivo do condutor indicado. O condutor deve estar vinculado à empresa à qual a infração foi aplicada e ter CNH com document.status = valid. CPF e demais dados são carregados do cadastro. A empresa deve ter documentos representative e representation com status diferente de invalid, expired e rejected.
Name
flow
Type
enum
Required
obrigatório
Description
Fluxo da indicação. Use form.
Name
transfer
Type
boolean
Required
obrigatório
Description
Indica se a responsabilidade da infração deve ser transferida ao condutor via documento de assinatura digital. Quando true, o documento FICI é gerado para o condutor assinar.
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 no formato internacional E.164, com + e código do país (ex.: +5511987654321).

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 '{
    "driver_id": 42,
    "flow": "form",
    "transfer": true
  }'

Response - 201

{
  "data": {
    "id": 5,
    "status": "pending",
    "status_reason": null,
    "status_reason_description": null,
    "status_label": "Aguardando assinatura",
    "status_description": "A indicação foi criada e aguarda a assinatura do condutor.",
    "flow": "form",
    "transfer": true,
    "external": false,
    "cancelable": 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 - 404 — driver não encontrado

{
  "error": "Not Found",
  "message": "Driver with id 42 not found"
}

Response - 409

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

Response - 422 — CNH não cadastrada

{
  "error": "Unprocessable Entity",
  "message": "Indication Not Allowed: driver document is required"
}

Response - 422 — documento representative

{
  "error": "Unprocessable Entity",
  "message": "company representative document is missing or has status invalid, expired, or rejected"
}

Response - 422 — documento representation

{
  "error": "Unprocessable Entity",
  "message": "company representation document is missing or has status invalid, expired, or rejected"
}

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

Cancelar Indicação

Cancela a indicação quando cancelable é true:

fluxo automated: status pending ou filed
fluxo form: status pending ou review

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

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": "Indication cannot be canceled in its current status"
}

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": "[email protected]",
          "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.

Name
traffic_violation
Type
object
Description
Infração à qual a indicação pertence.
- Name
  id
  Type
  number
  Description
  ID único da infração.
- Name
  ait
  Type
  string
  Description
  Auto de Infração de Trânsito (AIT).
Name
company
Type
object | null
Description
Empresa associada à infração.
- Name
  id
  Type
  number
  Description
  ID da empresa.
- Name
  tax_id
  Type
  string
  Description
  CNPJ da empresa.
- Name
  external_uid
  Type
  string
  Description
  Identificador externo da empresa.
Name
user
Type
object | null
Description
Usuário associado à infração.
- Name
  id
  Type
  number
  Description
  ID do usuário na organização.
- Name
  external_uid
  Type
  string
  Description
  Identificador externo do usuário.

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_reason_description": null,
    "status_label": null,
    "status_description": null,
    "tax_id": "12345678901",
    "name": "João da Silva",
    "flow": "form",
    "email": "[email protected]",
    "phone": "11999999999",
    "license": "12345678901",
    "id_number": "12.345.678-9",
    "id_issuer": "SESP/SP",
    "transfer": true,
    "external": false,
    "cancelable": true,
    "document_token": "abc123token",
    "document_status": "pending",
    "signer_token": "signer456token",
    "sign_url": "https://assinar.habilitar.me/verificar/abc123token",
    "document_signed_at": null,
    "traffic_violation": {
      "id": 1,
      "ait": "AIT123456789"
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z",
    "company": {
      "id": 1,
      "tax_id": "12345678000190",
      "external_uid": "12345"
    },
    "user": {
      "id": 1,
      "external_uid": "EXT_USER_12345"
    }
  }
}

Indicação em revisão (review)

{
  "type": "traffic-violation.indication.updated",
  "data": {
    "id": 1,
    "status": "review",
    "status_reason": null,
    "status_reason_description": null,
    "status_label": null,
    "status_description": null,
    "tax_id": "12345678901",
    "name": "João da Silva",
    "flow": "form",
    "email": "[email protected]",
    "phone": "11999999999",
    "license": "12345678901",
    "id_number": "12.345.678-9",
    "id_issuer": "SESP/SP",
    "transfer": true,
    "external": false,
    "cancelable": 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",
    "traffic_violation": {
      "id": 1,
      "ait": "AIT123456789"
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-16T09:00:00.000Z",
    "company": {
      "id": 1,
      "tax_id": "12345678000190",
      "external_uid": "12345"
    },
    "user": {
      "id": 1,
      "external_uid": "EXT_USER_12345"
    }
  }
}

CPF sem conta

{
  "type": "traffic-violation.indication.updated",
  "data": {
    "id": 1,
    "status": "failed",
    "status_reason": "driver_not_found",
    "status_reason_description": "O CPF informado não possui conta.",
    "status_label": null,
    "status_description": null,
    "tax_id": "12345678901",
    "name": "João da Silva",
    "flow": "form",
    "email": "[email protected]",
    "phone": "11999999999",
    "license": "12345678901",
    "id_number": "12.345.678-9",
    "id_issuer": "SESP/SP",
    "transfer": true,
    "external": false,
    "cancelable": false,
    "document_token": "abc123token",
    "document_status": "refused",
    "signer_token": "signer456token",
    "sign_url": "https://assinar.habilitar.me/verificar/abc123token",
    "document_signed_at": null,
    "traffic_violation": {
      "id": 1,
      "ait": "AIT123456789"
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-16T10:15:00.000Z",
    "company": {
      "id": 1,
      "tax_id": "12345678000190",
      "external_uid": "12345"
    },
    "user": {
      "id": 1,
      "external_uid": "EXT_USER_12345"
    }
  }
}