{"id":48549679,"url":"https://github.com/jeronimofjr/api-esus","last_synced_at":"2026-04-08T08:01:55.805Z","repository":{"id":337514755,"uuid":"1151100852","full_name":"jeronimofjr/api-esus","owner":"jeronimofjr","description":"API REST para acesso estruturado a dados de atendimentos de saúde","archived":false,"fork":false,"pushed_at":"2026-02-09T22:05:44.000Z","size":184,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-10T02:06:10.385Z","etag":null,"topics":["docker-compose","flask","python","sqlalchemy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeronimofjr.png","metadata":{"files":{"readme":"readme.MD","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T03:50:13.000Z","updated_at":"2026-02-09T22:05:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jeronimofjr/api-esus","commit_stats":null,"previous_names":["jeronimofjr/api-esus"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jeronimofjr/api-esus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeronimofjr%2Fapi-esus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeronimofjr%2Fapi-esus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeronimofjr%2Fapi-esus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeronimofjr%2Fapi-esus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeronimofjr","download_url":"https://codeload.github.com/jeronimofjr/api-esus/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeronimofjr%2Fapi-esus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31545908,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-compose","flask","python","sqlalchemy"],"created_at":"2026-04-08T08:01:54.929Z","updated_at":"2026-04-08T08:01:55.798Z","avatar_url":"https://github.com/jeronimofjr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# API REST para Acesso a Dados de Saúde\n\nEste projeto consiste no desenvolvimento de uma API REST para acesso estruturado a dados de atendimentos de saúde, originalmente exportados de um sistema de terceiros em formato CSV. O objetivo é disponibilizar esses dados de forma segura, padronizada e eficiente para consumo por uma equipe de Ciência de dados.\n\nA API foi desenvolvida em Python utilizando o micro-framework Flask, seguindo boas práticas de arquitetura, validação de dados, testes automatizados e documentação.\n\nO banco de dados é representado pelo arquivo `atendimentos.csv`\n\n# Implementação da API\n\nA API expõe endpoints para consulta de atendimentos de saúde, suportando paginação de resultados, **filtros** por período e unidade, validação de entradas e respostas padronizadas. A aplicação foi estruturada em camadas, com foco em manutenibilidade e testabilidade.\n\n## Arquitetura\n\nO projeto utiliza arquitetura em camadas, promovendo separação de responsabilidades, facilidade de manutenção e testes:\n\n- **Controllers:** Camada HTTP, responsável por receber requisições, aplicar validações e retornar respostas padronizadas.\n- **Services:** Regras de negócio e orquestração dos fluxos da aplicação.\n- **Repositories:** Acesso e abstração da camada de dados.\n- **Schemas:** Validação, serialização e desserialização de dados de entrada e saída.\n- **Models:** Representação das entidades de domínio.\n\n## Funcionalidades\n\n- Consulta paginada de atendimentos de saúde, evitando sobrecarga e facilitando o consumo de grandes volumes de dados\n- Filtros por período e unidade de atendimento\n- Validação e sanitização de dados de entrada e saída utilizando schemas dedicados\n- Respostas padronizadas em toda a API, garantindo consistência e previsibilidade para consumidores\n- Tratamento centralizado de erros por meio de handlers globais\n- Documentação interativa da API utilizando OpenAPI (Swagger)\n- Testes automatizados cobrindo rotas e schemas, assegurando confiabilidade e estabilidade da aplicação\n\n## Tecnologias\n\n| Tecnologia                      | Versão   |\n| ------------------------------- | -------- |\n| Python                          | `3.10`   |\n| Flask                           | `3.1.2`  |\n| Marshmallow                     | `4.2.1`  |\n| SQLAlchemy                      | `2.0.46` |\n| Pytest                          | `9.0.2`  |\n| Docker                          | `26.1.0` |\n| Swagger UI (`flask-swagger-ui`) | `4.11.1` |\n\n## Estrutura\n\n```bash\n.\n├── app\n│   ├── config\n│   │   ├── database.py\n│   │   └── __init__.py\n│   ├── controllers\n│   │   ├── atendimento_controller.py\n│   │   ├── __init__.py\n│   │   └── system_controller.py\n│   ├── data\n│   │   ├── 01_schema.sql\n│   │   ├── 02_seed.sql\n│   │   ├── atendimentos.csv\n│   │   └── __init__.py\n│   ├── Dockerfile\n│   ├── __init__.py\n│   ├── models\n│   │   ├── atendimentos.py\n│   │   └── __init__.py\n│   ├── repositories\n│   │   ├── atendimento_repository.py\n│   │   └── __init__.py\n│   ├── requirements.txt\n│   ├── run.py\n│   ├── schemas\n│   │   ├── atendimento_schema.py\n│   │   └── __init__.py\n│   ├── services\n│   │   ├── atendimento_service.py\n│   │   └── __init__.py\n│   ├── tests\n│   │   ├── conftest.py\n│   │   ├── __init__.py\n│   │   ├── test_rotas.py\n│   │   └── test_schemas.py\n│   └── utils\n│       ├── error_handlers.py\n│       ├── __init__.py\n│       ├── responses.py\n│       └── swagger.py\n├── docker-compose.yml\n└── docs\n    └── openapi.yml\n```\n\n## Como executar o projeto\n\n### Pré-requisitos\n\n- Docker \u003e= 26.1.0\n- Porta **8001** livre\n\n**Clone o repositório do projeto:**\n\n```bash\ngit clone https://github.com/jeronimofjr/api-esus\n```\n\n**Acesse o diretório do projeto**\n\n```bash\ncd /api-esus\n```\n\nNa raiz do projeto crie um arquivo `.env` e o preecha de acordo com o exemplo dado no arquivo `.env.example`\n\nSuba a aplicação utilizando Docker Compose:\n\n```bash\ndocker compose up --build\n```\n\nApós a inicialização dos containers, a API estará disponível para consumo.\n\n---\n\n### Acesso à API e Documentação\n\n- **URL Base:** `http://127.0.0.1:8001/api/v1/`\n\nA documentação interativa da API pode ser acessada via Swagger:\n\n- **Swagger UI:** `http://127.0.0.1:8001/api/v1/docs`\n\n### Principais Endpoints\n\n| Método | Rota                                           | Descrição                                                        |\n| ------ | ---------------------------------------------- | ---------------------------------------------------------------- |\n| GET    | `/atendimentos`                                | Lista atendimentos com paginação                                 |\n| GET    | `/atendimentos/periodo?data_inicio=\u0026data_fim=` | Consulta atendimentos por período                                |\n| GET    | `/atendimentos/{id}`                           | Filtra atendimentos por id                                       |\n| GET    | `/atendimentos/stats`                          | Lista estatísticas dos Atendimentos                              |\n| GET    | `/info`                                        | Lista informações da API, endpoints, docs, nome, status e versão |\n\n### Exemplos de uso\n\n**Listagem simples com paginação**\n\n```http\ncurl http://127.0.0.1:8001/api/v1/atendimentos?limit=3\n```\n\n**Quando usar**\nPara consumir dados paginados ou popular listagens no front-end.\n\n**Saída:**\n\n```json\n{\n  \"data\": {\n    \"atendimentos\": [\n      {\n        \"cns\": \"75983412655\",\n        \"condicao_saude\": \"hipertensao\",\n        \"cpf\": \"***.***.***-87\",\n        \"data_atendimento\": \"2023-08-10\",\n        \"id\": 0,\n        \"nascimento\": \"1978-04-05\",\n        \"nome\": \"Elisa Pinto\",\n        \"unidade\": \"Unidade de saude Maria Alice\"\n      },\n      {\n        \"cns\": \"75983412655\",\n        \"condicao_saude\": \"diabetes\",\n        \"cpf\": \"***.***.***-87\",\n        \"data_atendimento\": \"2023-12-19\",\n        \"id\": 1,\n        \"nascimento\": \"1978-04-05\",\n        \"nome\": \"Elisa Pinto\",\n        \"unidade\": \"Unidade de saude Maria Alice\"\n      },\n      {\n        \"cns\": \"75983412655\",\n        \"condicao_saude\": \"diabetes\",\n        \"cpf\": \"***.***.***-87\",\n        \"data_atendimento\": \"2023-11-06\",\n        \"id\": 2,\n        \"nascimento\": \"1978-04-05\",\n        \"nome\": \"Elisa Pinto\",\n        \"unidade\": \"Unidade de saude Maria Alice\"\n      }\n    ]\n  },\n  \"pagination\": {\n    \"limit\": 3,\n    \"page\": 1,\n    \"total_pages\": 3111\n  },\n  \"success\": true,\n  \"total_items\": 9331\n}\n```\n\n**Consulta por período**\n\n```http\ncurl http://127.0.0.1:8001/api/v1/atendimentos/periodo?data_inicio=2024-01-01\u0026data_fim=2024-01-02\n```\n\n**Quando usar:**\nPara análises temporais ou geração de relatórios.\n\n**Estatísticas agregadas**\n\n```http\ncurl http://127.0.0.1:8001/api/v1/atendimentos/stats\n```\n\n**Quando usar:**\n\nPara dashboards, indicadores e métricas de saúde.\n\n**Saída:**\n\n```json\n{\n  \"data\": {\n    \"atendimentos_por_condicao_saude\": {\n      \"dengue\": 2353,\n      \"diabetes\": 2342,\n      \"ferida vascular\": 2319,\n      \"hipertensao\": 2317\n    },\n    \"total_atendimentos\": 9331,\n    \"total_pessoas_unicas\": 934\n  },\n  \"success\": true\n}\n```\n\n**Mesclando filtros**\n\n```http\nhttp://127.0.0.1:8001/api/v1/atendimentos?condicao_saude=diabetes\u0026unidade=Unidade%20de%20saude%20Maria%20Alice\u0026limit=3\n```\n\n**Quando usar:**\n\nPara consultas refinadas e cruzamento de dados.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeronimofjr%2Fapi-esus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeronimofjr%2Fapi-esus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeronimofjr%2Fapi-esus/lists"}