{ "openapi": "3.1.0", "info": { "title": "SusConecta Data API", "version": "1", "description": "API pública e oficial da Plataforma SusConecta para consulta e consumo de dados canônicos, auditados e tratados do Sistema Único de Saúde (SUS).\n\n### Arquitetura e Níveis de Versionamento\n- **API Route Version:** `v1` (prefixo `/v1` nas rotas).\n- **Data Catalog Version:** `v1.1.0` (catálogo semântico com 18 métricas e 15 dimensões).\n- **Application Build Version:** Refletida em `meta.version` (`0.1.0`), indicando a compilação do microservice de API.\n- **Data Release ID:** Snapshot temporal imutável de 256 bits (ex.: `CNES-GO-202607-71d4baec...`).\n\n### Autenticação e Segurança\nTodas as rotas sob `/v1` exigem autenticação via chave de API server-side no cabeçalho HTTP:\n`Authorization: Bearer `\n\nO acesso é controlado por 8 Capabilities Públicas canônicas (`PUBLIC_CAPABILITY_COUNT = 8`).\n" }, "servers": [ { "url": "https://api.susconecta.com.br", "description": "Servidor de Produção Oficial" } ], "tags": [ { "name": "Health", "description": "Verificação de disponibilidade e prontidão da instância" }, { "name": "Geography", "description": "Divisão territorial canônica e metadados do IBGE (27 UFs e 5.571 municípios)" }, { "name": "Facilities", "description": "Cadastro Nacional de Estabelecimentos de Saúde (CNES Current Core)" }, { "name": "Bed Capacity", "description": "Capacidade mensal cadastrada de leitos hospitalares (CNES/DATASUS)" }, { "name": "Equipment Inventory", "description": "Inventário quantitativo mensal de equipamentos de saúde (CNES)" }, { "name": "Specialized Services", "description": "Declarações cadastrais de ofertas de serviços especializados (CNES)" }, { "name": "Demography", "description": "Estimativas e projeções populacionais municipais do IBGE" }, { "name": "Analytics Catalog", "description": "Descoberta dinâmica de catálogo semântico de indicadores e valores de dimensões" }, { "name": "Analytics Query", "description": "Motor de consultas analíticas multidimensionais e exportações XLSX auditáveis" } ], "paths": { "/health": { "get": { "tags": ["Health"], "summary": "Verificação de disponibilidade (Liveness check)", "description": "Endpoint público para sondagem de integridade e liveness do serviço.", "operationId": "getHealth", "security": [], "responses": { "200": { "description": "Serviço operacional", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/ready": { "get": { "tags": ["Health"], "summary": "Verificação de prontidão da infraestrutura (Readiness check)", "description": "Endpoint público para sondagem de conectividade do pool de banco de dados.", "operationId": "getReady", "security": [], "responses": { "200": { "description": "Banco de dados disponível e pronto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" } } } }, "503": { "description": "Banco de dados indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotReadyResponse" } } } } } } }, "/v1/states": { "get": { "tags": ["Geography"], "summary": "Listagem das 27 Unidades da Federação", "description": "Retorna todas as 27 Unidades da Federação do Brasil com metadados do IBGE.", "operationId": "listStates", "x-susconecta-capability": "geo.read", "security": [{ "ApiKeyBearer": [] }], "responses": { "200": { "description": "Lista de estados retornada com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/states/{ibge_code}": { "get": { "tags": ["Geography"], "summary": "Detalhe de Estado por código IBGE", "description": "Retorna os dados de uma Unidade da Federação pelo código IBGE de 2 dígitos.", "operationId": "getStateByIbgeCode", "x-susconecta-capability": "geo.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "ibge_code", "in": "path", "required": true, "description": "Código IBGE da Unidade da Federação (2 dígitos)", "schema": { "type": "integer", "example": 52 } } ], "responses": { "200": { "description": "Estado encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateDetailResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/states/{uf}/municipalities": { "get": { "tags": ["Geography"], "summary": "Listagem de municípios de uma UF", "description": "Retorna os municípios pertencentes a uma Unidade da Federação com suporte a paginação keyset.", "operationId": "listMunicipalitiesByState", "x-susconecta-capability": "geo.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "uf", "in": "path", "required": true, "description": "Sigla da Unidade Federativa (2 caracteres)", "schema": { "type": "string", "example": "GO" } }, { "name": "limit", "in": "query", "required": false, "description": "Quantidade de municípios por página (1 a 250)", "schema": { "type": "integer", "default": 50, "maximum": 250 } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor opaco base64 para keyset pagination", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada de municípios", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MunicipalityListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/municipalities": { "get": { "tags": ["Geography"], "summary": "Listagem geral e busca de municípios", "description": "Consulta e busca municípios em todo o território nacional.", "operationId": "listMunicipalities", "x-susconecta-capability": "geo.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Filtro por sigla da UF (2 caracteres)", "schema": { "type": "string", "example": "GO" } }, { "name": "search", "in": "query", "required": false, "description": "Busca textual por nome ou código IBGE", "schema": { "type": "string", "example": "Goiânia" } }, { "name": "territorial_type", "in": "query", "required": false, "description": "Tipo de território", "schema": { "type": "string", "default": "MUNICIPALITY" } }, { "name": "limit", "in": "query", "required": false, "description": "Limite de registros por página", "schema": { "type": "integer", "default": 50, "maximum": 250 } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor opaco base64 para keyset pagination", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada de municípios", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MunicipalityListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/municipalities/{ibge_code}": { "get": { "tags": ["Geography"], "summary": "Detalhe de município por código IBGE", "description": "Retorna os dados completos do município identificado pelo código IBGE de 7 dígitos.", "operationId": "getMunicipalityByIbgeCode", "x-susconecta-capability": "geo.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "ibge_code", "in": "path", "required": true, "description": "Código IBGE de 7 dígitos do município", "schema": { "type": "integer", "example": 5208707 } } ], "responses": { "200": { "description": "Município encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MunicipalityDetailResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/facilities": { "get": { "tags": ["Facilities"], "summary": "Listagem de estabelecimentos de saúde (CNES)", "description": "Consulta estabelecimentos de saúde oficiais com filtros territoriais e administrativos e paginação keyset.", "operationId": "listFacilities", "x-susconecta-capability": "facilities.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "uf", "in": "query", "required": false, "description": "Sigla da Unidade Federativa", "schema": { "type": "string", "example": "GO" } }, { "name": "municipality_ibge_code", "in": "query", "required": false, "description": "Código IBGE do município gestor (7 dígitos)", "schema": { "type": "integer", "example": 5208707 } }, { "name": "facility_type_code", "in": "query", "required": false, "description": "Código do tipo de estabelecimento CNES (2 dígitos)", "schema": { "type": "string", "example": "05" } }, { "name": "management_type", "in": "query", "required": false, "description": "Tipo de gestão SUS (M, E, D, S)", "schema": { "type": "string", "enum": ["M", "E", "D", "S"], "example": "M" } }, { "name": "legal_nature_code", "in": "query", "required": false, "description": "Código de natureza jurídica CONCLA (4 dígitos)", "schema": { "type": "string", "example": "2062" } }, { "name": "search", "in": "query", "required": false, "description": "Busca textual por código CNES ou razão social/nome fantasia", "schema": { "type": "string", "example": "CLINICAS" } }, { "name": "limit", "in": "query", "required": false, "description": "Limite de registros por página (1 a 250)", "schema": { "type": "integer", "default": 50, "maximum": 250 } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor opaco base64 para keyset pagination", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada de estabelecimentos de saúde", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/facilities/{cnes_code}": { "get": { "tags": ["Facilities"], "summary": "Detalhe do estabelecimento de saúde", "description": "Retorna a projeção canônica Current completa do estabelecimento de saúde identificado pelo código CNES.", "operationId": "getFacilityByCnesCode", "x-susconecta-capability": "facilities.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "cnes_code", "in": "path", "required": true, "description": "Código CNES de 7 dígitos do estabelecimento", "schema": { "type": "string", "example": "5000416" } } ], "responses": { "200": { "description": "Estabelecimento encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityDetailResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/facilities/{cnes_code}/provenance": { "get": { "tags": ["Facilities"], "summary": "Proveniência a nível de atributo do estabelecimento", "description": "Retorna a linhagem de auditoria detalhada de cada atributo projetado do estabelecimento.", "operationId": "getFacilityProvenance", "x-susconecta-capability": "facilities.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "cnes_code", "in": "path", "required": true, "description": "Código CNES de 7 dígitos", "schema": { "type": "string", "example": "5000416" } } ], "responses": { "200": { "description": "Trilha de proveniência do estabelecimento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityProvenanceResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/bed-capacity": { "get": { "tags": ["Bed Capacity"], "summary": "Observações de capacidade mensal de leitos", "description": "Lista os registros de capacidade de leitos cadastrados com filtros por especialidade e macrocategoria.", "operationId": "listBedCapacity", "x-susconecta-capability": "bed_capacity.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "cnes_code", "in": "query", "required": false, "schema": { "type": "string", "example": "5000416" } }, { "name": "municipality_ibge_code", "in": "query", "required": false, "schema": { "type": "integer", "example": 5208707 } }, { "name": "bed_type_code", "in": "query", "required": false, "description": "Código da especialidade de leito (2 dígitos)", "schema": { "type": "string", "example": "33" } }, { "name": "bed_category_code", "in": "query", "required": false, "description": "Código da macrocategoria de leito (1 dígito)", "schema": { "type": "string", "example": "2" } }, { "name": "has_sus_capacity", "in": "query", "required": false, "description": "Filtrar registros com leitos SUS > 0", "schema": { "type": "boolean", "example": true } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada de capacidade de leitos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedCapacityListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/facilities/{cnes_code}/bed-capacity": { "get": { "tags": ["Bed Capacity"], "summary": "Capacidade de leitos de um estabelecimento", "description": "Retorna todos os leitos cadastrados e os totais consolidados para um estabelecimento.", "operationId": "getFacilityBedCapacity", "x-susconecta-capability": "bed_capacity.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "cnes_code", "in": "path", "required": true, "schema": { "type": "string", "example": "5000416" } } ], "responses": { "200": { "description": "Capacidade de leitos do estabelecimento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityBedCapacityResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/facilities/{cnes_code}/bed-capacity/{bed_type_code}/provenance": { "get": { "tags": ["Bed Capacity"], "summary": "Proveniência de capacidade de leito", "description": "Retorna a linhagem de auditoria do registro de leito até o snapshot de origem do DATASUS.", "operationId": "getBedCapacityProvenance", "x-susconecta-capability": "bed_capacity.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "cnes_code", "in": "path", "required": true, "schema": { "type": "string", "example": "5000416" } }, { "name": "bed_type_code", "in": "path", "required": true, "schema": { "type": "string", "example": "33" } } ], "responses": { "200": { "description": "Linhagem do registro de leito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedCapacityProvenanceResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/bed-types": { "get": { "tags": ["Bed Capacity"], "summary": "Catálogo canônico de especialidades de leitos (69 tipos)", "description": "Retorna o catálogo oficial das 69 especialidades de leitos do Ministério da Saúde.", "operationId": "listBedTypes", "x-susconecta-capability": "bed_capacity.read", "security": [{ "ApiKeyBearer": [] }], "responses": { "200": { "description": "Catálogo de especialidades de leitos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedTypeListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/bed-categories": { "get": { "tags": ["Bed Capacity"], "summary": "Catálogo canônico de macrocategorias de leitos (7 categorias)", "description": "Retorna as 7 macrocategorias canônicas oficiais de leitos hospitalares.", "operationId": "listBedCategories", "x-susconecta-capability": "bed_capacity.read", "security": [{ "ApiKeyBearer": [] }], "responses": { "200": { "description": "Catálogo de macrocategorias de leitos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BedCategoryListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/equipment-inventory": { "get": { "tags": ["Equipment Inventory"], "summary": "Inventário quantitativo de equipamentos de saúde", "description": "Consulta itens de inventário quantitativo mensal cadastrado com chave taxonômica composta.", "operationId": "listEquipmentInventory", "x-susconecta-capability": "equipment_inventory.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "cnes_code", "in": "query", "required": false, "schema": { "type": "string", "example": "7743068" } }, { "name": "municipality_ibge_code", "in": "query", "required": false, "schema": { "type": "integer", "example": 5208707 } }, { "name": "equipment_category_code", "in": "query", "required": false, "schema": { "type": "string", "example": "05" } }, { "name": "equipment_type_code", "in": "query", "required": false, "schema": { "type": "string", "example": "52" } }, { "name": "equipment_type_key", "in": "query", "required": false, "schema": { "type": "string", "example": "05:52" } }, { "name": "renem_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "tp_sus_code", "in": "query", "required": false, "schema": { "type": "string", "enum": ["1", "2", "0", "9"] } }, { "name": "has_sus_quantity", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada de itens de inventário", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquipmentInventoryListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/facilities/{cnes_code}/equipment-inventory": { "get": { "tags": ["Equipment Inventory"], "summary": "Inventário de equipamentos de um estabelecimento", "description": "Retorna todos os equipamentos vinculados a um estabelecimento e seus totais agregados.", "operationId": "getFacilityEquipmentInventory", "x-susconecta-capability": "equipment_inventory.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "cnes_code", "in": "path", "required": true, "schema": { "type": "string", "example": "7743068" } } ], "responses": { "200": { "description": "Inventário de equipamentos do estabelecimento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityEquipmentInventoryResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/facilities/{cnes_code}/equipment-inventory/{category_code}/{equipment_code}/provenance": { "get": { "tags": ["Equipment Inventory"], "summary": "Proveniência de item de equipamento", "description": "Retorna a linhagem de auditoria do registro de equipamento até o snapshot bruto do DATASUS.", "operationId": "getEquipmentProvenance", "x-susconecta-capability": "equipment_inventory.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "cnes_code", "in": "path", "required": true, "schema": { "type": "string", "example": "7743068" } }, { "name": "category_code", "in": "path", "required": true, "schema": { "type": "string", "example": "05" } }, { "name": "equipment_code", "in": "path", "required": true, "schema": { "type": "string", "example": "52" } } ], "responses": { "200": { "description": "Linhagem do item de equipamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquipmentProvenanceResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/equipment-categories": { "get": { "tags": ["Equipment Inventory"], "summary": "Catálogo das 16 macrocategorias de equipamentos", "description": "Retorna as 16 macrocategorias taxonômicas oficiais de equipamentos de saúde.", "operationId": "listEquipmentCategories", "x-susconecta-capability": "equipment_inventory.read", "security": [{ "ApiKeyBearer": [] }], "responses": { "200": { "description": "Catálogo de macrocategorias de equipamentos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquipmentCategoryListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/equipment-types": { "get": { "tags": ["Equipment Inventory"], "summary": "Catálogo dos 224 tipos de equipamentos", "description": "Retorna os tipos canônicos de equipamentos com chave composta e código RENEM.", "operationId": "listEquipmentTypes", "x-susconecta-capability": "equipment_inventory.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "category_code", "in": "query", "required": false, "description": "Filtro opcional por macrocategoria", "schema": { "type": "string", "example": "05" } } ], "responses": { "200": { "description": "Catálogo de tipos de equipamentos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquipmentTypeListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/equipment-types/{category_code}/{equipment_code}": { "get": { "tags": ["Equipment Inventory"], "summary": "Detalhe taxonômico de tipo de equipamento", "description": "Retorna a definição canônica do tipo de equipamento identificado pela chave composta.", "operationId": "getEquipmentTypeByKey", "x-susconecta-capability": "equipment_inventory.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "category_code", "in": "path", "required": true, "schema": { "type": "string", "example": "05" } }, { "name": "equipment_code", "in": "path", "required": true, "schema": { "type": "string", "example": "52" } } ], "responses": { "200": { "description": "Tipo de equipamento encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquipmentTypeDetailResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/specialized-service-offerings": { "get": { "tags": ["Specialized Services"], "summary": "Declarações cadastradas de ofertas de serviços especializados", "description": "Lista as ofertas de serviços especializados vinculadas a estabelecimentos de saúde com filtros de modalidades SUS e ambulatorial/hospitalar.", "operationId": "listSpecializedServiceOfferings", "x-susconecta-capability": "specialized_services.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "cnes_code", "in": "query", "required": false, "schema": { "type": "string", "example": "5000416" } }, { "name": "municipality_ibge_code", "in": "query", "required": false, "schema": { "type": "integer", "example": 5208707 } }, { "name": "service_code", "in": "query", "required": false, "schema": { "type": "string", "example": "100" } }, { "name": "classification_code", "in": "query", "required": false, "schema": { "type": "string", "example": "001" } }, { "name": "classification_key", "in": "query", "required": false, "schema": { "type": "string", "example": "100:001" } }, { "name": "characteristic_code", "in": "query", "required": false, "schema": { "type": "string", "enum": ["1", "2", "3"] } }, { "name": "provider_kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "CNES", "CNPJ", "NOT_INFORMED", "NOT_APPLICABLE", "OTHER_SENTINEL" ] } }, { "name": "has_ambulatory", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "has_ambulatory_sus", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "has_hospital", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "has_hospital_sus", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "offers_any_sus", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada de ofertas de serviços especializados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecializedServiceOfferingsListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/facilities/{cnes_code}/specialized-services": { "get": { "tags": ["Specialized Services"], "summary": "Serviços especializados ofertados por um estabelecimento", "description": "Retorna todas as declarações de serviços vinculadas a um estabelecimento específico.", "operationId": "getFacilitySpecializedServices", "x-susconecta-capability": "specialized_services.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "cnes_code", "in": "path", "required": true, "schema": { "type": "string", "example": "5000416" } } ], "responses": { "200": { "description": "Serviços especializados do estabelecimento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilitySpecializedServicesResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/facilities/{cnes_code}/specialized-services/{service_code}/{classification_code}/provenance": { "get": { "tags": ["Specialized Services"], "summary": "Proveniência da oferta de serviço especializado", "description": "Retorna a linhagem de auditoria da declaração de serviço até o snapshot bruto do DATASUS.", "operationId": "getSpecializedServiceProvenance", "x-susconecta-capability": "specialized_services.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "cnes_code", "in": "path", "required": true, "schema": { "type": "string", "example": "5000416" } }, { "name": "service_code", "in": "path", "required": true, "schema": { "type": "string", "example": "100" } }, { "name": "classification_code", "in": "path", "required": true, "schema": { "type": "string", "example": "001" } } ], "responses": { "200": { "description": "Linhagem do serviço especializado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecializedServiceProvenanceResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/specialized-service-types": { "get": { "tags": ["Specialized Services"], "summary": "Catálogo dos 73 tipos de serviços especializados nacionais", "description": "Retorna os 73 tipos canônicos de serviços especializados homologados pelo Ministério da Saúde.", "operationId": "listSpecializedServiceTypes", "x-susconecta-capability": "specialized_services.read", "security": [{ "ApiKeyBearer": [] }], "responses": { "200": { "description": "Catálogo de serviços especializados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecializedServiceTypeListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/specialized-service-classifications": { "get": { "tags": ["Specialized Services"], "summary": "Catálogo das 459 classificações de serviços especializados", "description": "Retorna as 459 classificações canônicas nacionais com chave taxonômica composta.", "operationId": "listSpecializedServiceClassifications", "x-susconecta-capability": "specialized_services.read", "security": [{ "ApiKeyBearer": [] }], "responses": { "200": { "description": "Catálogo de classificações de serviços", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecializedServiceClassificationListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/specialized-service-types/{service_code}/classifications/{classification_code}": { "get": { "tags": ["Specialized Services"], "summary": "Detalhe da classificação de serviço especializado", "description": "Retorna os dados da classificação identificada pela chave composta (serviço:classificação).", "operationId": "getSpecializedServiceClassificationByKey", "x-susconecta-capability": "specialized_services.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "service_code", "in": "path", "required": true, "schema": { "type": "string", "example": "100" } }, { "name": "classification_code", "in": "path", "required": true, "schema": { "type": "string", "example": "001" } } ], "responses": { "200": { "description": "Classificação de serviço encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpecializedServiceClassificationDetailResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/demography/population": { "get": { "tags": ["Demography"], "summary": "Listagem paginada de estimativas populacionais municipais", "description": "Consulta estimativas e projeções populacionais dos municípios a partir de bases oficiais do IBGE.", "operationId": "listDemographyPopulation", "x-susconecta-capability": "demography.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "example": "GO" } }, { "name": "municipality", "in": "query", "required": false, "schema": { "type": "string", "example": "5208707" } }, { "name": "reference_year", "in": "query", "required": false, "schema": { "type": "string", "example": "2026" } }, { "name": "population_type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["ESTIMATED_POPULATION", "CENSUS_POPULATION"], "default": "ESTIMATED_POPULATION" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "default": "50" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "expected_release_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada de estimativas populacionais", "headers": { "x-demography-release-id": { "description": "Identificador da release demográfica", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemographyPopulationListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/demography/population/{municipalityCode}": { "get": { "tags": ["Demography"], "summary": "Consulta de população por código IBGE do município", "description": "Retorna a população municipal oficial pelo código IBGE de 7 dígitos.", "operationId": "getDemographyPopulationByMunicipality", "x-susconecta-capability": "demography.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "municipalityCode", "in": "path", "required": true, "schema": { "type": "string", "example": "5208707" } }, { "name": "reference_year", "in": "query", "required": false, "schema": { "type": "string", "example": "2026" } }, { "name": "population_type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["ESTIMATED_POPULATION", "CENSUS_POPULATION"] } } ], "responses": { "200": { "description": "Dados demográficos do município", "headers": { "x-demography-release-id": { "description": "Identificador da release demográfica", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemographyPopulationDetailResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/analytics/catalog": { "get": { "tags": ["Analytics Catalog"], "summary": "Catálogo semântico dinâmico de métricas e dimensões", "description": "Retorna o catálogo semântico de indicadores e dimensões acessíveis pela chave autenticada.", "operationId": "getAnalyticsCatalog", "x-susconecta-capability": "analytics.catalog.read", "security": [{ "ApiKeyBearer": [] }], "responses": { "200": { "description": "Catálogo semântico dinâmico", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsCatalogResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/analytics/dimensions/{dimensionCode}/values": { "get": { "tags": ["Analytics Catalog"], "summary": "Descoberta paginada de valores das 15 dimensões analíticas", "description": "Retorna a lista paginada de valores discretos para preenchimento de filtros e seletores.", "operationId": "getDimensionValues", "x-susconecta-capability": "analytics.catalog.read", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "dimensionCode", "in": "path", "required": true, "description": "Código da dimensão analítica", "schema": { "type": "string", "enum": [ "state", "municipality", "facility", "facility_type", "management_type", "legal_nature", "bed_category", "bed_type", "equipment_category", "equipment_type", "specialized_service", "specialized_service_classification", "service_characteristic", "provider_kind", "reference_period" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 250 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Valores da dimensão retornados com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DimensionValuesResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/analytics/query": { "post": { "tags": ["Analytics Query"], "summary": "Execução de consultas analíticas estruturadas e seguras", "description": "Executa agregações multidimensionais sobre métricas canônicas com suporte a ordenação, paginação e release pinning.", "operationId": "executeAnalyticsQuery", "x-susconecta-capability": "analytics.query.read", "security": [{ "ApiKeyBearer": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsQueryRequest" } } } }, "responses": { "200": { "description": "Resultado da consulta analítica", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsQueryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "409": { "$ref": "#/components/responses/ConflictReleaseError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/analytics/exports/xlsx": { "post": { "tags": ["Analytics Query"], "summary": "Exportação de consultas analíticas em formato XLSX auditável", "description": "Gera uma planilha XLSX auditável contendo os dados da consulta analítica e manifesto de integridade integrado.", "operationId": "exportAnalyticsXlsx", "x-susconecta-capability": "analytics.query.read", "security": [{ "ApiKeyBearer": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsExportRequest" } } } }, "responses": { "200": { "description": "Arquivo XLSX gerado com sucesso", "headers": { "Content-Disposition": { "description": "Cabeçalho com nome do arquivo para download", "schema": { "type": "string", "example": "attachment; filename=\"susconecta_relatorio_analitico_20260929.xlsx\"" } }, "x-analytics-release-id": { "description": "Identificador da release analítica utilizada", "schema": { "type": "string" } }, "x-report-fingerprint": { "description": "Fingerprint SHA-256 de reprodutibilidade", "schema": { "type": "string" } }, "x-artifact-sha256": { "description": "Hash SHA-256 do arquivo binário gerado", "schema": { "type": "string" } }, "x-report-row-count": { "description": "Total de linhas no relatório", "schema": { "type": "string" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "409": { "$ref": "#/components/responses/ConflictReleaseError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/analytics/export/xlsx": { "post": { "tags": ["Analytics Query"], "summary": "Alias para /v1/analytics/exports/xlsx", "description": "Endpoint alias para compatibilidade com clientes externos. Executa exatamente o mesmo processamento de /v1/analytics/exports/xlsx.", "operationId": "exportAnalyticsXlsxAlias", "x-susconecta-capability": "analytics.query.read", "security": [{ "ApiKeyBearer": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsExportRequest" } } } }, "responses": { "200": { "description": "Arquivo XLSX gerado com sucesso", "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "x-analytics-release-id": { "schema": { "type": "string" } }, "x-report-fingerprint": { "schema": { "type": "string" } }, "x-artifact-sha256": { "schema": { "type": "string" } }, "x-report-row-count": { "schema": { "type": "string" } } }, "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "409": { "$ref": "#/components/responses/ConflictReleaseError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Token de API de longa duração fornecido pelo SusConecta transmitido no header HTTP Authorization." } }, "schemas": { "Meta": { "type": "object", "required": ["timestamp", "version"], "properties": { "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-29T12:00:00.000Z" }, "version": { "type": "string", "description": "Versão de compilação/deploy do microservice de API (Application Package Version)", "example": "0.1.0" }, "request_id": { "type": "string", "example": "req-123456" } } }, "ErrorDetail": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string", "example": "FORBIDDEN" }, "message": { "type": "string", "example": "Insufficient capabilities. Requires facilities.read" }, "request_id": { "type": "string", "example": "req-123456" } } }, "ErrorResponse": { "type": "object", "required": ["status", "error"], "properties": { "status": { "type": "string", "enum": ["error"], "example": "error" }, "error": { "$ref": "#/components/schemas/ErrorDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "HealthResponse": { "type": "object", "required": ["status", "data", "meta"], "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "status": { "type": "string", "example": "healthy" }, "uptime": { "type": "number", "example": 3600.5 }, "environment": { "type": "string", "example": "production" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ReadyResponse": { "type": "object", "required": ["status", "database"], "properties": { "status": { "type": "string", "example": "ready" }, "database": { "type": "string", "example": "available" } } }, "NotReadyResponse": { "type": "object", "required": ["status", "database"], "properties": { "status": { "type": "string", "example": "not_ready" }, "database": { "type": "string", "example": "unavailable" } } }, "State": { "type": "object", "required": ["ibge_code", "uf", "name", "region"], "properties": { "ibge_code": { "type": "integer", "example": 52 }, "uf": { "type": "string", "example": "GO" }, "name": { "type": "string", "example": "Goiás" }, "region": { "type": "string", "example": "CENTRO-OESTE" } } }, "StateListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/State" } } } }, "StateDetailResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/State" } } }, "Municipality": { "type": "object", "required": ["ibge_code", "name", "state_uf"], "properties": { "ibge_code": { "type": "integer", "example": 5208707 }, "name": { "type": "string", "example": "Goiânia" }, "state_uf": { "type": "string", "example": "GO" }, "state_ibge_code": { "type": "integer", "example": 52 }, "territorial_type": { "type": "string", "example": "MUNICIPALITY" } } }, "MunicipalityListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Municipality" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "next_cursor": { "type": "string", "nullable": true, "example": "NTIwODcwNw==" }, "has_more": { "type": "boolean", "example": true } } } } }, "MunicipalityDetailResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/Municipality" } } }, "FacilitySummary": { "type": "object", "required": ["cnes_code"], "properties": { "cnes_code": { "type": "string", "example": "5000416" }, "trade_name": { "type": "string", "nullable": true, "example": "HOSPITAL DAS CLINICAS" }, "legal_name": { "type": "string", "nullable": true, "example": "UNIVERSIDADE FEDERAL DE GOIAS" }, "municipality": { "type": "object", "properties": { "ibge_code": { "type": "integer", "example": 5208707 }, "name": { "type": "string", "example": "Goiânia" }, "uf": { "type": "string", "example": "GO" } } }, "facility_type": { "type": "object", "properties": { "code": { "type": "string", "example": "05" }, "name": { "type": "string", "example": "HOSPITAL GERAL" } } }, "management_type": { "type": "object", "nullable": true, "properties": { "code": { "type": "string", "example": "M" }, "name": { "type": "string", "example": "Municipal" } } }, "legal_nature": { "type": "object", "nullable": true, "properties": { "code": { "type": "string", "example": "110-4" }, "name": { "type": "string", "example": "Autarquia Federal" }, "kind": { "type": "string", "example": "LEAF" } } } } }, "FacilityListResponse": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FacilitySummary" } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "count": { "type": "integer", "example": 50 }, "next_cursor": { "type": "string", "nullable": true, "example": "NTAwMDQxNg==" }, "as_of_reference_period": { "type": "string", "example": "202607" } } } } }, "FacilityDetailResponse": { "type": "object", "required": ["data"], "properties": { "data": { "$ref": "#/components/schemas/FacilitySummary" } } }, "FacilityProvenanceResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "properties": { "cnes_code": { "type": "string", "example": "5000416" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "field_name": { "type": "string", "example": "management_type" }, "selected_value": { "type": "string", "example": "M" }, "selection_rule": { "type": "string", "example": "FEDERAL_MISSING_USE_SES" }, "has_conflict": { "type": "boolean", "example": false } } } } } } } }, "BedCapacityListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "cnes_code": { "type": "string", "example": "5000416" }, "bed_type": { "type": "object", "properties": { "code": { "type": "string", "example": "33" }, "name": { "type": "string", "example": "CLINICA GERAL" } } }, "bed_category": { "type": "object", "properties": { "code": { "type": "string", "example": "2" }, "name": { "type": "string", "example": "CLÍNICO" } } }, "capacity": { "type": "object", "properties": { "existing": { "type": "integer", "example": 20 }, "sus": { "type": "integer", "example": 20 }, "non_sus": { "type": "integer", "example": 0 }, "contracted": { "type": "integer", "example": 0 } } } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 25 }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean", "example": true } } } } }, "FacilityBedCapacityResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "properties": { "cnes_code": { "type": "string", "example": "5000416" }, "items": { "type": "array", "items": { "type": "object" } }, "totals": { "type": "object", "properties": { "existing": { "type": "integer" }, "sus": { "type": "integer" }, "non_sus": { "type": "integer" } } } } } } }, "BedCapacityProvenanceResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object" } } }, "BedTypeListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "33" }, "name": { "type": "string", "example": "CLINICA GERAL" } } } } } }, "BedCategoryListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "2" }, "name": { "type": "string", "example": "CLÍNICO" } } } } } }, "EquipmentInventoryListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "cnes_code": { "type": "string", "example": "7743068" }, "equipment_type_key": { "type": "string", "example": "05:52" }, "inventory": { "type": "object", "properties": { "existing": { "type": "integer", "example": 2371 }, "in_use": { "type": "integer", "example": 2349 }, "sus": { "type": "integer", "example": 2337 }, "non_sus": { "type": "integer", "example": 34 } } } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean", "example": true } } } } }, "FacilityEquipmentInventoryResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "properties": { "cnes_code": { "type": "string", "example": "7743068" }, "items": { "type": "array", "items": { "type": "object" } }, "totals": { "type": "object" } } } } }, "EquipmentProvenanceResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object" } } }, "EquipmentCategoryListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "05" }, "name": { "type": "string", "example": "MANUTENCAO DA VIDA" } } } } } }, "EquipmentTypeListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "52" }, "name": { "type": "string", "example": "BOMBA DE INFUSAO" } } } } } }, "EquipmentTypeDetailResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object" } } }, "SpecializedServiceOfferingsListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "cnes_code": { "type": "string", "example": "5000416" }, "specialized_service": { "type": "object", "properties": { "code": { "type": "string", "example": "100" }, "name": { "type": "string", "example": "SERVICO DE ATENCAO A SAUDE AUDITIVA" } } }, "classification": { "type": "object", "properties": { "code": { "type": "string", "example": "001" }, "name": { "type": "string", "example": "ATENCAO BASICA A SAUDE AUDITIVA" } } }, "classification_key": { "type": "string", "example": "100:001" }, "modalities": { "type": "object", "properties": { "has_ambulatory": { "type": "boolean", "example": true }, "has_ambulatory_sus": { "type": "boolean", "example": true }, "has_hospital": { "type": "boolean", "example": false }, "has_hospital_sus": { "type": "boolean", "example": false }, "offers_any_sus": { "type": "boolean", "example": true } } } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean", "example": true } } } } }, "FacilitySpecializedServicesResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "properties": { "cnes_code": { "type": "string", "example": "5000416" }, "items": { "type": "array", "items": { "type": "object" } } } } } }, "SpecializedServiceProvenanceResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object" } } }, "SpecializedServiceTypeListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "100" }, "name": { "type": "string", "example": "SERVICO DE ATENCAO A SAUDE AUDITIVA" } } } } } }, "SpecializedServiceClassificationListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "001" }, "name": { "type": "string", "example": "ATENCAO BASICA A SAUDE AUDITIVA" } } } } } }, "SpecializedServiceClassificationDetailResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object" } } }, "DemographyPopulationListResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "municipality_ibge_code": { "type": "integer", "example": 5208707 }, "municipality_name": { "type": "string", "example": "Goiânia" }, "state_uf": { "type": "string", "example": "GO" }, "reference_year": { "type": "integer", "example": 2026 }, "population_type": { "type": "string", "example": "ESTIMATED_POPULATION" }, "total_population": { "type": "integer", "example": 1494599 } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean", "example": true } } } } }, "DemographyPopulationDetailResponse": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "properties": { "municipality_ibge_code": { "type": "integer", "example": 5208707 }, "municipality_name": { "type": "string", "example": "Goiânia" }, "state_uf": { "type": "string", "example": "GO" }, "reference_year": { "type": "integer", "example": 2026 }, "total_population": { "type": "integer", "example": 1494599 } } } } }, "AnalyticsCatalogResponse": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "version": { "type": "string", "example": "1.1.0" }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "facilities_count" }, "label": { "type": "string", "example": "Estabelecimentos de Saúde" }, "domain": { "type": "string", "example": "FACILITIES" }, "unit": { "type": "string", "example": "facilities" }, "metric_kind": { "type": "string", "example": "DIRECT_AGGREGATE" }, "additivity": { "type": "string", "example": "NON_ADDITIVE_DISTINCT" } } } }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "municipality" }, "label": { "type": "string", "example": "Município" } } } } } } } }, "DimensionValuesResponse": { "type": "object", "required": ["status", "data", "meta"], "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "05" }, "label": { "type": "string", "example": "HOSPITAL GERAL" } } } }, "meta": { "type": "object", "properties": { "dimension": { "type": "string", "example": "facility_type" }, "total_count": { "type": "integer", "example": 34 }, "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 } } } } }, "AnalyticsFilter": { "type": "object", "required": ["dimension", "operator", "value"], "properties": { "dimension": { "type": "string", "example": "state" }, "operator": { "type": "string", "enum": ["EQ", "IN", "BOOLEAN_EQ", "SEARCH"], "example": "EQ" }, "value": { "description": "Valor ou lista de valores para filtragem", "example": "GO" } } }, "AnalyticsOrderBy": { "type": "object", "required": ["field", "direction"], "properties": { "field": { "type": "string", "example": "facilities_count" }, "direction": { "type": "string", "enum": ["ASC", "DESC"], "example": "DESC" } } }, "AnalyticsQueryRequest": { "type": "object", "required": ["metrics"], "properties": { "metrics": { "type": "array", "minItems": 1, "items": { "type": "string" }, "example": ["facilities_count"] }, "group_by": { "type": "array", "maxItems": 3, "items": { "type": "string" }, "example": ["municipality"] }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsFilter" } }, "order_by": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsOrderBy" } }, "limit": { "type": "integer", "default": 100, "maximum": 500, "example": 100 }, "offset": { "type": "integer", "default": 0, "minimum": 0, "example": 0 }, "expected_release_id": { "type": "string", "description": "Token de release esperada (mandatório quando offset > 0)", "example": "CNES-GO-202607-71d4baecb58a56ffdc9f3062649acf232b309832d59bc39ffa4857cfc051cfa7" } } }, "AnalyticsExportRequest": { "type": "object", "required": ["metrics"], "properties": { "metrics": { "type": "array", "minItems": 1, "items": { "type": "string" }, "example": ["facilities_count"] }, "group_by": { "type": "array", "maxItems": 3, "items": { "type": "string" }, "example": ["municipality"] }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsFilter" } }, "order_by": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsOrderBy" } } } }, "AnalyticsQueryResponse": { "type": "object", "required": ["status", "data", "meta"], "properties": { "status": { "type": "string", "example": "SUCCESS" }, "data": { "type": "array", "items": { "type": "object", "properties": { "dimensions": { "type": "object" }, "metrics": { "type": "object" } } } }, "meta": { "type": "object", "properties": { "catalog_version": { "type": "string", "example": "1.1.0" }, "analytics_release_id": { "type": "string", "example": "CNES-GO-202607-71d4baecb58a56ffdc9f3062649acf232b309832d59bc39ffa4857cfc051cfa7" }, "reference_period": { "type": "string", "example": "202607" }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 100 }, "offset": { "type": "integer", "example": 0 }, "has_more": { "type": "boolean", "example": true } } } } } } } }, "responses": { "BadRequestError": { "description": "Requisição inválida ou parâmetros incorretos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnauthorizedError": { "description": "Token de autenticação ausente ou inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ForbiddenError": { "description": "Permissão (capability) insuficiente para o recurso solicitado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFoundError": { "description": "Recurso não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ConflictReleaseError": { "description": "Release de dados atualizada durante a paginação (requer reinício da consulta a partir do offset 0)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimitError": { "description": "Limite de taxa excedido (120 req/min por machine API/IP)", "headers": { "X-RateLimit-Limit": { "description": "Limite de requisições por janela", "schema": { "type": "integer", "example": 120 } }, "X-RateLimit-Remaining": { "description": "Requisições restantes", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Timestamp UTC de reinício da janela", "schema": { "type": "integer" } }, "Retry-After": { "description": "Tempo em segundos antes de reenviar a requisição", "schema": { "type": "integer", "example": 45 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "Erro interno inesperado no servidor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }