Habilitar.me

Empresas

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

Propriedades

  • Name
    id
    Type
    number
    Description

    ID da empresa.

  • Name
    uid
    Type
    string
    Description

    Identificador único da empresa.

  • Name
    tax_id
    Type
    string
    Description

    CNPJ (14 dígitos) da empresa.

  • Name
    name
    Type
    string
    Description

    Nome da empresa.

  • 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
      representative
      Type
      object | null
      Description

      Representante legal. null quando o nome ou o CPF não estão disponíveis.

      • Name
        name
        Type
        string
        Description

        Nome do representante legal.

      • Name
        tax_id
        Type
        string
        Description

        CPF do representante legal.

  • Name
    login
    Type
    object
    Description

    Login associado à empresa.

    • Name
      id
      Type
      number
      Description

      ID do login.

    • Name
      uid
      Type
      string
      Description

      Identificador único do login.

    • Name
      status
      Type
      string
      Description

      Status do login. Valores possíveis:

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

      Indica se a sessão de login está atualmente ativa.

    • Name
      connected_at
      Type
      string
      Description

      Data e hora da última conexão bem-sucedida (ISO 8601).

    • Name
      disconnected_at
      Type
      string
      Description

      Data e hora da última desconexão (ISO 8601).

    • Name
      step
      Type
      string
      Description

      Etapa atual do processo de conexão. Em caso de falha, permanece com o valor da etapa em que o erro ocorreu.

      ValorDescrição
      credentialsValidação de credenciais
      usernameValidação de usuário
      passwordValidação de senha
      certificateValidação de certificado
      otpValidação de Código de Acesso
      completedConexão concluída
  • 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,
      "uid": "a4e1c8b2-6d3f-4a91-9c70-1b2e5f8d0a33",
      "tax_id": "12345678000190",
      "name": "Transportes ABC LTDA",
      "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",
        "representative": {
          "name": "João da Silva",
          "tax_id": "12345678901"
        }
      },
      "login": {
        "id": 1,
        "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
        "status": "success",
        "connected": true,
        "connected_at": "2026-05-07T12:34:56.000Z",
        "disconnected_at": null,
        "step": "completed"
      },
      "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 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,
    "uid": "a4e1c8b2-6d3f-4a91-9c70-1b2e5f8d0a33",
    "tax_id": "12345678000190",
    "name": "Transportes ABC LTDA",
    "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",
      "representative": {
        "name": "João da Silva",
        "tax_id": "12345678901"
      }
    },
    "login": {
      "id": 1,
      "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
      "status": "success",
      "connected": true,
      "connected_at": "2026-05-07T12:34:56.000Z",
      "disconnected_at": null,
      "step": "completed"
    },
    "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.

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

Response - 201

{
  "data": {
    "id": 1,
    "uid": "a4e1c8b2-6d3f-4a91-9c70-1b2e5f8d0a33",
    "tax_id": "12345678000195",
    "name": "Transportes ABC LTDA",
    "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 da empresa.

Corpo da Requisição

  • Name
    name
    Type
    string
    Description

    Nome da empresa.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo da empresa.

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,
    "uid": "a4e1c8b2-6d3f-4a91-9c70-1b2e5f8d0a33",
    "tax_id": "12345678000190",
    "name": "Nova Transportes LTDA",
    "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 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 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"
}
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 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"
}

Documentos

Documentos da empresa, usados na indicação via formulário FICI.

Identificação de quem representa a empresa. Tipo representative.

Tipo (document_type)Documento
driver_licenseCNH
identity_cardRG

Documento que comprova a representação legal da empresa. Tipo representation.

Tipo (document_type)Documento
bylawsEstatuto Social
articles_of_associationContrato Social
commercial_registry_certificateCertidão da Junta Comercial

Status

  • Name
    status
    Type
    enum
    Description

    Status do documento.

    ValorDescrição
    reviewDocumento em revisão. Status inicial na criação e na atualização do arquivo.
    validDocumento validado e aprovado.
    rejectedDocumento recusado. Envie outro documento em Atualizar Documento.
    invalidDocumento inválido. Envie outro documento em Atualizar Documento.
    expiredDocumento expirado. Envie outro documento em Atualizar Documento.

Motivo do Status

  • Name
    status_reason
    Type
    enum
    Description

    Justifica o status após a revisão interna. É null em review e valid.

    ValorDescrição
    illegibleDocumento ilegível ou com qualidade insuficiente para conferência.
    incompleteFaltam páginas, frente e verso ou informações obrigatórias.
    wrong_document_typeO arquivo não corresponde ao document_type informado.
    data_mismatchOs dados não conferem com a empresa ou o representante legal.
    unofficial_copyCópia não oficial, print de tela ou recorte.
    alteredHá sinais de adulteração.
    cancelledO documento foi cancelado, cassado ou baixado no órgão emissor.
    not_legal_representativeNão identifica o representante legal da empresa.
    insufficient_powersNão comprova poderes de representação da empresa.
    validity_expiredO prazo de validade do documento venceu.
    supersededFoi substituído por uma versão mais recente.
GET/v1/companies/:id/documents

Listar Documentos

Lista os documentos vinculados à empresa.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID da empresa.

Request

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

Response - 200

{
  "data": [
    {
      "id": 9,
      "type": "representative",
      "document_type": "driver_license",
      "status": "review",
      "status_reason": null,
      "file": {
        "id": 44,
        "name": "cnh.pdf",
        "mime": "application/pdf"
      },
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-20T14:45:00.000Z"
    }
  ]
}
GET/v1/companies/:id/documents/:documentId

Detalhar Documento

Retorna um documento da empresa.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID da empresa.

  • Name
    documentId
    Type
    number
    Required
    obrigatório
    Description

    ID único do documento.

Request

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

Response - 200

{
  "data": {
    "id": 9,
    "type": "representative",
    "document_type": "driver_license",
    "status": "valid",
    "status_reason": null,
    "file": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf"
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}
POST/v1/companies/:id/documents

Criar Documento

Cria o registro do documento e devolve uma URL pré-assinada para o envio do arquivo. Informe type e document. O status inicial é review.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID da empresa.

Corpo da Requisição

  • Name
    type
    Type
    enum
    Required
    obrigatório
    Description

    Tipo de documento.

    ValorDescrição
    representativeDocumento do representante legal (CNH ou RG).
    representationComprovação de representante legal (estatuto, contrato social ou certidão da junta).
  • Name
    document
    Type
    object
    Required
    obrigatório
    Description

    Metadados do arquivo para emitir a URL pré-assinada.

    • Name
      file_name
      Type
      string
      Required
      obrigatório
      Description

      Nome do arquivo (PDF, JPG ou PNG).

    • Name
      content_type
      Type
      string
      Required
      obrigatório
      Description

      application/pdf, image/jpeg ou image/png.

    • Name
      size
      Type
      integer
      Required
      obrigatório
      Description

      Tamanho em bytes (máximo 50 MB).

Resposta

  • Name
    data.id
    Type
    number
    Description

    ID do documento recém-criado.

  • Name
    data.type
    Type
    string
    Description

    Tipo de Documento.

  • Name
    data.document_type
    Type
    string
    Description

    Tipo de Documento.

  • Name
    data.status
    Type
    enum
    Description

    Status inicial de validação (review).

  • Name
    data.upload
    Type
    object
    Description

    Dados da URL pré-assinada para o envio do arquivo.

    • Name
      url
      Type
      string
      Description

      URL pré-assinada para o PUT do arquivo. Válida pelo tempo em expires_in.

    • Name
      method
      Type
      string
      Description

      Sempre PUT.

    • Name
      headers
      Type
      object
      Description

      Cabeçalhos obrigatórios no PUT, incluindo Content-Type.

    • Name
      expires_in
      Type
      number
      Description

      Validade da URL, em segundos (15 minutos).

Request

POST
/v1/companies/:id/documents
curl -X POST https://api.habilitar.me/v1/companies/1/documents \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{
    "type": "representative",
    "document": {
      "file_name": "cnh.pdf",
      "content_type": "application/pdf",
      "size": 245760
    }
  }'

Response 201

{
  "data": {
    "id": 9,
    "type": "representative",
    "document_type": null,
    "status": "review",
    "status_reason": null,
    "upload": {
      "url": "https://media.example/put?X-Amz-Signature=...",
      "method": "PUT",
      "headers": { "Content-Type": "application/pdf" },
      "expires_in": 900
    }
  }
}

Implementação recomendada

O arquivo não precisa transitar pelos seus servidores. O frontend envia só os metadados; o binário vai direto à URL pré-assinada.

  1. O usuário seleciona o arquivo. O frontend lê file_name, content_type e size e envia esses dados ao backend.
  2. O backend repassa as informações para a API habilitar.me em Criar Documento.
  3. A API habilitar.me retorna o id do documento e a URL pré-assinada em data.upload (url, method, headers, expires_in).
  4. O backend devolve essa URL ao frontend.
  5. O frontend envia o arquivo com PUT na URL pré-assinada, usando o Content-Type de data.upload.headers.

A revisão interna atualiza o status. Um evento company.document.updated informa o resultado.

Envie o arquivo via PUT na URL pré-assinada retornada em data.upload.url:

curl -X PUT "{data.upload.url}" \
  -H "Content-Type: application/pdf" \
  --data-binary @cnh.pdf

Sandbox

No ambiente sandbox, o título do arquivo (document.file_name, sem a extensão) pode forçar o resultado da revisão. O título deve ser exatamente o status desejado: valid.pdf, rejected.jpg, invalid.png ou expired.pdf.

  • Name
    valid
    Type
    string
    Description

    Define status como valid. O document_type é escolhido aleatoriamente entre os tipos de documento (driver_license, identity_card, bylaws, articles_of_association ou commercial_registry_certificate).

  • Name
    rejected
    Type
    string
    Description

    Define status como rejected. O document_type permanece null.

  • Name
    invalid
    Type
    string
    Description

    Define status como invalid. O document_type é escolhido aleatoriamente, como em valid.

  • Name
    expired
    Type
    string
    Description

    Define status como expired. O document_type é escolhido aleatoriamente, como em valid.

Exemplos: valid.pdf pode resultar em document_type = driver_license ou document_type = commercial_registry_certificate.

PUT/v1/companies/:id/documents/:documentId

Atualizar Documento

Envie document para substituir o arquivo pelo mesmo fluxo do create: metadados neste PUT, binário na URL pré-assinada. Com arquivo novo, o status volta para review.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID da empresa.

  • Name
    documentId
    Type
    number
    Required
    obrigatório
    Description

    ID único do documento.

Corpo da Requisição

  • Name
    document
    Type
    object
    Required
    obrigatório
    Description

    Metadados do arquivo para emitir a URL pré-assinada e substituir o arquivo atual.

    • Name
      file_name
      Type
      string
      Required
      obrigatório
      Description

      Nome do arquivo (PDF, JPG ou PNG).

    • Name
      content_type
      Type
      string
      Required
      obrigatório
      Description

      application/pdf, image/jpeg ou image/png.

    • Name
      size
      Type
      integer
      Required
      obrigatório
      Description

      Tamanho em bytes (máximo 50 MB).

Resposta

  • Name
    data.id
    Type
    number
    Description

    ID do documento.

  • Name
    data.type
    Type
    string
    Description

    Tipo de Documento.

  • Name
    data.document_type
    Type
    string
    Description

    Tipo de Documento.

  • Name
    data.status
    Type
    enum
    Description

    Status de validação. review quando um arquivo novo é enviado.

  • Name
    data.status_reason
    Type
    enum
    Description

    Motivo do status. null quando um arquivo novo é enviado.

  • Name
    data.upload
    Type
    object
    Description

    Presente somente quando document é enviado. URL pré-assinada para o envio do arquivo.

    • Name
      url
      Type
      string
      Description

      URL pré-assinada para o PUT do arquivo. Válida pelo tempo em expires_in.

    • Name
      method
      Type
      string
      Description

      Sempre PUT.

    • Name
      headers
      Type
      object
      Description

      Cabeçalhos obrigatórios no PUT, incluindo Content-Type.

    • Name
      expires_in
      Type
      number
      Description

      Validade da URL, em segundos (15 minutos).

Request

PUT
/v1/companies/:id/documents/:documentId
curl -X PUT https://api.habilitar.me/v1/companies/1/documents/9 \
  -H "Content-Type: application/json" \
  -H "x-api-key: {api_key}" \
  -d '{
    "document": {
      "file_name": "cnh.pdf",
      "content_type": "application/pdf",
      "size": 245760
    }
  }'

Response 200

{
  "data": {
    "id": 9,
    "type": "representative",
    "document_type": null,
    "status": "review",
    "status_reason": null,
    "file": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf"
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z",
    "upload": {
      "url": "https://media.example/put?X-Amz-Signature=...",
      "method": "PUT",
      "headers": { "Content-Type": "application/pdf" },
      "expires_in": 900
    }
  }
}
GET/v1/companies/:id/documents/:documentId/file

Baixar Arquivo do Documento

Retorna uma URL GET pré-assinada (15 minutos) para o arquivo do documento.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID da empresa.

  • Name
    documentId
    Type
    number
    Required
    obrigatório
    Description

    ID único do documento.

Request

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

Response - 200

{
  "data": {
    "url": "https://media.example/get?X-Amz-Signature=..."
  }
}
DELETE/v1/companies/:id/documents/:documentId

Remover Documento

Remove o documento e o arquivo associado.

Parâmetros de URL

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID da empresa.

  • Name
    documentId
    Type
    number
    Required
    obrigatório
    Description

    ID único do documento.

Request

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

Response - 200

{
  "data": null
}

Eventos de documento

Os eventos abaixo são enviados por webhook. O data é o documento, não o recurso empresa.

company.document.created

EVENT

Disparado quando um documento é criado. O status é o inicial de validação (review).

Payload

{
  "type": "company.document.created",
  "data": {
    "id": 9,
    "type": "representative",
    "document_type": null,
    "status": "review",
    "status_reason": null,
    "file": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf"
    },
    "company": {
      "id": 1,
      "uid": "a4e1c8b2-6d3f-4a91-9c70-1b2e5f8d0a33",
      "tax_id": "12345678000190",
      "external_uid": "EXT_12345",
      "name": "Transportes ABC LTDA"
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

company.document.updated

EVENT

Disparado quando o status, o status_reason ou o arquivo do documento mudam. valid indica aprovação; rejected pede outro envio; invalid indica documento inválido; expired indica documento expirado. O status_reason descreve o motivo.

Payload

{
  "type": "company.document.updated",
  "data": {
    "id": 9,
    "type": "representative",
    "document_type": "driver_license",
    "status": "rejected",
    "status_reason": "illegible",
    "file": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf"
    },
    "company": {
      "id": 1,
      "uid": "a4e1c8b2-6d3f-4a91-9c70-1b2e5f8d0a33",
      "tax_id": "12345678000190",
      "external_uid": "EXT_12345",
      "name": "Transportes ABC LTDA"
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}

company.document.deleted

EVENT

Disparado quando o documento é removido. O payload é o estado imediatamente antes da exclusão.

Payload

{
  "type": "company.document.deleted",
  "data": {
    "id": 9,
    "type": "representative",
    "document_type": "driver_license",
    "status": "review",
    "status_reason": null,
    "file": {
      "id": 44,
      "name": "cnh.pdf",
      "mime": "application/pdf"
    },
    "company": {
      "id": 1,
      "uid": "a4e1c8b2-6d3f-4a91-9c70-1b2e5f8d0a33",
      "tax_id": "12345678000190",
      "external_uid": "EXT_12345",
      "name": "Transportes ABC LTDA"
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

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

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 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.*, company.login.* e company.document.*) entregam o recurso completo da empresa em data, no mesmo formato do endpoint Detalhar Empresa.

Os eventos de documento estão em company.document.created, company.document.updated e company.document.deleted.

  • 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.sne.updated
    Description

    O SNE da empresa foi atualizado.

Exemplo de payload

{
  "type": "company.created",
  "data": {
    "id": 1,
    "uid": "a4e1c8b2-6d3f-4a91-9c70-1b2e5f8d0a33",
    "tax_id": "12345678000190",
    "name": "Transportes ABC LTDA",
    "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",
      "representative": {
        "name": "João da Silva",
        "tax_id": "12345678901"
      }
    },
    "login": {
      "id": 1,
      "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
      "status": "success",
      "connected": true,
      "connected_at": "2026-05-07T12:34:56.000Z",
      "disconnected_at": null,
      "step": "completed"
    },
    "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 conexão

company.login.connected

O login da empresa foi conectado com sucesso: transição de desconectado para conectado.

  • 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
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre true neste evento.

  • Name
    step
    Type
    string
    Description

    Etapa em que o login ficou. Em uma conexão bem-sucedida é completed. Os valores possíveis estão em Propriedades.

  • Name
    connected_at
    Type
    string
    Description

    Data e hora da conexão que gerou o evento (ISO 8601).

  • Name
    disconnected_at
    Type
    string
    Description

    Data e hora da desconexão anterior (ISO 8601), ou null se esta é a primeira conexão do login.

company.login.connected

{
  "type": "company.login.connected",
  "data": {
    "id": 1,
    "tax_id": "12345678000190",
    "external_uid": "EXT_12345",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": true,
    "step": "completed",
    "connected_at": "2026-05-07T12:34:56.000Z",
    "disconnected_at": null
  }
}

company.login.disconnected

O login da empresa foi desconectado: transição de conectado para desconectado, por exemplo após uma falha de autenticação ou expiração de sessã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
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento.

  • Name
    step
    Type
    string
    Description

    Etapa em que o login estava no momento da desconexão. Os valores possíveis estão em Propriedades.

  • Name
    connected_at
    Type
    string
    Description

    Data e hora da última conexão bem-sucedida, anterior a esta desconexão (ISO 8601).

  • Name
    disconnected_at
    Type
    string
    Description

    Data e hora da desconexão que gerou o evento (ISO 8601).

company.login.disconnected

{
  "type": "company.login.disconnected",
  "data": {
    "id": 1,
    "tax_id": "12345678000190",
    "external_uid": "EXT_12345",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": "otp",
    "connected_at": "2026-05-01T08:12:00.000Z",
    "disconnected_at": "2026-05-07T12:34:56.000Z"
  }
}

company.login.started

A tentativa de conexão começou. É sempre o primeiro evento da tentativa, e ainda não há etapa definida.

  • 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
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento.

  • Name
    step
    Type
    string
    Description

    Sempre null neste evento: a tentativa ainda não entrou em nenhuma etapa.

  • Name
    attempt
    Type
    number
    Description

    Sempre 1 neste evento.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora em que a tentativa começou (ISO 8601). É o marco zero para medir a duração da tentativa.

company.login.started

{
  "type": "company.login.started",
  "data": {
    "id": 1,
    "tax_id": "12345678000190",
    "external_uid": "EXT_12345",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": null,
    "attempt": 1,
    "occurred_at": "2026-08-07T13:00:00.000Z"
  }
}

company.login.step.updated

A tentativa mudou de etapa, ou repetiu a mesma etapa em uma nova tentativa — o caso de uma senha ou um código de acesso recusado. É o único evento que pode ocorrer várias vezes na mesma tentativa.

  • 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
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento: a tentativa está em andamento.

  • Name
    step
    Type
    string
    Description

    Etapa em que a tentativa acabou de entrar. Os valores possíveis estão em Propriedades.

  • Name
    attempt
    Type
    number
    Description

    Tentativa dentro desta etapa, começando em 1. Um valor maior que 1 significa que a etapa foi repetida — senha ou código de acesso recusado. Em password vai até 3 e em otp até 5; nas demais etapas é sempre 1.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora da mudança de etapa (ISO 8601).

company.login.step.updated

{
  "type": "company.login.step.updated",
  "data": {
    "id": 1,
    "tax_id": "12345678000190",
    "external_uid": "EXT_12345",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": "otp",
    "attempt": 1,
    "occurred_at": "2026-08-07T13:00:42.000Z"
  }
}

company.login.succeeded

A conta foi conectada com sucesso. É um dos quatro desfechos possíveis, e encerra a tentativa.

  • 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
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre true neste evento. É o único dos seis em que este campo é true.

  • Name
    step
    Type
    string
    Description

    Sempre completed neste evento.

  • Name
    attempt
    Type
    number
    Description

    Tentativa da última etapa, aquela que foi aceita.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora em que a conta foi conectada (ISO 8601).

company.login.succeeded

{
  "type": "company.login.succeeded",
  "data": {
    "id": 1,
    "tax_id": "12345678000190",
    "external_uid": "EXT_12345",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": true,
    "step": "completed",
    "attempt": 1,
    "occurred_at": "2026-08-07T13:01:04.000Z"
  }
}

company.login.failed

A tentativa falhou, por recusa do gov.br ou por erro técnico. É o único dos seis eventos que traz o campo error.

  • 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
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento.

  • Name
    step
    Type
    string
    Description

    Etapa em que a falha ocorreu. Os valores possíveis estão em Propriedades.

  • Name
    attempt
    Type
    number
    Description

    Tentativa em curso na etapa quando a falha ocorreu. Uma senha recusada três vezes falha com attempt igual a 3.

  • Name
    error
    Type
    string
    Description

    Descrição da falha, no mesmo texto exibido na tela de login. Presente somente neste evento.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora da falha (ISO 8601).

company.login.failed

{
  "type": "company.login.failed",
  "data": {
    "id": 1,
    "tax_id": "12345678000190",
    "external_uid": "EXT_12345",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": "otp",
    "attempt": 5,
    "error": "Não foi possível validar o código de acesso.",
    "occurred_at": "2026-08-07T13:01:36.000Z"
  }
}

company.login.abandoned

A página foi fechada antes de concluir a conexão. Diferente de company.login.expired, aqui houve uma ação explícita de sair.

  • 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
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento.

  • Name
    step
    Type
    string
    Description

    Etapa em que a pessoa estava quando fechou a página. É o campo que diz onde o funil perde gente. Os valores possíveis estão em Propriedades.

  • Name
    attempt
    Type
    number
    Description

    Tentativa em curso na etapa quando a página foi fechada.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora em que o abandono foi detectado (ISO 8601).

company.login.abandoned

{
  "type": "company.login.abandoned",
  "data": {
    "id": 1,
    "tax_id": "12345678000190",
    "external_uid": "EXT_12345",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": "password",
    "attempt": 2,
    "occurred_at": "2026-08-07T13:00:58.000Z"
  }
}

company.login.expired

A página permaneceu aberta, mas o tempo para informar a senha ou o código de acesso expirou. Diferente de company.login.abandoned, aqui ninguém fechou nada — apenas não houve resposta em tempo.

  • 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
    uid
    Type
    string
    Description

    Identificador do login.

  • Name
    service
    Type
    string
    Description

    Serviço externo do login.

  • Name
    connected
    Type
    boolean
    Description

    Sempre false neste evento.

  • Name
    step
    Type
    string
    Description

    Etapa cujo tempo de espera expirou, password ou otp — as duas etapas que aguardam algo de quem está na tela.

  • Name
    attempt
    Type
    number
    Description

    Tentativa em curso na etapa quando o tempo expirou.

  • Name
    occurred_at
    Type
    string
    Description

    Data e hora em que o tempo de espera expirou (ISO 8601).

company.login.expired

{
  "type": "company.login.expired",
  "data": {
    "id": 1,
    "tax_id": "12345678000190",
    "external_uid": "EXT_12345",
    "uid": "9f2b1c7e-4d3a-4b1e-9c88-2a7f5e6d0b31",
    "service": "govbr",
    "connected": false,
    "step": "otp",
    "attempt": 3,
    "occurred_at": "2026-08-07T13:05:12.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,
      "uid": "a4e1c8b2-6d3f-4a91-9c70-1b2e5f8d0a33",
      "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,
      "uid": "a4e1c8b2-6d3f-4a91-9c70-1b2e5f8d0a33",
      "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?