{
  "openapi": "3.0.3",
  "info": {
    "title": "WebSystem Provider — API Pública",
    "version": "1.0.0",
    "description": "API pública do WebSystem Provider para integração de chatbots, URA, aplicativos e BI. Documentação completa: https://websystemprovider.com.br/api.html. O endereço do servidor é o do painel de cada provedor, seguido de /api/v1.",
    "contact": { "name": "WebSystem Provider", "email": "websystemprovider@gmail.com", "url": "https://websystemprovider.com.br/api.html" }
  },
  "servers": [
    {
      "url": "https://{painel}/api/v1",
      "description": "Endereço do painel do provedor",
      "variables": { "painel": { "default": "painel.seuprovedor.com.br", "description": "Domínio do painel do provedor" } }
    }
  ],
  "security": [{ "chave": [] }],
  "tags": [
    { "name": "Status" }, { "name": "Clientes e contratos" }, { "name": "Faturas" }, { "name": "Chamados" }, { "name": "Planos e pré-cadastro" }
  ],
  "paths": {
    "/status": {
      "get": {
        "tags": ["Status"], "summary": "Testar a chave", "operationId": "status",
        "responses": {
          "200": { "description": "Chave válida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RespostaStatus" } } } },
          "401": { "$ref": "#/components/responses/Erro" }
        }
      }
    },
    "/clientes": {
      "get": {
        "tags": ["Clientes e contratos"], "summary": "Listar ou buscar clientes", "operationId": "listarClientes",
        "description": "Permissão: clientes:leitura.",
        "parameters": [
          { "name": "cpf_cnpj", "in": "query", "schema": { "type": "string" }, "description": "CPF (11 dígitos) ou CNPJ (14), com ou sem pontuação." },
          { "name": "telefone", "in": "query", "schema": { "type": "string" }, "description": "Telefone com DDD; compara pelos últimos 8 dígitos." },
          { "name": "situacao", "in": "query", "schema": { "type": "string", "enum": ["ativo", "bloqueado", "cancelado", "inativo", "observacao", "pre_cadastro"] } },
          { "$ref": "#/components/parameters/pagina" }, { "$ref": "#/components/parameters/por_pagina" }
        ],
        "responses": {
          "200": { "description": "Clientes", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Cliente" } }, "paginacao": { "$ref": "#/components/schemas/Paginacao" } } } } } },
          "400": { "$ref": "#/components/responses/Erro" }, "401": { "$ref": "#/components/responses/Erro" }, "403": { "$ref": "#/components/responses/Erro" }, "429": { "$ref": "#/components/responses/Erro" }
        }
      }
    },
    "/clientes/{id}": {
      "get": {
        "tags": ["Clientes e contratos"], "summary": "Consultar um cliente", "operationId": "consultarCliente",
        "description": "Permissão: clientes:leitura.",
        "parameters": [{ "$ref": "#/components/parameters/id" }],
        "responses": {
          "200": { "description": "Cliente", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "$ref": "#/components/schemas/Cliente" } } } } } },
          "404": { "$ref": "#/components/responses/Erro" }
        }
      }
    },
    "/contratos/{id}": {
      "get": {
        "tags": ["Clientes e contratos"], "summary": "Consultar um contrato", "operationId": "consultarContrato",
        "description": "Permissão: clientes:leitura.",
        "parameters": [{ "$ref": "#/components/parameters/id" }],
        "responses": {
          "200": { "description": "Contrato", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "$ref": "#/components/schemas/Contrato" } } } } } },
          "404": { "$ref": "#/components/responses/Erro" }
        }
      }
    },
    "/contratos/{id}/conexao": {
      "get": {
        "tags": ["Clientes e contratos"], "summary": "Conexão e quedas dos últimos 30 dias", "operationId": "conexaoContrato",
        "description": "Permissão: clientes:leitura.",
        "parameters": [{ "$ref": "#/components/parameters/id" }],
        "responses": {
          "200": { "description": "Conexão", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "$ref": "#/components/schemas/Conexao" } } } } } },
          "404": { "$ref": "#/components/responses/Erro" }
        }
      }
    },
    "/contratos/{id}/desbloqueio-confianca": {
      "post": {
        "tags": ["Clientes e contratos"], "summary": "Aplicar desbloqueio de confiança", "operationId": "desbloqueioConfianca",
        "description": "Permissão: contratos:desbloqueio. Mesmas regras do autoatendimento.",
        "parameters": [{ "$ref": "#/components/parameters/id" }],
        "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "motivo": { "type": "string", "maxLength": 500 } } } } } },
        "responses": {
          "201": { "description": "Desbloqueio aplicado", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "type": "object", "properties": { "contrato_id": { "type": "integer" }, "dias": { "type": "integer" }, "ate": { "type": "string", "format": "date-time" } } } } } } } },
          "409": { "$ref": "#/components/responses/Erro" }, "422": { "$ref": "#/components/responses/Erro" }
        }
      }
    },
    "/faturas": {
      "get": {
        "tags": ["Faturas"], "summary": "Listar faturas", "operationId": "listarFaturas",
        "description": "Permissão: financeiro:leitura.",
        "parameters": [
          { "name": "cliente_id", "in": "query", "schema": { "type": "integer" } },
          { "name": "contrato_id", "in": "query", "schema": { "type": "integer" } },
          { "name": "situacao", "in": "query", "schema": { "type": "string", "enum": ["aberta", "pendente", "vencida", "paga", "cancelada", "estornada", "todas"], "default": "todas" } },
          { "name": "vencimento_de", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "vencimento_ate", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "$ref": "#/components/parameters/pagina" }, { "$ref": "#/components/parameters/por_pagina" }
        ],
        "responses": {
          "200": { "description": "Faturas", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Fatura" } }, "paginacao": { "$ref": "#/components/schemas/Paginacao" } } } } } }
        }
      }
    },
    "/faturas/{id}": {
      "get": {
        "tags": ["Faturas"], "summary": "Consultar uma fatura", "operationId": "consultarFatura",
        "description": "Permissão: financeiro:leitura.",
        "parameters": [{ "$ref": "#/components/parameters/id" }],
        "responses": {
          "200": { "description": "Fatura", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "$ref": "#/components/schemas/Fatura" } } } } } },
          "404": { "$ref": "#/components/responses/Erro" }
        }
      }
    },
    "/chamados": {
      "get": {
        "tags": ["Chamados"], "summary": "Listar chamados", "operationId": "listarChamados",
        "description": "Permissão: chamados:leitura.",
        "parameters": [
          { "name": "cliente_id", "in": "query", "schema": { "type": "integer" } },
          { "name": "contrato_id", "in": "query", "schema": { "type": "integer" } },
          { "name": "situacao", "in": "query", "schema": { "type": "string", "enum": ["aberto", "pendente", "pendente_terceiro", "em_andamento", "reaberto", "solucionado", "cancelado", "em_aberto"] } },
          { "$ref": "#/components/parameters/pagina" }, { "$ref": "#/components/parameters/por_pagina" }
        ],
        "responses": {
          "200": { "description": "Chamados", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Chamado" } }, "paginacao": { "$ref": "#/components/schemas/Paginacao" } } } } } }
        }
      },
      "post": {
        "tags": ["Chamados"], "summary": "Abrir chamado", "operationId": "abrirChamado",
        "description": "Permissão: chamados:escrita.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["cliente_id", "assunto", "descricao"],
            "properties": {
              "cliente_id": { "type": "integer" },
              "contrato_id": { "type": "integer", "nullable": true },
              "assunto": { "type": "string", "minLength": 3, "maxLength": 300 },
              "descricao": { "type": "string", "minLength": 3, "maxLength": 5000 },
              "prioridade": { "type": "string", "enum": ["baixa", "normal", "alta", "urgente"], "default": "normal" },
              "categoria": { "type": "string", "enum": ["TECNICO", "FINANCEIRO", "COMERCIAL", "INSTALACAO", "CANCELAMENTO", "OUTRO"] }
            }
          } } }
        },
        "responses": {
          "201": { "description": "Chamado aberto", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "$ref": "#/components/schemas/Chamado" } } } } } },
          "400": { "$ref": "#/components/responses/Erro" }, "404": { "$ref": "#/components/responses/Erro" }, "422": { "$ref": "#/components/responses/Erro" }
        }
      }
    },
    "/chamados/{id}": {
      "get": {
        "tags": ["Chamados"], "summary": "Consultar um chamado", "operationId": "consultarChamado",
        "description": "Permissão: chamados:leitura.",
        "parameters": [{ "$ref": "#/components/parameters/id" }],
        "responses": {
          "200": { "description": "Chamado", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "$ref": "#/components/schemas/Chamado" } } } } } },
          "404": { "$ref": "#/components/responses/Erro" }
        }
      },
      "patch": {
        "tags": ["Chamados"], "summary": "Atualizar, comentar ou solucionar", "operationId": "atualizarChamado",
        "description": "Permissão: chamados:escrita. Envie ao menos um campo.",
        "parameters": [{ "$ref": "#/components/parameters/id" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "properties": {
              "situacao": { "type": "string", "enum": ["em_andamento", "pendente", "pendente_terceiro", "reaberto", "solucionado", "cancelado"] },
              "solucao": { "type": "string", "minLength": 3, "maxLength": 5000 },
              "prioridade": { "type": "string", "enum": ["baixa", "normal", "alta", "urgente"] },
              "comentario": { "type": "string", "minLength": 1, "maxLength": 5000 }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Chamado atualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "$ref": "#/components/schemas/Chamado" } } } } } },
          "404": { "$ref": "#/components/responses/Erro" }, "422": { "$ref": "#/components/responses/Erro" }
        }
      }
    },
    "/chamados/{id}/historico": {
      "get": {
        "tags": ["Chamados"], "summary": "Histórico do chamado", "operationId": "historicoChamado",
        "description": "Permissão: chamados:leitura.",
        "parameters": [{ "$ref": "#/components/parameters/id" }],
        "responses": {
          "200": { "description": "Histórico", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "acao": { "type": "string" }, "descricao": { "type": "string", "nullable": true }, "autor": { "type": "string", "nullable": true }, "ocorrido_em": { "type": "string", "format": "date-time" } } } } } } } } }
        }
      }
    },
    "/planos": {
      "get": {
        "tags": ["Planos e pré-cadastro"], "summary": "Listar planos ativos", "operationId": "listarPlanos",
        "description": "Permissão: planos:leitura.",
        "responses": {
          "200": { "description": "Planos", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Plano" } } } } } } }
        }
      }
    },
    "/pre-cadastros/convites": {
      "post": {
        "tags": ["Planos e pré-cadastro"], "summary": "Gerar link de pré-cadastro", "operationId": "gerarConvitePreCadastro",
        "description": "Permissão: pre_cadastro:escrita.",
        "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "plano_id": { "type": "integer" }, "dia_vencimento": { "type": "integer", "minimum": 1, "maximum": 30 }, "validade_dias": { "type": "integer", "minimum": 1, "maximum": 365, "default": 7 } } } } } },
        "responses": {
          "201": { "description": "Link gerado", "content": { "application/json": { "schema": { "type": "object", "properties": { "sucesso": { "type": "boolean" }, "dados": { "type": "object", "properties": { "link": { "type": "string" }, "expira_em": { "type": "string", "format": "date-time", "nullable": true }, "plano_id": { "type": "integer", "nullable": true }, "dia_vencimento": { "type": "integer", "nullable": true } } } } } } } },
          "422": { "$ref": "#/components/responses/Erro" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "chave": { "type": "http", "scheme": "bearer", "description": "Chave da API (wsp_...), criada pelo provedor em Configurações > API pública. Também aceita o cabeçalho X-API-Key." }
    },
    "parameters": {
      "id": { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
      "pagina": { "name": "pagina", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
      "por_pagina": { "name": "por_pagina", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
    },
    "responses": {
      "Erro": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }
    },
    "schemas": {
      "Erro": {
        "type": "object",
        "properties": { "sucesso": { "type": "boolean", "example": false }, "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" } } } }
      },
      "Paginacao": {
        "type": "object",
        "properties": { "pagina": { "type": "integer" }, "por_pagina": { "type": "integer" }, "total": { "type": "integer" }, "total_paginas": { "type": "integer" } }
      },
      "RespostaStatus": {
        "type": "object",
        "properties": { "sucesso": { "type": "boolean" }, "dados": { "type": "object", "properties": { "provedor": { "type": "string" }, "chave": { "type": "string" }, "permissoes": { "type": "array", "items": { "type": "string" } }, "versao": { "type": "string" } } } }
      },
      "Endereco": {
        "type": "object",
        "properties": { "cep": { "type": "string", "nullable": true }, "logradouro": { "type": "string", "nullable": true }, "numero": { "type": "string", "nullable": true }, "complemento": { "type": "string", "nullable": true }, "bairro": { "type": "string", "nullable": true }, "cidade": { "type": "string", "nullable": true }, "uf": { "type": "string", "nullable": true } }
      },
      "Contrato": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" }, "cliente_id": { "type": "integer" },
          "situacao": { "type": "string", "enum": ["pendente", "ativo", "bloqueado", "inativo", "cancelado", "cancelado_definitivo"] },
          "conexao": { "type": "string", "enum": ["online", "offline", "desconhecido"] },
          "tipo_conexao": { "type": "string" }, "login": { "type": "string", "nullable": true }, "mac": { "type": "string", "nullable": true }, "ip": { "type": "string", "nullable": true },
          "tipo_cobranca": { "type": "string", "enum": ["pos_pago", "pre_pago", "isento"] },
          "dia_vencimento": { "type": "integer" }, "valor": { "type": "number" },
          "ativado_em": { "type": "string", "format": "date", "nullable": true }, "bloqueado_em": { "type": "string", "format": "date-time", "nullable": true },
          "desbloqueio_confianca": { "type": "object", "properties": { "ativo": { "type": "boolean" }, "ate": { "type": "string", "format": "date-time", "nullable": true } } },
          "plano": { "type": "object", "properties": { "id": { "type": "integer" }, "nome": { "type": "string" }, "download_mbps": { "type": "integer" }, "upload_mbps": { "type": "integer" } } },
          "endereco_instalacao": { "$ref": "#/components/schemas/Endereco" }
        }
      },
      "Cliente": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" }, "nome": { "type": "string" }, "nome_fantasia": { "type": "string", "nullable": true },
          "tipo": { "type": "string", "enum": ["pf", "pj"] }, "cpf_cnpj": { "type": "string" }, "email": { "type": "string", "nullable": true },
          "telefones": { "type": "array", "items": { "type": "string" } },
          "situacao": { "type": "string" }, "data_nascimento": { "type": "string", "format": "date", "nullable": true },
          "criado_em": { "type": "string", "format": "date-time" }, "endereco": { "$ref": "#/components/schemas/Endereco" },
          "contratos": { "type": "array", "items": { "$ref": "#/components/schemas/Contrato" } }
        }
      },
      "Conexao": {
        "type": "object",
        "properties": {
          "contrato_id": { "type": "integer" }, "conexao": { "type": "string" }, "fonte": { "type": "string" },
          "quedas_7_dias": { "type": "integer" }, "quedas_30_dias": { "type": "integer" },
          "sessoes": { "type": "array", "items": { "type": "object", "properties": { "inicio": { "type": "string", "format": "date-time", "nullable": true }, "fim": { "type": "string", "format": "date-time", "nullable": true }, "duracao_segundos": { "type": "integer" }, "causa": { "type": "string", "nullable": true } } } }
        }
      },
      "Fatura": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" }, "cliente_id": { "type": "integer" }, "contrato_id": { "type": "integer", "nullable": true },
          "descricao": { "type": "string", "nullable": true },
          "situacao": { "type": "string", "enum": ["pendente", "vencida", "paga", "cancelada", "estornada", "processando"] },
          "tipo": { "type": "string", "nullable": true }, "valor": { "type": "number" }, "valor_atualizado": { "type": "number", "nullable": true }, "valor_pago": { "type": "number" },
          "vencimento": { "type": "string", "format": "date" }, "emitida_em": { "type": "string", "format": "date-time" }, "pago_em": { "type": "string", "format": "date-time", "nullable": true },
          "segunda_via": {
            "type": "object", "nullable": true,
            "properties": { "link_pagamento": { "type": "string", "nullable": true }, "pdf": { "type": "string", "nullable": true }, "pagina_pix": { "type": "string", "nullable": true }, "pix_copia_cola": { "type": "string", "nullable": true }, "linha_digitavel": { "type": "string", "nullable": true }, "codigo_barras": { "type": "string", "nullable": true } }
          }
        }
      },
      "Chamado": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" }, "cliente_id": { "type": "integer" }, "contrato_id": { "type": "integer", "nullable": true },
          "situacao": { "type": "string" }, "prioridade": { "type": "string" }, "categoria": { "type": "string", "nullable": true },
          "assunto": { "type": "string" }, "descricao": { "type": "string" }, "solucao": { "type": "string", "nullable": true },
          "aberto_em": { "type": "string", "format": "date-time" }, "fechado_em": { "type": "string", "format": "date-time", "nullable": true },
          "agendado_para": { "type": "string", "nullable": true }
        }
      },
      "Plano": {
        "type": "object",
        "properties": { "id": { "type": "integer" }, "nome": { "type": "string" }, "download_mbps": { "type": "integer" }, "upload_mbps": { "type": "integer" }, "valor": { "type": "number" }, "tecnologia": { "type": "string", "nullable": true }, "descricao": { "type": "string", "nullable": true } }
      }
    }
  }
}