Habilitar.me

Cobranças

A API de Cobranças permite listar e obter detalhes das cobranças (multas, taxas, impostos, etc.) associadas à sua organização. As cobranças podem ser de diferentes tipos como multas de órgãos reguladores (ex: ANTT), taxas e impostos.

Propriedades

  • Name
    id
    Type
    number
    Description

    ID único da cobrança.

  • Name
    external_uid
    Type
    string
    Description

    Identificador externo no órgão.

  • Name
    code
    Type
    string
    Description

    Código da cobrança no órgão.

  • Name
    description
    Type
    string
    Description

    Descrição detalhada da cobrança.

  • Name
    date
    Type
    string
    Description

    Data da cobrança no formato "YYYY-MM-DD".

  • Name
    due_date
    Type
    string
    Description

    Data de vencimento no formato "YYYY-MM-DD".

  • Name
    agency
    Type
    string
    Description

    Órgão autuador (ex: "antt", "detran").

  • Name
    key
    Type
    string
    Description

    Chave de identificação da cobrança.

  • Name
    type
    Type
    string
    Description

    Tipo da cobrança. Valores possíveis:

    ValorDescrição
    fineMulta
    feeTaxa
    taxImposto
  • Name
    status
    Type
    string
    Description

    Status atual da cobrança. Valores possíveis:

    ValorDescrição
    pendingPagamento pendente
    paidPago
    overdueVencido
  • Name
    amount
    Type
    number
    Description

    Valor da cobrança em reais.

  • Name
    company
    Type
    object
    Description

    Informações da empresa associada à cobrança.

    • Name
      id
      Type
      number
      Description

      ID da empresa.

    • Name
      external_uid
      Type
      string
      Description

      Identificador externo da empresa.

    • Name
      name
      Type
      string
      Description

      Nome da empresa.

GET/v1/charges/

Listar Cobranças

Retorna uma lista paginada de todas as cobranças 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[date]
    Type
    object
    Description

    Filtra por data da cobrança. 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[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[status]
    Type
    object
    Description

    Filtra por status da cobrança. Valores possíveis: pending, paid, overdue.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

  • Name
    filters[type]
    Type
    object
    Description

    Filtra por tipo da cobrança. Valores possíveis: fine, fee, tax.

    • Name
      $eq
      Type
      string
      Description

      Igual ao valor especificado.

    • Name
      $ne
      Type
      string
      Description

      Diferente do valor especificado.

  • Name
    filters[agency]
    Type
    object
    Description

    Filtra por órgão autuador.

    • 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.

Request

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

Response

{
  "data": [
    {
      "id": 1,
      "external_uid": "FRMEV02298932025",
      "code": "606-82",
      "description": "Pagamento Eletrônico de Frete (PEF)",
      "date": "2025-01-15",
      "due_date": "2026-01-19",
      "agency": "antt",
      "key": "50501.352971/2025-26",
      "type": "fee",
      "status": "pending",
      "amount": 293.47,
      "company": {
        "id": 1,
        "external_uid": "EXT_COMPANY_123",
        "name": "Empresa Exemplo Ltda"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10
  },
  "total": 1
}
GET/v1/charges/{id}

Detalhar Cobrança

Retorna os detalhes completos de uma cobrança específica.

Parâmetros de Rota

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID da cobrança que deseja consultar.

Request

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

Response - 200

{
  "data": {
    "id": 1,
    "external_uid": "FRMEV02298932025",
    "code": "606-82",
    "description": "Pagamento Eletrônico de Frete (PEF)",
    "date": "2025-01-15",
    "due_date": "2026-01-19",
    "agency": "antt",
    "key": "50501.352971/2025-26",
    "type": "fee",
    "status": "pending",
    "amount": 293.47,
    "company": {
      "id": 1,
      "external_uid": "EXT_COMPANY_123",
      "name": "Empresa Exemplo Ltda"
    }
  }
}

Response - 404

{
  "error": "Not Found",
  "message": "Charge with id 123 not found"
}
GET/v1/charges/{id}/payment-slips

Listar Guias de Pagamento

Retorna a lista de guias de pagamento associadas a uma cobrança específica.

Parâmetros de Rota

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID da cobrança.

Request

GET
/v1/charges/{id}/payment-slips
curl https://api.habilitar.me/v1/charges/1/payment-slips \
  -H "x-api-key: {token}"

Response - 200

{
  "data": [
    {
      "id": 1,
      "status": "issued",
      "amount": 293.47,
      "barcode": "23793381286000000000300000000402184340000029347",
      "due_date": "2026-01-19",
      "status_reason": null,
      "last_synced_at": "2025-01-10T10:00:00.000Z",
      "created_at": "2026-01-06T19:06:41.609Z",
      "updated_at": "2026-01-14T11:59:25.865Z"
    }
  ]
}

Response - 404

{
  "error": "Not Found",
  "message": "Charge with id 123 not found"
}
POST/v1/charges/{id}/payment-slips

Solicitar Guia de Pagamento

Solicita a geração de uma guia de pagamento para uma cobrança. Se já existir uma guia de pagamento ativa para esta cobrança, a solicitação será rejeitada.

A geração da guia de pagamento ocorre de forma assíncrona. Todos os eventos relacionados são enviados por webhook.

Parâmetros de Rota

  • Name
    id
    Type
    number
    Required
    obrigatório
    Description

    ID da cobrança.

Request

POST
/v1/charges/{id}/payment-slips
curl -X POST https://api.habilitar.me/v1/charges/1/payment-slips \
  -H "x-api-key: {token}" \
  -H "Content-Type: application/json"

Response - 201

{
  "data": {
    "id": 1,
    "status": "pending",
    "due_date": "2026-01-19"
  }
}

Response - 404

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

Response - 409

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

Response - 422

{
  "error": "Unprocessable Entity",
  "message": "Ticket request is only allowed when charge status is pending or overdue"
}

Eventos de Webhook

  • Name
    charge.created
    Description

    Uma nova cobrança foi criada.

  • Name
    charge.updated
    Description

    Uma cobrança foi atualizada.

Exemplo de payload

{
  "type": "charge.created",
  "data": {
    "id": 1,
    "external_uid": "FRMEV02298932025",
    "code": "606-82",
    "description": "Pagamento Eletrônico de Frete (PEF)",
    "date": "2025-01-15",
    "due_date": "2026-01-19",
    "agency": "antt",
    "key": "50501.352971/2025-26",
    "type": "fee",
    "status": "pending",
    "amount": 293.47,
    "company": {
      "id": 1,
      "tax_id": "12345678000190",
      "external_uid": "EXT_COMPANY_123",
      "name": "Empresa Exemplo Ltda"
    }
  }
}

Essa página foi útil?