Infrações

A API de Infrações permite listar e obter detalhes das infrações de condutores conectados à sua organização. As informações são coletadas através da autenticação dos usuários via widget de login.

Propriedades

Name
id
Type
number
Description
ID único da infração.
Name
ait
Type
string
Description
Auto de Infração de Trânsito (AIT).
Name
code
Type
string
Description
Código da infração.
Name
breakdown
Type
string
Description
Desdobramento da infração.
Name
license_plate
Type
string
Description
Placa do veículo autuado.
Name
description
Type
string
Description
Descrição detalhada da infração.

Name

status

Type

string

Description

Status atual da infração. Valores possíveis:

Valor	Descrição
`citation`	Infração autuada (ainda sem penalidade)
`warning`	Infração transformada em advertência
`pending`	Infração pendente de pagamento (penalidade aplicada, sem pagamento registrado)
`paid`	Infração paga
`overdue`	Infração vencida (penalidade aplicada, data de vencimento ultrapassada e ainda sem pagamento registrado)

Name
written_warning
Type
boolean
Description
Indica se a infração resultou em advertência por escrito.
Name
renainf
Type
boolean
Description
Indica se a infração está registrada no RENAINF (Registro Nacional de Infrações de Trânsito).
Name
amount
Type
number
Description
Valor em reais da infração.
Name
date
Type
string
Description
Data e hora da infração no formato "YYYY-MM-DD HH:mm:ss".
Name
violation_notice_date
Type
string
Description
Data de autuação da infração no formato "YYYY-MM-DD".
Name
penalty_notice_date
Type
string
Description
Data de notificação de penalidade no formato "YYYY-MM-DD".
Name
location
Type
string
Description
Endereço ou local onde ocorreu a infração.
Name
latitude
Type
number
Description
Latitude geográfica do local da infração.
Name
longitude
Type
number
Description
Longitude geográfica do local da infração.
Name
payment_date
Type
string
Description
Data de pagamento da infração no formato "YYYY-MM-DD".
Name
due_date
Type
string
Description
Data de vencimento da penalidade no formato "YYYY-MM-DD".
Name
indication_deadline
Type
string
Description
Data limite para indicação do infrator no formato "YYYY-MM-DD".
Name
indication_availability
Type
boolean
Description
Indica se a indicação de condutor está disponível para esta infração.
Name
preliminary_appeal_deadline
Type
string
Description
Data limite para recurso em defesa prévia no formato "YYYY-MM-DD".
Name
notice_appeal_deadline
Type
string
Description
Data limite para recurso de notificação no formato "YYYY-MM-DD".
Name
reference
Type
object
Description
Informações de referência da infração.
- Name
  legal_basis
  Type
  string
  Description
  Artigo do Código de Trânsito Brasileiro (CTB).
- Name
  severity
  Type
  string
  Description
  Gravidade da infração (ex: "minor", "medium", "serious", "very_serious").
- Name
  multiplier
  Type
  string
  Description
  Multiplicador de valor da infração.
- Name
  points
  Type
  string
  Description
  Quantidade de pontos da infração na CNH.
Name
user
Type
object
Description
Informações do usuário associado à infração.
- Name
  id
  Type
  string
  Description
  ID do usuário.
- Name
  external_uid
  Type
  string
  Description
  Identificador externo do usuário.
Name
company
Type
object
Description
Informações da empresa associada à infração.
- Name
  id
  Type
  number
  Description
  ID da empresa.
- Name
  name
  Type
  string
  Description
  Nome da empresa.
- Name
  external_uid
  Type
  string
  Description
  Identificador externo da empresa.
Name
agency
Type
object
Description
Órgão autuador da infração.
- Name
  code
  Type
  string
  Description
  Código do órgão autuador.
- Name
  name
  Type
  string
  Description
  Nome do órgão autuador.
- Name
  sne_indications
  Type
  boolean
  Description
  Indica se o órgão aceita indicação de condutor via SNE.
- Name
  sne_tickets
  Type
  boolean
  Description
  Indica se o órgão emite boletos via SNE.
Name
ticket_discount_availability
Type
object
Description
Disponibilidade de desconto para pagamento da infração.
- Name
  full
  Type
  boolean
  Description
  Indica se desconto integral (40%) está disponível.
- Name
  partial
  Type
  boolean
  Description
  Indica se desconto parcial (20%) está disponível.

GET/v1/traffic-violations/

Listar Infrações

Retorna uma lista paginada de todas as infrações.

Parâmetros de Paginação

Name
pagination[page]
Type
integer
Description
Número da página (começando em 1). Use junto com pagination[size].
Name
pagination[size]
Type
integer
Description
Tamanho da página (número de itens por página, máximo 100). Use junto com pagination[page].

Parâmetros de Filtro

Name
filters[date]
Type
object
Description
Filtra por data da infração. Formato: YYYY-MM-DD ou YYYY-MM-DD HH:mm:ss.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor especificado.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor especificado.
- Name
  $lt
  Type
  string
  Description
  Menor que o valor especificado.
- Name
  $lte
  Type
  string
  Description
  Menor ou igual ao valor especificado.
- Name
  $gt
  Type
  string
  Description
  Maior que o valor especificado.
- Name
  $gte
  Type
  string
  Description
  Maior ou igual ao valor especificado.
Name
filters[due_date]
Type
object
Description
Filtra por data de vencimento. Formato: YYYY-MM-DD.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor especificado.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor especificado.
- Name
  $lt
  Type
  string
  Description
  Menor que o valor especificado.
- Name
  $lte
  Type
  string
  Description
  Menor ou igual ao valor especificado.
- Name
  $gt
  Type
  string
  Description
  Maior que o valor especificado.
- Name
  $gte
  Type
  string
  Description
  Maior ou igual ao valor especificado.
Name
filters[license_plate]
Type
object
Description
Filtra por placa do veículo.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor especificado.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor especificado.
- Name
  $contains
  Type
  string
  Description
  Contém o valor especificado.
- Name
  $startsWith
  Type
  string
  Description
  Começa com o valor especificado.
- Name
  $endsWith
  Type
  string
  Description
  Termina com o valor especificado.
Name
filters[status]
Type
object
Description
Filtra por status da infração. Valores possíveis: citation, warning, pending, paid, overdue.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor especificado.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor especificado.
Name
filters[company][external_uid]
Type
object
Description
Filtra por identificador externo da empresa.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor especificado.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor especificado.
Name
filters[agency][code]
Type
object
Description
Filtra por código do órgão autuador.
- Name
  $eq
  Type
  string
  Description
  Igual ao valor especificado.
- Name
  $ne
  Type
  string
  Description
  Diferente do valor especificado.
Name
filters[indication_availability]
Type
object
Description
Filtra por disponibilidade de indicação de condutor.
- Name
  $eq
  Type
  boolean
  Description
  Igual ao valor especificado.

Request

GET

/v1/traffic-violations/

curl -G https://api.habilitar.me/v1/traffic-violations/ \
  -H "x-api-key: {token}" \
  -d "pagination[page]=1" \
  -d "pagination[size]=10"

Response

{
  "data": [
    {
      "id": 1,
      "ait": "AIT123456789",
      "code": "1234567890",
      "breakdown": "0",
      "license_plate": "ABC1234",
      "description": "Excesso de velocidade",
      "status": "Pendente",
      "written_warning": false,
      "renainf": true,
      "amount": 100.9,
      "date": "2024-01-01 12:00:00",
      "violation_notice_date": "2024-01-01",
      "penalty_notice_date": "2024-01-15",
      "location": "Av. Paulista, 1000 - São Paulo/SP",
      "latitude": -23.561684,
      "longitude": -46.655981,
      "payment_date": null,
      "due_date": "2024-02-01",
      "indication_deadline": "2024-01-20",
      "indication_availability": true,
      "preliminary_appeal_deadline": "2024-01-25",
      "notice_appeal_deadline": "2024-01-30",
      "reference": {
        "legal_basis": "218-I",
        "severity": "medium",
        "multiplier": "1",
        "points": "4"
      },
      "user": {
        "id": "1",
        "external_uid": "EXT_USER_12345"
      },
      "company": {
        "id": 1,
        "name": "Empresa Exemplo Ltda",
        "external_uid": "12345"
      },
      "agency": {
        "code": "1234",
        "name": "DETRAN São Paulo",
        "sne_indications": true,
        "sne_tickets": true
      },
      "ticket_discount_availability": {
        "full": true,
        "partial": false
      }
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10
  },
  "total": 1
}

GET/v1/traffic-violations/{id}

Detalhar Infração

Retorna os detalhes completos de uma infração específica.

Parâmetros de Rota

Name
id
Type
number
Required
obrigatório
Description
ID da infração que deseja consultar.

Request

GET

/v1/traffic-violations/{id}

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

Response - 200

{
  "data": {
    "id": 1,
    "ait": "AIT123456789",
    "code": "1234567890",
    "breakdown": "0",
    "license_plate": "ABC1234",
    "description": "Excesso de velocidade",
    "status": "pending",
    "written_warning": false,
    "renainf": true,
    "amount": 100.9,
    "date": "2024-01-01 12:00:00",
    "violation_notice_date": "2024-01-01",
    "penalty_notice_date": "2024-01-15",
    "location": "Av. Paulista, 1000 - São Paulo/SP",
    "latitude": -23.561684,
    "longitude": -46.655981,
    "payment_date": null,
    "due_date": "2024-02-01",
    "indication_deadline": "2024-01-20",
    "indication_availability": true,
    "preliminary_appeal_deadline": "2024-01-25",
    "notice_appeal_deadline": "2024-01-30",
    "reference": {
      "legal_basis": "218-I",
      "severity": "medium",
      "multiplier": "1",
      "points": "4"
    },
    "user": {
      "id": "1",
      "external_uid": "EXT_USER_12345"
    },
    "company": {
      "id": 1,
      "name": "Empresa Exemplo Ltda",
      "external_uid": "12345"
    },
    "agency": {
      "code": "1234",
      "name": "DETRAN São Paulo",
      "sne_indications": true,
      "sne_tickets": true
    },
    "ticket_discount_availability": {
      "full": true,
      "partial": false
    }
  }
}

Response - 404

{
  "error": "Infração não encontrada"
}

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

Indicações da Infração

Retorna uma lista paginada de todas as indicações associadas a uma infração específica.

Parâmetros de Rota

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

Request

GET

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

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

Response

{
  "data": [
    {
      "id": 1,
      "flow": "automated",
      "status": "pending",
      "result": "pending",
      "processing_status": "pending",
      "processing_description": "Aguardando processamento",
      "signature_status": "unsigned",
      "driver": {
        "id": 123,
        "name": "João Silva",
        "tax_id": "12345678900"
      },
      "traffic_violation": {
        "id": 1,
        "code": "1234567890",
        "description": "Excesso de velocidade"
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10
  },
  "total": 1
}

Response - 404

{
  "error": "Infração não encontrada"
}

GET/v1/traffic-violations/{id}/violation-notice

Notificação da Autuação

Retorna o arquivo PDF da notificação da autuação de uma infração específica.

Parâmetros de Rota

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

Request

GET

/v1/traffic-violations/{id}/violation-notice

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

Response - 200

{
  "data": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2..."
}

Response - 404

{
  "error": "Not Found",
  "message": "Violation notice for traffic violation with id 123 not found"
}

GET/v1/traffic-violations/{id}/penalty-notice

Notificação da Penalidade

Retorna o arquivo PDF da notificação da penalidade de uma infração específica.

Parâmetros de Rota

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

Request

GET

/v1/traffic-violations/{id}/penalty-notice

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

Response - 200

{
  "data": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2..."
}

Response - 404

{
  "error": "Not Found",
  "message": "Penalty notice for traffic violation with id 123 not found"
}

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

Listar Guias de Pagamento

Retorna a lista de boletos associados a 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}/tickets

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

Response - 200

{
  "data": [
    {
      "id": 1,
      "status": "issued",
      "amount": 293.47,
      "barcode": "23793381286000000000300000000402184340000029347",
      "due_date": "2026-01-28"
    }
  ]
}

Response - 404

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

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

Solicitar Guia de Pagamento

Solicita a geração de um boleto para pagamento de uma infração de trânsito. Se já existir um boleto para esta infração, a solicitação será rejeitada.

A geração do boleto ocorre de forma assíncrona. Todos os eventos relacionados à solicitação de um boleto são enviados por webhook.

Parâmetros de Rota

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

Corpo da Requisição

Name
discount
Type
string
Description
Tipo de desconto a ser aplicado no boleto. Este parâmetro está disponível para uso até a data de vencimento da infração. Após a data de vencimento, ele é ignorado. Valores possíveis:
Valor Descrição
full 40% de desconto no valor da infração (disponível até o prazo de defesa prévia)
partial 20% de desconto no valor da infração

Valor	Descrição
`full`	40% de desconto no valor da infração (disponível até o prazo de defesa prévia)
`partial`	20% de desconto no valor da infração

Request

POST

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

curl -X POST https://api.habilitar.me/v1/traffic-violations/1/tickets \
  -H "x-api-key: {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "discount": "full"
  }'

Response - 201

{
  "data": {
    "id": 1,
    "status": "pending"
  }
}

Response - 404

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

Response - 409

{
  "error": "Conflict",
  "message": "A ticket already exists for traffic violation with id 123"
}

Response - 422

{
  "error": "Unprocessable Entity",
  "message": "Ticket request is only allowed when traffic violation is available for payment"
}

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

Listar Indicações de Condutor

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": "Documento inválido",
      "tax_id": "12345678901",
      "name": "João da Silva",
      "flow": "automated",
      "email": "condutor@email.com",
      "phone": "11999999999",
      "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"
}

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

Indicar Condutor

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

A indicação ocorre de forma assíncrona. O status será atualizado conforme o processamento. Todos os eventos relacionados à indicação são enviados por webhook.

Regras de Validação

O status da infração deve ser "pending" ou "accepted"
A data atual deve ser anterior ou igual ao prazo de indicação (indication_deadline)
Se já existir uma indicação pendente para esta infração, a solicitação será rejeitada (409 Conflict)

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 que será indicado (sem formatação).
Name
flow
Type
string
Description
Fluxo de indicação. Padrão: automated. Valores possíveis:
Valor Descrição
automated Automático (aceitação simples via carteira digital).
form Formulário (requer assinatura de formulário de transferência de pontuação).
O fluxo form ainda não está disponível para uso. Previsão de liberação: 21/01/2026.
Name
email
Type
string
Description
E-mail do condutor indicado. Quando fornecido, um e-mail será enviado para o condutor.
Name
phone
Type
string
Description
Telefone do condutor indicado. Quando fornecido, um SMS será enviado para o condutor.

Valor	Descrição
`automated`	Automático (aceitação simples via carteira digital).
`form`	Formulário (requer assinatura de formulário de transferência de pontuação).

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": 1,
    "flow": "automated",
    "status": "pending",
    "tax_id": "12345678901",
    "email": "condutor@email.com",
    "phone": "11999999999"
  }
}

Response - 404

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

Response - 409

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

Response - 422

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

Eventos de Webhook

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

Exemplo de payload

{
  "type": "traffic-violation.created",
  "data": {
    "id": 1,
    "ait": "AIT123456789",
    "code": "1234567890",
    "breakdown": "0",
    "license_plate": "ABC1234",
    "description": "Excesso de velocidade",
    "status": "pending",
    "written_warning": false,
    "renainf": true,
    "amount": 100.9,
    "date": "2024-01-01 12:00:00",
    "violation_notice_date": "2024-01-01",
    "penalty_notice_date": "2024-01-15",
    "location": "Av. Paulista, 1000 - São Paulo/SP",
    "latitude": -23.561684,
    "longitude": -46.655981,
    "payment_date": null,
    "due_date": "2024-02-01",
    "indication_deadline": "2024-01-20",
    "indication_availability": true,
    "preliminary_appeal_deadline": "2024-01-25",
    "notice_appeal_deadline": "2024-01-30",
    "reference": {
      "legal_basis": "218-I",
      "severity": "medium",
      "multiplier": "1",
      "points": "4"
    },
    "user": {
      "id": "1",
      "external_uid": "EXT_USER_12345"
    },
    "company": {
      "id": 1,
      "tax_id": "12345678000190",
      "external_uid": "12345",
      "name": "Empresa Exemplo Ltda"
    },
    "agency": {
      "code": "1234",
      "name": "DETRAN São Paulo",
      "sne_indications": true,
      "sne_tickets": true
    },
    "ticket_discount_availability": {
      "full": true,
      "partial": false
    }
  }
}