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

Eventos de Webhook

  • 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"
    },
    "organization": {
      "id": 1
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-20T14:45:00.000Z"
  }
}

Essa página foi útil?