155 lines
4.4 KiB
Markdown
155 lines
4.4 KiB
Markdown
# 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. |