rafaelfreba/cnes-dw

Pacote para permitir a consulta de estabelecimentos de saúde no DW SES-MT de maneira padronizada para todo o time de desenvolvimento.

v1.0.2 2026-05-19 14:45 UTC

Requires

• php: ^8.1
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/routing: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0|^11.0|^12.0

MIT

• Rafael Batista

README

Este pacote Laravel foi desenvolvido para centralizar e reutilizar a lógica de consultas a estabelecimentos do Cadastro Nacional de Estabelecimentos de Saúde (CNES) diretamente a partir de uma conexão de Data Warehouse (DW).

🚀 Requisitos

Antes de instalar o pacote, certifique-se de que sua aplicação atende aos seguintes requisitos:

• PHP: ^8.1
• Laravel: ^10.0 ou ^11.0
• Driver do Banco: Certifique-se de ter suporte a conexões sqlsrv configurado no seu ambiente PHP/Laravel.

📦 Instalação

Você pode instalar o pacote via Composer executando o comando abaixo no terminal do seu projeto principal:

composer require rafaelfreba/cnes-dw

Nota: Graças ao recurso de Package Discovery do Laravel, o Service Provider do pacote será registrado automaticamente.

⚙️ Configuração Prévia Obrigatória

Como este pacote consome dados diretamente do seu Data Warehouse, você precisa garantir que a conexão chamada dw esteja configurada no projeto que vai utilizá-lo.

1. Adicionar variáveis ao .env

Abra o arquivo .env da sua aplicação e insira as credenciais do seu DW:

DW_CONNECTION=dw
DW_HOST=127.0.0.1
DW_PORT=1433
DW_DATABASE=Datawarehouse
DW_USERNAME=seu_usuario
DW_PASSWORD=sua_senha

2. Configurar o banco de dados (config/database.php)

Certifique-se de que seu arquivo config/database.php possui a conexão dw mapeada na chave connections:

'connections' => [

    // ... outras conexões existentes

    'dw' => [
        'driver' => 'sqlsrv',
        'url' => env('DW_URL'),
        'host' => env('DW_HOST', 'localhost'),
        'port' => env('DW_PORT', '1433'),
        'database' => env('DW_DATABASE', 'laravel'),
        'username' => env('DW_USERNAME', 'root'),
        'password' => env('DW_PASSWORD', ''),
        'charset' => env('DW_CHARSET', 'utf8'),
        'prefix' => '',
        'prefix_indexes' => true,
    ],
],

🔧 Publicando Arquivos para Customização

Para customizar o Controller, o Model ou as Rotas sem mexer nos arquivos do vendor, publique os stubs do pacote:

php artisan vendor:publish --tag=cnes-dw

Isso copiará os seguintes arquivos para o seu projeto:

Arquivo publicado	Destino no projeto
CnesEstabelecimentoController.php	app/Http/Controllers/CnesEstabelecimentoController.php
CnesEstabelecimento.php	app/Models/CnesEstabelecimento.php
cnes-dw-routes.php	routes/dw.php

Importante: Após publicar, adicione a importação das rotas no seu routes/web.php:

require base_path('routes/dw.php');

O pacote detecta automaticamente a presença do routes/dw.php e desativa suas rotas internas, evitando conflitos.

🛠️ Como Usar

O pacote disponibiliza rotas automáticas, controllers prontos e métodos encapsulados no Model para serem consumidos diretamente.

🛣️ Rotas Disponíveis

O pacote expõe nativamente a seguinte rota de API/Web para a sua aplicação:

• GET /dw-buscar-estabelecimento-por-cnes/{cnes}
• Descrição: Busca um estabelecimento pelo código CNES exato.
• Validação interna: O parâmetro {cnes} deve ser obrigatório e conter exatamente 7 dígitos numéricos.
• Nome da rota: dw-buscar-estabelecimento-por-cnes

Exemplo de resposta (Sucesso - 200):

{
  "data": {
    "cnes": "1234567",
    "nome": "HOSPITAL DE CLINICAS EXEMPLO",
    "municipio": "SAO PAULO",
    "ibge": "3550308"
  }
}

Exemplo de resposta (Erro de Validação - 422):

{
  "erros": {
    "cnes": [
      "The cnes field must be 7 digits."
    ]
  }
}

🗄️ Utilizando o Model Diretamente

Se você preferir realizar consultas diretamente no backend de outras partes do seu código, pode importar e usar o Model CnesEstabelecimento:

use Rafaelfreba\CnesDw\Models\CnesEstabelecimento;

// 1. Buscar por código CNES (Retorna CnesEstabelecimentoResource ou lança ModelNotFoundException)
$estabelecimento = CnesEstabelecimento::buscaEstabelecimentoPorCnes('1234567');

// 2. Buscar por parte do Nome (Usa SQL LIKE - Retorna CnesEstabelecimentoResource ou null)
$estabelecimentoPorNome = CnesEstabelecimento::buscaEstabelecimentoPorNome('Hospital Regional');

// 3. Buscar estabelecimentos de um Município (Retorna CnesEstabelecimentoCollection já paginada com 15 itens por página, filtrada pelo ano atual)
$collection = CnesEstabelecimento::buscaEstabelecimentosPorMunicipio('Cuiabá');

🗂️ Estrutura do Retorno (API Resource)

Todos os retornos de registros individuais deste pacote são transformados nativamente para o padrão unificado abaixo:

Campo original no DW	Campo retornado no JSON	Descrição
CodigoCnes	cnes	Identificador do código CNES
EstabelecimentoNome	nome	Nome oficial do estabelecimento
EstabelecimentoMunicipioNome	municipio	Nome do município do estabelecimento
EstabelecimentoMunicipioCodigo	ibge	Código IBGE do município

📄 Licença

Este pacote é de uso interno e exclusivo. Todos os direitos reservados à SES-MT.