API de serviços gerenciados

Estas rotas permitem consultar o catálogo Valkey e operar um projeto gerenciado existente. A criação continua sendo feita pela rota pública de projetos com config.type_project: "valkey", config.profile e o plano correspondente.

Autenticação e permissões

Envie a autenticação da sessão ou a API Key do projeto, além do contexto da organização:

Authorization: Bearer <token>
x-organization-id: <organization-id>

Para automações, substitua o bearer por uma API Key da organização no mecanismo de autenticação aceito pelo seu perfil. O catálogo público não exige esses cabeçalhos.

O cabeçalho de organização seleciona o contexto de cobrança e autorização quando o usuário participa de mais de uma organização. A API Key deve permanecer em um secret manager, nunca em um arquivo versionado. Para leituras, trate 404 como projeto inacessível ou inexistente sem tentar adivinhar IDs. Para rotação, mostre a resposta somente ao operador autorizado, atualize o secret da aplicação e descarte a senha da memória assim que os clientes forem reiniciados.

As operações do projeto exigem as permissões correspondentes ao recurso managed_service:

Operação	Permissão
Consultar estado	`managed_service.status.read`
Consultar conexão mascarada	`managed_service.connection.read`
Rotacionar credencial	`managed_service.credentials.rotate`

Catálogo

GET /v1/managed-services/catalog

Não exige autenticação. O catálogo informa a versão do Valkey, moeda, perfis, planos, preços por hora/mês/ano, benefícios, armazenamento incluído e disponibilidade pública de alta disponibilidade.

{
  "status": "success",
  "data": {
    "engine": "valkey",
    "version": "9.1.1",
    "currency": "brl",
    "profiles": [
      { "id": "key_value", "persistence": true },
      { "id": "cache", "persistence": false },
      { "id": "queue", "persistence": true }
    ],
    "plans": [
      {
        "id": "queue-basic",
        "profile": "queue",
        "prices": { "hourly": 13, "monthly": 7490, "yearly": 74900 },
        "features": ["1 GB de memória", "1 vCPU", "Alta disponibilidade"],
        "included_storage_gb": 5,
        "high_availability": true
      }
    ]
  }
}

Os valores são centavos de BRL. Consulte o catálogo no momento da execução; não fixe preços em automações.

Consultar o estado

GET /v1/managed-services/:id/status

Resposta reduzida:

{
  "status": "success",
  "data": {
    "id": "<project-id>",
    "status": "running",
    "engine": "valkey",
    "profile": "queue",
    "version": "9.1.1",
    "persistence": true,
    "instances": 3
  }
}

Consultar a conexão

GET /v1/managed-services/:id/connection

A senha nunca é recuperada por esta rota:

{
  "status": "success",
  "data": {
    "host": "valkey-<project-id>.managed.zenifra.com",
    "port": 30000,
    "username": "default",
    "tls": true,
    "connection_string": "valkeys://default:********@valkey-<project-id>.managed.zenifra.com:30000/0"
  }
}

Rotacionar a credencial

PATCH /v1/managed-services/:id/credentials

A resposta contém a nova senha uma única vez. Atualize o secret da aplicação antes de descartar o valor anterior:

{
  "status": "success",
  "data": {
    "username": "default",
    "host": "valkey-<project-id>.managed.zenifra.com",
    "port": 30000,
    "tls": true,
    "connection_string": "valkeys://default:<nova-senha>@valkey-<project-id>.managed.zenifra.com:30000/0"
  }
}

Erros comuns

Código	Situação
`400`	ID ou parâmetros inválidos
`401`	Sessão ou API Key ausente/inválida
`403`	Permissão da organização insuficiente
`404`	Projeto gerenciado não encontrado
`502`	Falha ao rotacionar credencial
`503`	Catálogo comercial temporariamente indisponível