{"openapi":"3.1.0","info":{"title":"Sistema Unimed — API privada da AxiaCare","version":"0.3.0","description":"Catálogo institucional privado do Sistema Unimed, publicado atomicamente por release. Respostas protegidas informam o snapshot em X-Catalog-Release. O tenant canônico é axiacare; axia é aceito somente como alias legado das sessões do Hub. Para consumo automatizado de logotipos, a rota /v1/entities/{code}/logos usa por padrão os quatro PNGs principais; SVG, PDF e AI são secundários. Credenciais nunca são aceitas na query string.","license":{"name":"Proprietário — Grupo CSV","identifier":"LicenseRef-Proprietary"}},"servers":[{"url":"https://api.grupocsv.com/unimed","description":"Produção"}],"security":[{"HubSession":[]},{"BearerApiKey":[]}],"tags":[{"name":"Operação","description":"Saúde e descoberta do contrato."},{"name":"Catálogo","description":"Entidades, metadados e classificações institucionais."},{"name":"Assets","description":"Metadados, previews e originais mantidos no R2 privado."},{"name":"Recursos","description":"Documentos e referências extensíveis do Sistema Unimed."}],"paths":{"/health":{"get":{"tags":["Operação"],"summary":"Verifica a disponibilidade do Worker e dos bindings","operationId":"health","security":[],"responses":{"200":{"description":"Serviço disponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/meta":{"get":{"tags":["Catálogo"],"summary":"Retorna metadados e capacidades do catálogo","operationId":"getMeta","responses":{"200":{"description":"Metadados do catálogo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/entities":{"get":{"tags":["Catálogo"],"summary":"Pesquisa entidades do Sistema Unimed","operationId":"listEntities","parameters":[{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Uf"},{"$ref":"#/components/parameters/TypePtu"},{"$ref":"#/components/parameters/InstitutionalType"},{"$ref":"#/components/parameters/TypeAlias"},{"$ref":"#/components/parameters/OperationalRole"},{"$ref":"#/components/parameters/AnsStatus"},{"$ref":"#/components/parameters/HasAssets"},{"$ref":"#/components/parameters/IncludeTests"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Página de entidades ordenada por código","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/entities/{code}":{"get":{"tags":["Catálogo"],"summary":"Obtém uma entidade por código","description":"Aceita de um a quatro dígitos. Por exemplo, 236 é normalizado para 0236. Códigos canônicos têm precedência; aliases de código ambíguos retornam 409.","operationId":"getEntity","parameters":[{"$ref":"#/components/parameters/EntityCode"}],"responses":{"200":{"description":"Entidade encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityDetailResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/entities/{code}/assets":{"get":{"tags":["Assets"],"summary":"Lista os assets ativos de uma entidade","operationId":"listEntityAssets","parameters":[{"$ref":"#/components/parameters/EntityCode"}],"responses":{"200":{"description":"Assets da entidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/entities/{code}/logos":{"get":{"tags":["Assets"],"summary":"Lista o conjunto canônico de logotipos de uma entidade","description":"Rota recomendada para agentes e integrações. Sem o parâmetro set, retorna os quatro PNGs principais, um por composição normativa. Use set=secondary para SVG, PDF e AI, ou set=all para todo o acervo.","operationId":"listEntityLogos","parameters":[{"$ref":"#/components/parameters/EntityCode"},{"name":"set","in":"query","required":false,"description":"Conjunto de uso. primary é o padrão recomendado e retorna PNG; secondary retorna SVG, PDF e AI; all retorna ambos.","schema":{"type":"string","enum":["primary","secondary","all"],"default":"primary"}}],"responses":{"200":{"description":"Conjunto de logotipos da entidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/assets/{asset_id}/download":{"get":{"tags":["Assets"],"summary":"Transmite um asset diretamente do R2 privado","description":"Exige o escopo assets:download. A resposta é sempre privada e não armazenável em cache.","operationId":"downloadAsset","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"Stream binário do asset","headers":{"Content-Disposition":{"schema":{"type":"string"}},"ETag":{"schema":{"type":"string"}},"X-Asset-SHA256":{"schema":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$"}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/svg+xml":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/assets/{asset_id}/preview":{"get":{"tags":["Assets"],"summary":"Transmite um preview estático do R2 privado","description":"Exige catalog:read. Somente image/webp e image/png são servidos, sempre inline e sem cache.","operationId":"previewAsset","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"Stream do preview","headers":{"Content-Disposition":{"schema":{"type":"string"}},"ETag":{"schema":{"type":"string"}}},"content":{"image/webp":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/resources":{"get":{"tags":["Recursos"],"summary":"Pesquisa recursos institucionais versionados","operationId":"listResources","parameters":[{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Uf"},{"$ref":"#/components/parameters/ResourceCategory"},{"$ref":"#/components/parameters/DocumentType"},{"$ref":"#/components/parameters/ResourceEntityCode"},{"$ref":"#/components/parameters/IncludeTests"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Página de recursos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/openapi.json":{"get":{"tags":["Operação"],"summary":"Retorna este contrato OpenAPI 3.1","operationId":"getOpenApi","security":[],"responses":{"200":{"description":"Documento OpenAPI","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"components":{"securitySchemes":{"HubSession":{"type":"apiKey","in":"header","name":"X-Auth-Token","description":"Sessão ativa do Hub para o tenant canônico axiacare. O alias legado axia é normalizado para AxiaCare."},"BearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"Chave individual opaca, armazenada somente como SHA-256, com escopos catalog:read, assets:download e/ou admin."}},"parameters":{"Query":{"name":"q","in":"query","schema":{"type":"string","maxLength":120},"description":"Nome, alias ou código. A busca textual ignora acentos conforme o campo normalizado na ingestão."},"Uf":{"name":"uf","in":"query","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"TypePtu":{"name":"type_ptu","in":"query","schema":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$"}},"InstitutionalType":{"name":"institutional_type","in":"query","schema":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$"}},"TypeAlias":{"name":"type","in":"query","description":"Filtro amplo: corresponde a institutional_type OU type_ptu. Não pode ser combinado com esses dois filtros específicos.","schema":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$"}},"OperationalRole":{"name":"operational_role","in":"query","schema":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$"}},"AnsStatus":{"name":"ans_status","in":"query","schema":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$"}},"HasAssets":{"name":"has_assets","in":"query","schema":{"type":"boolean"}},"IncludeTests":{"name":"include_tests","in":"query","description":"Exige o escopo admin quando verdadeiro.","schema":{"type":"boolean","default":false}},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":24}},"Cursor":{"name":"cursor","in":"query","description":"Cursor opaco, vinculado ao conjunto exato de filtros e à release ativa. Uma ativação invalida cursores anteriores.","schema":{"type":"string","maxLength":1024}},"EntityCode":{"name":"code","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,4}$"}},"ResourceCategory":{"name":"category","in":"query","schema":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$"}},"DocumentType":{"name":"document_type","in":"query","schema":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$"}},"ResourceEntityCode":{"name":"entity_code","in":"query","schema":{"type":"string","pattern":"^\\d{1,4}$"}}},"responses":{"BadRequest":{"description":"Parâmetro, cursor ou credencial em query inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Sessão ou chave ausente, inválida ou expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Tenant, origem ou escopo não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Recurso não encontrado ou oculto pela política de testes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"Método HTTP não permitido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Alias de código ambíguo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailable":{"description":"Dependência, auditoria, integridade ou release ativa indisponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"RequestMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid"}}},"ErrorResponse":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"$ref":"#/components/schemas/RequestMeta"}}},"Health":{"type":"object","required":["status","service","version","timestamp","dependencies"],"properties":{"status":{"type":"string","enum":["ok","unavailable"]},"service":{"const":"unimed-system"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"dependencies":{"type":"object","properties":{"database":{"type":"string","enum":["ok","unavailable"]},"assets":{"type":"string","enum":["configured","unavailable"]}}}}},"Ans":{"type":["object","null"],"properties":{"registration":{"type":["string","null"]},"status":{"type":["string","null"]},"modality":{"type":["string","null"]}}},"Curation":{"type":"object","required":["status","confidence"],"properties":{"status":{"type":"string"},"confidence":{"type":"string"},"evidence_url":{"type":["string","null"],"format":"uri"},"verified_at":{"type":["string","null"],"format":"date-time"},"valid_from":{"type":["string","null"],"format":"date-time"},"valid_to":{"type":["string","null"],"format":"date-time"}}},"Entity":{"type":"object","required":["code","source_code","name","type_ptu","institutional_type","operational_role","is_test","curation","provenance","visible_by_default","assets","updated_at"],"properties":{"code":{"type":"string","pattern":"^\\d{4}$","examples":["0236"]},"source_code":{"type":"string","examples":["236"]},"name":{"type":"string","examples":["Unimed Governador Valadares"]},"uf":{"type":["string","null"],"pattern":"^[A-Z]{2}$"},"type_ptu":{"type":"string"},"institutional_type":{"type":"string"},"operational_role":{"type":"string"},"ans":{"$ref":"#/components/schemas/Ans"},"is_test":{"type":"boolean"},"curation":{"$ref":"#/components/schemas/Curation"},"provenance":{"type":"object","required":["sources","classification_method","classification_criterion","source_line"],"properties":{"sources":{"type":"array","items":{"type":"object","additionalProperties":true}},"classification_method":{"type":["string","null"]},"classification_criterion":{"type":["string","null"]},"source_line":{"type":["integer","null"],"minimum":1}}},"visible_by_default":{"type":"boolean"},"assets":{"type":"object","required":["count","variant_count","complete_four_variants"],"properties":{"count":{"type":"integer","minimum":0},"variant_count":{"type":"integer","minimum":0},"complete_four_variants":{"type":"boolean"}}},"updated_at":{"type":"string","format":"date-time"}}},"EntityListResponse":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Entity"}},"meta":{"$ref":"#/components/schemas/PageMeta"},"links":{"$ref":"#/components/schemas/PageLinks"}}},"EntityDetailResponse":{"type":"object","required":["data","meta","links"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Entity"},{"type":"object","properties":{"aliases":{"type":"array","items":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"type":"string"}}}}}}]},"meta":{"$ref":"#/components/schemas/RequestMeta"},"links":{"type":"object","additionalProperties":{"type":["string","null"],"format":"uri"}}}},"Asset":{"type":"object","required":["asset_id","entity_code","variant","has_box","has_symbol","format","is_default","usage_tier","original_filename","media_type","size_bytes","sha256","download_url","preview_url","updated_at"],"properties":{"asset_id":{"type":"string"},"entity_code":{"type":"string","pattern":"^\\d{4}$"},"variant":{"type":"string","enum":["box_pinheiro","box","sem_box_pinheiro","sem_box"]},"has_box":{"type":"boolean"},"has_symbol":{"type":"boolean"},"format":{"type":"string","enum":["ai","pdf","png","svg"]},"is_default":{"type":"boolean","description":"Verdadeiro para o PNG principal da composição."},"usage_tier":{"type":"string","enum":["primary","secondary"],"description":"PNGs são primários; SVG, PDF e AI são secundários."},"original_filename":{"type":"string"},"media_type":{"type":"string"},"size_bytes":{"type":"integer","minimum":0},"sha256":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$"},"width_px":{"type":["integer","null"],"minimum":1},"height_px":{"type":["integer","null"],"minimum":1},"has_transparency":{"type":["boolean","null"]},"version":{"type":["string","null"]},"download_url":{"type":"string","format":"uri"},"preview_url":{"type":["string","null"],"format":"uri"},"updated_at":{"type":"string","format":"date-time"}}},"AssetListResponse":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"meta":{"allOf":[{"$ref":"#/components/schemas/RequestMeta"},{"type":"object","properties":{"entity_code":{"type":"string","pattern":"^\\d{4}$"},"total":{"type":"integer","minimum":0},"set":{"type":"string","enum":["primary","secondary","all"]},"recommended_set":{"type":"string","const":"primary"},"default_format":{"type":"string","const":"png"},"primary_png_count":{"type":"integer","minimum":0},"complete_primary_png_set":{"type":"boolean"},"missing_primary_variants":{"type":"array","items":{"type":"string","enum":["box_pinheiro","box","sem_box_pinheiro","sem_box"]}},"duplicate_primary_variants":{"type":"array","items":{"type":"string","enum":["box_pinheiro","box","sem_box_pinheiro","sem_box"]}}}}]},"links":{"type":"object","additionalProperties":{"type":["string","null"],"format":"uri"}}}},"Resource":{"type":"object","required":["resource_id","category","document_type","title","has_private_asset","created_at","updated_at"],"properties":{"resource_id":{"type":"string"},"entity_code":{"type":["string","null"],"pattern":"^\\d{4}$"},"category":{"type":"string"},"document_type":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"uf":{"type":["string","null"],"pattern":"^[A-Z]{2}$"},"version":{"type":["string","null"]},"published_at":{"type":["string","null"],"format":"date-time"},"source_url":{"type":["string","null"],"format":"uri"},"original_filename":{"type":["string","null"]},"media_type":{"type":["string","null"]},"size_bytes":{"type":["integer","null"],"minimum":0},"sha256":{"type":["string","null"],"pattern":"^[A-Fa-f0-9]{64}$"},"has_private_asset":{"type":"boolean"},"metadata":{"type":["object","null"],"additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ResourceListResponse":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Resource"}},"meta":{"$ref":"#/components/schemas/PageMeta"},"links":{"$ref":"#/components/schemas/PageLinks"}}},"PageMeta":{"type":"object","required":["request_id","limit","returned","has_more","next_cursor","filters"],"properties":{"request_id":{"type":"string","format":"uuid"},"limit":{"type":"integer"},"returned":{"type":"integer"},"total":{"type":"integer","minimum":0,"description":"Contagem dos filtros antes da aplicação do cursor. Presente na listagem de entidades."},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"filters":{"type":"object","additionalProperties":true}}},"PageLinks":{"type":"object","required":["self","next"],"properties":{"self":{"type":"string","format":"uri"},"next":{"type":["string","null"],"format":"uri"}}},"MetaResponse":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"object","additionalProperties":true},"meta":{"$ref":"#/components/schemas/RequestMeta"},"links":{"type":"object","additionalProperties":{"type":"string","format":"uri"}}}}}}}