Habilitar.me

Empresas

A API de Empresas permite gerenciar as empresas da organização, incluindo o cadastro no SNE e certificados digitais.

Propriedades

  • Name
    id
    Type
    number
    Description

    ID único da empresa.

  • Name
    tax_id
    Type
    string
    Description

    CNPJ (14 dígitos) da empresa.

  • Name
    name
    Type
    string
    Description

    Nome da empresa.

  • Name
    login_username
    Type
    string
    Description

    CPF do responsável pela conexão de login.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo da empresa.

  • Name
    sne
    Type
    object
    Description

    Informações do Sistema de Notificação Eletrônica (SNE).

    • Name
      status
      Type
      string
      Description

      Status do SNE. Valores possíveis:

      ValorDescrição
      activeCadastro ativo no SNE
      inactiveCadastro inativo no SNE
      unavailableSNE não disponível
      unknownStatus desconhecido
      pendingCadastro pendente no SNE
      cancelingCancelamento em andamento
    • Name
      sign_up_date
      Type
      string
      Description

      Data de cadastro no SNE no formato "YYYY-MM-DD".

    • Name
      cancel_date
      Type
      string
      Description

      Data de cancelamento do SNE no formato "YYYY-MM-DD".

    • Name
      synced_at
      Type
      string
      Description

      Data da última sincronização com o SNE no formato ISO 8601.

  • Name
    certificate
    Type
    object
    Description

    Informações do certificado digital.

    • Name
      status
      Type
      string
      Description

      Status do certificado digital. Valores possíveis:

      ValorDescrição
      validCertificado válido
      expiredCertificado expirado
      not_providedCertificado não cadastrado.
    • Name
      issue_date
      Type
      string
      Description

      Data de emissão do certificado no formato "YYYY-MM-DD".

    • Name
      expiration_date
      Type
      string
      Description

      Data de expiração do certificado no formato "YYYY-MM-DD".

  • Name
    login
    Type
    object
    Description

    Login associado à empresa.

    • Name
      id
      Type
      number
      Description

      ID do login.

    • Name
      type
      Type
      string
      Description

      Tipo de credencial do login. Valores possíveis:

      ValorDescrição
      certificateCertificado digital
      usernameCPF do responsável
    • Name
      status
      Type
      string
      Description

      Status do login. Valores possíveis:

      ValorDescrição
      failFalha no login
      successLogin bem-sucedido
      incompleteLogin incompleto
      processingProcessando
      voidedAnulado
  • Name
    address
    Type
    object
    Description

    Endereço da empresa.

    • Name
      address
      Type
      string
      Description

      Logradouro completo (rua, número, complemento e bairro).

    • Name
      city
      Type
      string
      Description

      Cidade.

    • Name
      state
      Type
      string
      Description

      Estado (UF).

    • Name
      postal_code
      Type
      string
      Description

      CEP.

  • Name
    organization
    Type
    object
    Description

    Organização associada à empresa.

    • Name
      id
      Type
      number
      Description

      ID da organização.

  • Name
    created_at
    Type
    string
    Description

    Data de criação da empresa no formato ISO 8601.

  • Name
    updated_at
    Type
    string
    Description

    Data da última atualização da empresa no formato ISO 8601.

GET/v1/companies

Listar Empresas

Retorna uma lista paginada de todas as empresas da organização.

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[name]
    Type
    object
    Description

    Filtra por nome da empresa.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $contains
      Type
      string
      Description

      Contém o valor especificado.

    • Name
      $startsWith
      Type
      string
      Description

      Começa com o valor especificado.

  • Name
    filters[tax_id]
    Type
    object
    Description

    Filtra por CNPJ da empresa.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $contains
      Type
      string
      Description

      Contém o valor especificado.

  • Name
    filters[sne][status]
    Type
    object
    Description

    Filtra por status do SNE.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado (active, inactive, unavailable, unknown, pending, canceling).

  • Name
    filters[certificate][status]
    Type
    object
    Description

    Filtra por status do certificado digital.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado (valid, expired, not_provided).

  • Name
    filters[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.

Request

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

Response

{
  "data": [
    {
      "id": 1,
      "tax_id": "12345678000190",
      "name": "Transportes ABC LTDA",
      "login_username": "12345678000",
      "external_uid": "EXT_12345",
      "sne": {
        "status": "active",
        "sign_up_date": "2024-01-15",
        "cancel_date": null,
        "synced_at": "2024-01-20T10:30:00.000Z"
      },
      "certificate": {
        "status": "valid",
        "issue_date": "2024-01-15",
        "expiration_date": "2025-01-15"
      },
      "login": {
        "id": 1,
        "type": "certificate",
        "status": "success"
      },
      "address": {
        "address": "Avenida Paulista, 1000, Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "postal_code": "01310100"
      },
      "organization": {
        "id": 1
      },
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-20T14:45:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10
  },
  "total": 1
}
GET/v1/companies/:id

Detalhar Empresa

Retorna os detalhes de uma empresa específica por ID.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único da empresa.

Request

GET
/v1/companies/:id
curl https://api.habilitar.me/v1/companies/1 \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": {
    "id": 1,
    "tax_id": "12345678000190",
    "name": "Transportes ABC LTDA",
    "login_username": "12345678000",
    "external_uid": "EXT_12345",
    "sne": {
      "status": "active",
      "sign_up_date": "2024-01-15",
      "cancel_date": null,
      "synced_at": "2024-01-20T10:30:00.000Z"
    },
    "certificate": {
      "status": "valid",
      "issue_date": "2024-01-15",
      "expiration_date": "2025-01-15"
    },
    "login": {
      "id": 1,
      "type": "certificate",
      "status": "success"
    },
    "address": {
      "address": "Avenida Paulista, 1000, Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310100"
    },
    "organization": {
      "id": 1
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "Company with id 123 not found"
}
POST/v1/companies

Criar Empresa

Cria uma nova empresa na organização.

Corpo da Requisição

  • Name
    name
    Type
    string
    Required
    obrigatório
    Description

    Nome da empresa.

  • Name
    tax_id
    Type
    string
    Required
    obrigatório
    Description

    CNPJ da empresa (14 dígitos).

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo da empresa.

  • Name
    login_username
    Type
    string
    Description

    CPF do usuário responsável pela conexão de login.

Request

POST
/v1/companies
curl -X POST https://api.habilitar.me/v1/companies \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{
    "name": "Transportes ABC LTDA",
    "tax_id": "12345678000195",
    "external_uid": "EXT_12345",
    "login_username": "12345678901"
  }'

Response - 201

{
  "data": {
    "id": 1,
    "tax_id": "12345678000195",
    "name": "Transportes ABC LTDA",
    "login_username": "12345678901",
    "external_uid": "EXT_12345",
    "organization": {
      "id": 1
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Response - 400

{
  "error": "Bad Request",
  "message": "tax_id must be a valid Brazilian CNPJ"
}

Response - 409

{
  "error": "Conflict",
  "message": "A company with this tax_id already exists"
}
PUT/v1/companies/:id

Atualizar Empresa

Atualiza os dados de uma empresa específica.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único da empresa.

Corpo da Requisição

  • Name
    name
    Type
    string
    Description

    Nome da empresa.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo da empresa.

  • Name
    login_username
    Type
    string
    Description

    CPF do responsável pela conexão de login.

Request

PUT
/v1/companies/:id
curl -X PUT https://api.habilitar.me/v1/companies/1 \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{
    "name": "Nova Transportes LTDA"
  }'

Response - 200

{
  "data": {
    "id": 1,
    "tax_id": "12345678000190",
    "name": "Nova Transportes LTDA",
    "login_username": "12345678000",
    "external_uid": "EXT_12345",
    "organization": {
      "id": 1
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}

Response - 400

{
  "error": "Bad Request",
  "message": "At least one field must be provided for update"
}

Response - 404

{
  "error": "Not Found",
  "message": "Company with id 123 not found"
}
POST/v1/companies/:id/sne

Cadastrar no SNE

Inicia o processo de cadastro da empresa no Sistema de Notificação Eletrônica (SNE).

Fluxo Assíncrono: Esta requisição inicia o processo de cadastro. O status será atualizado conforme o processamento.

Regras

  • A empresa não pode estar com sne.status igual a "active" ou "pending"
  • A empresa deve possuir um login com login.status igual a "success"

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único da empresa.

Request

POST
/v1/companies/:id/sne
curl -X POST https://api.habilitar.me/v1/companies/1/sne \
  -H "x-api-key: {api_key}"

Response - 201

{
  "data": {
    "status": "pending",
    "sign_up_date": "2024-01-15"
  }
}

Response - 404

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

Response - 409

{
  "error": "Conflict",
  "message": "Company is already registered or has a pending registration in SNE"
}

Response - 422

{
  "error": "Unprocessable Entity",
  "message": "Company must have a login with status 'success' to sign up for SNE"
}
DELETE/v1/companies/:id/sne

Cancelar SNE

Inicia o processo de cancelamento do cadastro da empresa no Sistema de Notificação Eletrônica (SNE).

Fluxo Assíncrono: Esta requisição inicia o processo de cancelamento. O status será atualizado conforme o processamento.

Regras

  • A empresa deve estar com sne.status igual a "active" para poder cancelar
  • A empresa deve possuir um login com login.status igual a "success"

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único da empresa.

Request

DELETE
/v1/companies/:id/sne
curl -X DELETE https://api.habilitar.me/v1/companies/1/sne \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": {
    "status": "canceling",
    "cancel_date": "2024-06-15"
  }
}

Response - 404

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

Response - 422 - SNE não ativo

{
  "error": "Unprocessable Entity",
  "message": "Company must have active SNE status to cancel"
}

Response - 422 - Login inválido

{
  "error": "Unprocessable Entity",
  "message": "Company must have a login with status 'success' to cancel SNE"
}
POST/v1/companies/:id/certificate

Registrar Certificado Digital

Registra um certificado digital (PFX/P12) para a empresa, validando a senha e armazenando de forma segura.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único da empresa.

Corpo da Requisição

  • Name
    certificate
    Type
    string
    Required
    obrigatório
    Description

    Certificado digital em formato base64 (PFX/P12).

  • Name
    password
    Type
    string
    Required
    obrigatório
    Description

    Senha do certificado digital.

Request

POST
/v1/companies/:id/certificate
curl -X POST https://api.habilitar.me/v1/companies/1/certificate \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{
    "certificate": "MIIKEQIBAzCCCc0GCSqGSIb3DQEH...",
    "password": "password"
  }'

Response - 200

{
  "data": {
    "status": "valid",
    "issue_date": "2024-01-15",
    "expiration_date": "2025-01-15"
  }
}

Response - 400

{
  "error": "Bad Request",
  "message": "Invalid certificate or password"
}

Response - 404

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

Response - 422

{
  "error": "Unprocessable Entity",
  "message": "Cannot register an expired certificate. The certificate expired on 2024-01-15"
}
DELETE/v1/companies/:id/certificate

Remover Certificado Digital

Remove o certificado digital registrado para a empresa.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único da empresa.

Request

DELETE
/v1/companies/:id/certificate
curl -X DELETE https://api.habilitar.me/v1/companies/1/certificate \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": {
    "status": "not_provided"
  }
}

Response - 404

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

Response - 422

{
  "error": "Unprocessable Entity",
  "message": "Company does not have a registered certificate"
}

Sincronização inicial

Quando uma empresa conecta sua conta pela primeira vez, importamos os dados existentes (veículos e multas) em segundo plano. Os endpoints abaixo permitem acompanhar o progresso desta sincronização inicial em tempo real e ficam disponíveis apenas enquanto a importação está em andamento — depois disso retornam 404.

O snapshot de progresso possui o seguinte formato:

  • Name
    started_at
    Type
    string
    Description

    Data e hora (ISO 8601) em que a sincronização foi iniciada.

  • Name
    totals
    Type
    object
    Description

    Contagens agregadas considerando todas as tarefas: { total, completed, succeeded, failed, remaining }.

  • Name
    domains.vehicles
    Type
    object
    Description

    Mesmas contagens, restritas às tarefas de importação de veículos.

  • Name
    domains.traffic_violations
    Type
    object
    Description

    Mesmas contagens, restritas às tarefas de importação de multas.

GET/v1/companies/:id/sync/stream

Stream de sincronização

Stream Server-Sent Events (text/event-stream) que envia uma atualização do snapshot a cada vez que o progresso muda. A conexão é fechada automaticamente quando a sincronização termina.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único da empresa.

Eventos

  • Name
    progress
    Type
    snapshot
    Description

    Snapshot atual do progresso (formato descrito acima). Enviado sempre que algum contador muda.

  • Name
    done
    Type
    object
    Description

    Enviado uma única vez ao final, com o status final no formato { "status": "success" | "partial_success" | "failure" }. Em seguida a conexão é encerrada.

Autenticação: este endpoint exige o header x-api-key. A API EventSource nativa do navegador não permite enviar headers personalizados, então o exemplo abaixo só funciona quando a chamada é feita por um backend ou por um proxy que injeta o header.

Para consumir do navegador, use uma biblioteca SSE baseada em fetch que aceite headers personalizados (ex.: @microsoft/fetch-event-source) ou um proxy no seu backend que injeta o x-api-key. Não envie a chave de API via querystring.

Request

GET
/v1/companies/:id/sync/stream
curl -N https://api.habilitar.me/v1/companies/1/sync/stream \
  -H "x-api-key: {api_key}" \
  -H "Accept: text/event-stream"

Stream - exemplo

event: progress
data: { "started_at": "...", "totals": { "total": 42, "completed": 18, ... }, "domains": { ... } }

event: progress
data: { "started_at": "...", "totals": { "total": 87, "completed": 87, ... }, "domains": { ... } }

event: done
data: { "status": "success" }

Response - 404

{
  "error": "Not Found",
  "message": "No active sync for company 1"
}
GET/v1/companies/:id/sync/snapshot

Snapshot de sincronização

Retorna o snapshot mais recente do progresso em uma única requisição. Útil para integrações que preferem polling em vez de manter uma conexão SSE aberta.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID único da empresa.

Request

GET
/v1/companies/:id/sync/snapshot
curl https://api.habilitar.me/v1/companies/1/sync/snapshot \
  -H "x-api-key: {api_key}"

Response - 200

{
  "data": {
    "started_at": "2026-04-29T23:14:00.000Z",
    "totals": { "total": 77, "completed": 72, "succeeded": 70, "failed": 2, "remaining": 5 },
    "domains": {
      "vehicles":           { "total": 42, "completed": 42, "succeeded": 42, "failed": 0, "remaining": 0 },
      "traffic_violations": { "total": 35, "completed": 30, "succeeded": 28, "failed": 2, "remaining": 5 }
    }
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "No active sync for company 1"
}

Eventos de Webhook

Os eventos company.* (exceto company.sync.*) entregam o recurso completo da empresa em data, no mesmo formato do endpoint Detalhar Empresa.

  • Name
    company.created
    Description

    Uma nova empresa foi criada.

  • Name
    company.updated
    Description

    Uma empresa foi atualizada.

  • Name
    company.certificate.updated
    Description

    O certificado digital da empresa foi atualizado.

  • Name
    company.login.updated
    Description

    O login da empresa foi atualizado.

  • Name
    company.sne.updated
    Description

    O SNE da empresa foi atualizado.

Exemplo de payload

{
  "type": "company.created",
  "data": {
    "id": 1,
    "tax_id": "12345678000190",
    "name": "Transportes ABC LTDA",
    "login_username": "12345678000",
    "external_uid": "EXT_12345",
    "sne": {
      "status": "active",
      "sign_up_date": "2024-01-15",
      "cancel_date": null,
      "synced_at": "2024-01-20T10:30:00.000Z"
    },
    "certificate": {
      "status": "valid",
      "issue_date": "2024-01-15",
      "expiration_date": "2025-01-15"
    },
    "login": {
      "id": 1,
      "type": "certificate",
      "status": "success"
    },
    "address": {
      "address": "Avenida Paulista, 1000, Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310100"
    },
    "organization": {
      "id": 1
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}

Eventos de sincronização

Os eventos company.sync.* notificam o início e o término da sincronização inicial de dados da empresa. O payload sempre contém duas chaves de primeiro nível:

  • Name
    company
    Type
    object
    Description

    Identificação resumida da empresa: id, tax_id, name e external_uid.

  • Name
    sync
    Type
    object
    Description

    Dados específicos do evento (timestamps, status final e contagens). Veja abaixo as variações por tipo.

company.sync.started

A sincronização de dados de infrações e veículos da empresa foi iniciada.

  • Name
    sync.started_at
    Type
    string
    Description

    Data e hora (ISO 8601) em que a sincronização foi iniciada.

company.sync.started

{
  "type": "company.sync.started",
  "data": {
    "company": {
      "id": 1,
      "tax_id": "12345678000190",
      "external_uid": "EXT_12345",
      "name": "Transportes ABC LTDA"
    },
    "sync": {
      "started_at": "2026-04-29T23:14:00.000Z"
    }
  }
}

company.sync.completed

A sincronização de dados de infrações e veículos da empresa foi concluída (com sucesso, parcial ou falha).

  • Name
    sync.status
    Type
    string
    Description

    Status final. Valores possíveis:

    ValorDescrição
    successTodas as importações concluíram com sucesso
    partial_successPelo menos uma importação falhou, mas outras tiveram sucesso
    failureTodas as importações falharam
  • Name
    sync.started_at
    Type
    string
    Description

    Data e hora (ISO 8601) em que a sincronização foi iniciada.

  • Name
    sync.completed_at
    Type
    string
    Description

    Data e hora (ISO 8601) em que a sincronização terminou.

  • Name
    sync.totals
    Type
    object
    Description

    Contagens agregadas considerando todas as importações: { total, completed, succeeded, failed, remaining }.

  • Name
    sync.domains.vehicles
    Type
    object
    Description

    Mesmas contagens, restritas às importações de veículos.

  • Name
    sync.domains.traffic_violations
    Type
    object
    Description

    Mesmas contagens, restritas às importações de multas.

company.sync.completed

{
  "type": "company.sync.completed",
  "data": {
    "company": {
      "id": 1,
      "tax_id": "12345678000190",
      "external_uid": "EXT_12345",
      "name": "Transportes ABC LTDA"
    },
    "sync": {
      "status": "partial_success",
      "started_at": "2026-04-29T23:14:00.000Z",
      "completed_at": "2026-04-29T23:18:42.000Z",
      "totals": {
        "total": 87,
        "completed": 87,
        "succeeded": 85,
        "failed": 2,
        "remaining": 0
      },
      "domains": {
        "vehicles": {
          "total": 42,
          "completed": 42,
          "succeeded": 42,
          "failed": 0,
          "remaining": 0
        },
        "traffic_violations": {
          "total": 45,
          "completed": 45,
          "succeeded": 43,
          "failed": 2,
          "remaining": 0
        }
      }
    }
  }
}

Essa página foi útil?