API Pública

Authorization: Bearer wsp_SUA_CHAVE_AQUI

X-API-Key: wsp_SUA_CHAVE_AQUI

https://painel.seuprovedor.com.br/api/v1

{
  "sucesso": true,
  "dados": { "id": 5, "nome": "João Silva" }
}

{
  "sucesso": true,
  "dados": [ ... ],
  "paginacao": { "pagina": 1, "por_pagina": 20, "total": 134, "total_paginas": 7 }
}

{
  "sucesso": false,
  "erro": { "codigo": "permissao_insuficiente", "mensagem": "Esta chave não tem a permissão \"financeiro:leitura\"." }
}

Testar a chave

Confirma que a chave funciona e mostra o provedor e as permissões dela. Use para testar a integração.

curl "$API/status" -H "Authorization: Bearer $CHAVE"

{
  "sucesso": true,
  "dados": {
    "provedor": "Fibra Exemplo Telecom",
    "chave": "Chatbot da Empresa X",
    "permissoes": ["clientes:leitura", "financeiro:leitura"],
    "versao": "v1"
  }
}

Listar ou buscar clientes

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.

Consultar um cliente

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

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

Consultar um contrato

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

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

Aplicar desbloqueio de confiança

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

Listar faturas

Lista faturas, da mais recente para a mais antiga. As faturas em aberto já vêm com a segunda via.

Parâmetros (query)

curl "$API/faturas?cliente_id=5&situacao=aberta" -H "Authorization: Bearer $CHAVE"

{
  "sucesso": true,
  "dados": [
    {
      "id": 77,
      "cliente_id": 5,
      "contrato_id": 10,
      "descricao": "Mensalidade 300 Mega",
      "situacao": "vencida",
      "tipo": "boleto",
      "valor": 99.9,
      "valor_atualizado": null,
      "valor_pago": 0,
      "vencimento": "2026-10-10",
      "emitida_em": "2026-09-25T10:00:00.000Z",
      "pago_em": null,
      "segunda_via": {
        "link_pagamento": "https://banco.exemplo/boleto/77",
        "pdf": "https://banco.exemplo/boleto/77.pdf",
        "pagina_pix": "https://painel.seuprovedor.com.br/api/billings/77/pix",
        "pix_copia_cola": "00020126580014br.gov.bcb.pix...",
        "linha_digitavel": "23793.38128 60000.000003 00000.000000 1 00000000000000",
        "codigo_barras": "23791000000000000003381286000000000000000000"
      }
    }
  ],
  "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "total_paginas": 1 }
}

• segunda_via só vem preenchida em fatura pendente ou vencida; nas demais é null.
• Cada campo da segunda via pode ser null, conforme o banco e o tipo de cobrança. Fatura só PIX não tem linha digitável.
• pagina_pix é a página de pagamento PIX do provedor. O QR é gerado de novo a cada abertura, então o link não expira.
• valor_atualizado aparece quando o PIX foi recalculado com multa e juros: é o valor a pagar hoje.
• tipo: boleto, pix, carne ou carteira.

Consultar uma fatura

Mesmo formato de um item de /faturas, com a segunda via quando em aberto.

curl "$API/faturas/77" -H "Authorization: Bearer $CHAVE"

Listar chamados

Parâmetros (query)

curl "$API/chamados?cliente_id=5&situacao=em_aberto" -H "Authorization: Bearer $CHAVE"

{
  "sucesso": true,
  "dados": [
    {
      "id": 300,
      "cliente_id": 5,
      "contrato_id": 10,
      "situacao": "aberto",
      "prioridade": "alta",
      "categoria": "TECNICO",
      "assunto": "Sem internet",
      "descricao": "Luz vermelha no roteador desde ontem.",
      "solucao": null,
      "aberto_em": "2026-10-13T12:00:00.000Z",
      "fechado_em": null,
      "agendado_para": null
    }
  ],
  "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "total_paginas": 1 }
}

Antes de abrir um chamado novo, consulte os chamados em_aberto do cliente para não duplicar o atendimento.

Consultar um chamado

curl "$API/chamados/300" -H "Authorization: Bearer $CHAVE"

Abrir chamado

O chamado entra na fila do provedor como qualquer outro, e a equipe recebe o aviso de chamado novo com origem API.

Corpo

curl -X POST "$API/chamados" \
  -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{
    "cliente_id": 5,
    "contrato_id": 10,
    "assunto": "Sem internet",
    "descricao": "Luz vermelha no roteador desde ontem. Cliente prefere visita pela manhã.",
    "prioridade": "alta",
    "categoria": "TECNICO"
  }'

Responde 201 com o chamado criado, no mesmo formato de /chamados/{id}.

Listar planos ativos

curl "$API/planos" -H "Authorization: Bearer $CHAVE"

{
  "sucesso": true,
  "dados": [
    { "id": 3, "nome": "300 Mega", "download_mbps": 300, "upload_mbps": 150, "valor": 99.9, "tecnologia": "FIBRA", "descricao": null }
  ]
}