Clientes e contratos

Sem filtros, lista todos os clientes. Com cpf_cnpj, encontra o cliente pelo documento, com ou sem pontuação. Cada cliente vem com os contratos.

Parâmetros (query)

curl "$API/clientes?cpf_cnpj=123.456.789-09" -H "Authorization: Bearer $CHAVE"

{
  "sucesso": true,
  "dados": [
    {
      "id": 5,
      "nome": "João Silva",
      "nome_fantasia": null,
      "tipo": "pf",
      "cpf_cnpj": "123.456.789-09",
      "email": "joao@email.com",
      "telefones": ["95999990000"],
      "situacao": "ativo",
      "data_nascimento": null,
      "criado_em": "2026-01-10T12:00:00.000Z",
      "endereco": { "cep": "69300000", "logradouro": "Rua A", "numero": "10", "complemento": null, "bairro": "Centro", "cidade": "Boa Vista", "uf": "RR" },
      "contratos": [
        {
          "id": 10,
          "cliente_id": 5,
          "situacao": "ativo",
          "conexao": "online",
          "tipo_conexao": "pppoe",
          "login": "joao",
          "mac": null,
          "ip": "100.64.0.10",
          "tipo_cobranca": "pos_pago",
          "dia_vencimento": 10,
          "valor": 99.9,
          "ativado_em": "2026-01-15",
          "bloqueado_em": null,
          "desbloqueio_confianca": { "ativo": false, "ate": null },
          "plano": { "id": 3, "nome": "300 Mega", "download_mbps": 300, "upload_mbps": 150 },
          "endereco_instalacao": { "cep": "69300000", "logradouro": "Rua A", "numero": "10", "complemento": null, "bairro": "Centro", "cidade": "Boa Vista", "uf": "RR" }
        }
      ]
    }
  ],
  "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "total_paginas": 1 }
}

situacao do contrato: pendente, ativo, bloqueado, inativo, cancelado ou cancelado_definitivo. conexao: online, offline ou desconhecido. tipo_cobranca: pos_pago, pre_pago ou isento.

Mesmo formato de um item de /clientes, com os contratos.

curl "$API/clientes/5" -H "Authorization: Bearer $CHAVE"

Mesmo formato do contrato dentro do cliente: situação, conexão, plano, valor, vencimento e desbloqueio de confiança em vigor.

curl "$API/contratos/10" -H "Authorization: Bearer $CHAVE"

Situação da conexão agora e as quedas dos últimos 30 dias, contadas do mesmo jeito que o relatório de Quedas de Conexões do provedor. Útil para o atendimento técnico: “caiu quantas vezes esta semana?”.

curl "$API/contratos/10/conexao" -H "Authorization: Bearer $CHAVE"

{
  "sucesso": true,
  "dados": {
    "contrato_id": 10,
    "conexao": "online",
    "fonte": "RADIUS",
    "quedas_7_dias": 1,
    "quedas_30_dias": 4,
    "sessoes": [
      { "inicio": "2026-10-12T08:00:00.000Z", "fim": null, "duracao_segundos": 0, "causa": null },
      { "inicio": "2026-10-10T19:30:00.000Z", "fim": "2026-10-12T07:58:00.000Z", "duracao_segundos": 131280, "causa": "Lost-Carrier" }
    ]
  }
}

• Uma sessão com fim: null está aberta (cliente conectado) e não conta como queda.
• sessoes traz as 50 mais recentes. causa vem do concentrador (ex.: Lost-Carrier, User-Request).
• fonte diz de onde a contagem saiu: RADIUS ou o monitoramento do sistema (API, DHCP/API).

Libera a conexão de um contrato bloqueado por falta de pagamento, pelo prazo definido nas regras de cobrança do provedor. Valem as mesmas regras do autoatendimento (Central do Assinante e WhatsApp):

• o desbloqueio de confiança precisa estar habilitado nas regras de cobrança do provedor;
• o contrato precisa estar bloqueado por cobrança: bloqueio feito manualmente pelo provedor só sai pelo atendimento;
• depois do primeiro uso, um novo desbloqueio só é liberado quando a fatura que motivou o anterior for quitada.

Corpo (opcional)

curl -X POST "$API/contratos/10/desbloqueio-confianca" \
  -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{"motivo": "Cliente informou que paga amanhã"}'

{
  "sucesso": true,
  "dados": { "contrato_id": 10, "dias": 3, "ate": "2026-10-16T15:00:00.000Z" }
}

Recusas possíveis

A mensagem de cada recusa já explica o motivo em linguagem simples e pode ser repassada ao assinante.