From ed607df25296c281fd806aaacbef6d07a155b1cf Mon Sep 17 00:00:00 2001
From: Rafael Lopes <rafael.lopes@sothis.com.br>
Date: Mon, 24 Nov 2025 16:13:55 -0300
Subject: [PATCH] =?UTF-8?q?DOCS:=20Documenta=C3=A7=C3=A3o=20inicial=20do?=
 =?UTF-8?q?=20projeto?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 155 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5448685
--- /dev/null
+++ b/README.md
@@ -0,0 +1,155 @@
+#  Sothis Contratação API
+
+## Visão Geral
+
+Esta API foi desenvolvida para automatizar e facilitar o processo de novas contratações. Suas duas funcionalidades principais são:
+
+1.  **Consulta de Viabilidade**: Verifica se um determinado endereço (baseado em CEP e número) possui viabilidade técnica para instalação de serviços.
+2.  **Criação de Prospectos**: Registra um novo cliente potencial (prospect) no sistema de gestão Hubsoft.
+
+A aplicação é construída em Node.js com Express e segue uma arquitetura modular para separação de responsabilidades.
+
+## Features
+
+-   **Servidor Express**: API RESTful robusta e performática.
+-   **Arquitetura Modular**: Lógica de negócio organizada no módulo `contratacao`, facilitando a manutenção e expansão.
+-   **Serviços Externos**: Integração com múltiplas APIs de terceiros para consulta de CEP, geolocalização e gestão de clientes.
+-   **Logging Avançado**: Utiliza `winston` para registrar logs da aplicação e de erros em arquivos diários rotacionados.
+-   **Gestão de Ambiente**: Usa `dotenv` para gerenciar configurações de desenvolvimento e produção de forma segura e isolada.
+-   **Desenvolvimento Otimizado**: `nodemon` para reinicialização automática do servidor em ambiente de desenvolvimento.
+
+## Pré-requisitos
+
+-   Node.js (versão 18.x ou superior recomendada)
+-   npm (geralmente instalado junto com o Node.js)
+
+## 1. Instalação
+
+Clone o repositório e instale as dependências:
+
+```bash
+npm install
+```
+
+## 2. Configuração
+
+A aplicação utiliza arquivos `.env` para carregar suas configurações. Você precisará criar dois arquivos na raiz do projeto:
+
+-   `.env.development` (para ambiente de desenvolvimento)
+-   `.env.production` (para ambiente de produção)
+
+Preencha os arquivos com as seguintes variáveis de ambiente:
+
+```env
+# Porta da API (padrão: 3000)
+PORT=3000
+
+# Chave da API do Google Maps Geocoding
+GOOGLE_API_KEY=SUA_CHAVE_AQUI
+
+# Configurações da API GeoGrid
+GEOGRID_API_URL=URL_DA_API_GEOGRID
+GEOGRID_API_KEY=SUA_CHAVE_GEOGRID_AQUI
+GEOGRID_API_COOKIE=SEU_COOKIE_GEOGRID_AQUI
+
+# Configurações da API Hubsoft
+HUBSOFT_URL=URL_DO_HUBSOFT
+HUBSOFT_CLIENT_ID=SEU_CLIENT_ID_HUBSOFT
+HUBSOFT_CLIENT_SECRET=SEU_CLIENT_SECRET_HUBSOFT
+HUBSOFT_USERNAME=SEU_USUARIO_HUBSOFT
+HUBSOFT_PASSWORD=SUA_SENHA_HUBSOFT
+HUBSOFT_GRANT_TYPE=password
+```
+
+## 3. Rodando a Aplicação
+
+### Modo de Desenvolvimento
+
+Este comando inicia a API com `nodemon`, que reinicia o servidor automaticamente a cada alteração nos arquivos. As configurações serão carregadas do `.env.development`.
+
+```bash
+npm run dev:api
+```
+
+### Modo de Produção
+
+Este comando inicia a API de forma otimizada para produção usando `node`. As configurações serão carregadas do `.env.production`.
+
+```bash
+npm run start:api
+```
+
+---
+
+## Documentação da API
+
+O prefixo para todos os endpoints é `/api`.
+
+### Consulta de Viabilidade
+
+Verifica a viabilidade de serviço para um endereço.
+
+-   **Endpoint**: `POST /viabilidade`
+-   **Corpo da Requisição** (`application/json`):
+
+    ```json
+    {
+      "cep": "06419240",
+      "numero": 303
+    }
+    ```
+
+-   **Resposta de Sucesso** (`200 OK`):
+
+    ```json
+    {
+      "bairro": "Chácaras Marco",
+      "cidade": "Barueri",
+      "estado": "SP",
+      "logradouro": "Rua Imirim",
+      "naoDedicado": true,
+      "dedicado": true
+    }
+    ```
+
+-   **Respostas de Erro**:
+    -   `400 Bad Request`: Se `cep` ou `numero` não forem fornecidos.
+    -   `404 Not Found`: Se o endereço não for encontrado para o CEP informado.
+    -   `500 Internal Server Error`: Para outras falhas no processo.
+
+### Criação de Prospecto
+
+Cria um novo cliente potencial no Hubsoft.
+
+-   **Endpoint**: `POST /prospecto`
+-   **Corpo da Requisição** (`application/json`):
+
+    ```json
+    {
+      "cep": "06419240",
+      "servicoId": 1,
+      "servicoValor": 100.00,
+      "numero": "303",
+      "endereco": "Rua Imirim",
+      "bairro": "Chácaras Marco",
+      "tipoPessoa": "F",
+      "nomeRazaoSocial": "Nome do Cliente",
+      "cpfCnpj": "123.456.789-00",
+      "email": "cliente@email.com",
+      "telefone": "11999998888"
+    }
+    ```
+
+-   **Resposta de Sucesso** (`200 OK`):
+
+    ```json
+    {
+      "message": "Prospecto criado com sucesso",
+      "data": {
+        // ... dados retornados pela API do Hubsoft
+      }
+    }
+    ```
+
+-   **Respostas de Erro**:
+    -   `500 Internal Server Error`: Se ocorrer um erro na comunicação com o Hubsoft.
\ No newline at end of file