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:

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:

# 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.

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.

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):

  {
    "cep": "06419240",
    "numero": 303
  }
  

• Resposta de Sucesso (200 OK):

  {
    "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):

  {
    "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):

  {
    "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.