Emita pedidos de compra, aprove e pague faturas, e configure seu espaço de trabalho.

Referência da API

Conexões de nuvem

Vínculos somente leitura com o faturamento das suas contas em provedores de nuvem.

Mais sobre este recurso

Uma conexão de nuvem dá à Pleaxy acesso somente leitura ao faturamento de uma conta de um provedor de nuvem, por meio de um acesso que você cria na sua própria conta com um script de configuração. A AWS usa uma função IAM entre contas, o Google Cloud, a Workload Identity Federation, e a Azure, uma credencial federada, cada um para sessões de curta duração, sem nenhuma chave de longa duração armazenada. A Oracle Cloud usa uma chave de assinatura de API que a Pleaxy gera para a conexão; você envia só a chave pública dela. Conectar exige duas chamadas: init retorna os valores de que o script de configuração precisa, e então CreateCloudConnection verifica o acesso e conclui a conexão. Só a pessoa que iniciou uma configuração pode concluí-la ou cancelá-la.

Endpoints

GET…/cloud-connections
POST…/cloud-connections/aws/init
POST…/cloud-connections/{provider}/init
POST…/cloud-connections/azure/discover
POST…/cloud-connections
POST…/cloud-connections/{id}/sync
DELETE…/cloud-connections/{id}
POST…/cloud-connections/{provider}/supplier

Listar conexões de nuvem

Lista as conexões de nuvem do espaço de trabalho.

GET/v1/workspaces/{regionId}/cloud-connections

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Lista as conexões de nuvem do espaço de trabalho, inclusive configurações ainda em andamento (status pending). Nunca retorna segredos nem os identificadores que a configuração usou (ARN da função, ID externo, conta de serviço, OCIDs, IDs de tenant ou de aplicativo).

Campos da resposta

dataSourcesArray<"invoices" | "current_cost">
O que a Pleaxy pode ler: faturas finalizadas e/ou custo do mês até a data. Ausente significa ambos.
lastSyncStatus"ok" | "error" | "throttled" | "never"
Como foi a última sincronização de faturamento. lastSyncErrorCode diz por que uma falhou: throttled, access_revoked, platform_config, data_not_enabled ou unknown.

Erros

401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

GET /v1/workspaces/{regionId}/cloud-connections

Requisição

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

[
   {
      "id": "string",
      "provider": "aws" | "gcp" | "azure" | "oci",
      "accountLabel": "string",
      "detail": "string",
      "spend": number,
      "status": "connected" | "pending" | "error",
      "connectedAt": "string",
      "awsAccountId": "string",
      "dataSources": [ "invoices" | "current_cost" ],
      "gcp": { "billingAccountId": "string", "providerId": "string" },
      "oci": { "homeRegion": "string", "keyFingerprint": "string" },
      "azure": { "scopeDisplayName": "string", "agreementType": "string" },
      "lastSyncedAt": "string",
      "lastSyncStatus": "ok" | "error" | "throttled" | "never",
      "lastSyncError": "string",
      "lastSyncErrorCode": "throttled" | "access_revoked" | "platform_config" | "data_not_enabled" | "unknown"
   }
]

Iniciar conexão de nuvem AWS

Começa a conectar uma conta AWS.

POST/v1/workspaces/{regionId}/cloud-connections/aws/init

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Começa a conectar uma conta AWS e retorna os valores a passar para o script de configuração (CloudFormation, CDK ou CLI), que cria uma função IAM somente leitura na sua conta. Chamar de novo retorna a sua própria configuração inacabada, com o mesmo ID externo. Não recebe corpo.

Campos da resposta

connectionIdstring
Passe-o para CreateCloudConnection como awsConnectionId.
cloudFormationTemplateUrlstring
Ausente quando esta implantação não publica nenhum template do CloudFormation; nesse caso, use o script de CDK ou de CLI.

Erros

401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/cloud-connections/aws/init

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/aws/init" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 201 Created

{
   "connectionId": "string",
   "platformAwsAccountId": "string",
   "externalId": "string",
   "cloudFormationTemplateUrl": "string"
}

Iniciar conexão de nuvem

Começa a conectar uma conta do Google Cloud, da Azure ou da Oracle Cloud.

POST/v1/workspaces/{regionId}/cloud-connections/{provider}/init

Parâmetros

provider"gcp" | "azure" | "oci"Obrigatório
O provedor a conectar.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

O mesmo que InitAwsCloudConnection para Google Cloud, Azure ou Oracle Cloud: retorna os valores por conexão que o script de configuração desse provedor fixa, incluindo um connectionId a passar para CreateCloudConnection (como gcpConnectionId, azureConnectionId ou ociConnectionId). Chamar de novo retorna a sua própria configuração inacabada. Não recebe corpo.

Campos da resposta

gcpobject
connectionId, platformAwsAccountId, federationRoleArn, expectedSubject, poolId e providerId: os valores da Workload Identity Federation que o script de configuração fixa.
azureobject
connectionId, issuer, subject, audience, appDisplayName e credentialName: a credencial federada que o script de configuração cria no seu aplicativo.
ociobject
connectionId, publicKeyPem, fingerprint e regions: a chave pública a enviar para o usuário pleaxy-billing e as regiões de origem entre as quais escolher.

Erros

404 Not Found - O conector real deste provedor não está ativado nesta implantação ("Real connections to this provider aren't switched on.").
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/cloud-connections/{provider}/init

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{provider}/init" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 201 Created

{
   "connectionId": "string",
   ...the provider's setup values
}

Descobrir escopos de faturamento da Azure

Lista os perfis de faturamento da Azure que você pode conectar.

POST/v1/workspaces/{regionId}/cloud-connections/azure/discover

Corpo

azureConnectionIdstringObrigatório
connectionId de InitCloudConnection.
azureTenantIdstringObrigatório
O tenant do Microsoft Entra em que o aplicativo foi registrado (GUID).
azureClientIdstringObrigatório
O ID do aplicativo (cliente) do registro de aplicativo (GUID).
azureBillingAccountIdstringObrigatório
O ID da conta de faturamento do Contrato de Cliente da Microsoft (<guid>:<guid>_YYYY-MM-DD).
azureBillingProfileIdstringObrigatório
O ID do perfil de faturamento em que o aplicativo tem a função Billing profile reader.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Só Azure, entre init e CreateCloudConnection: comprova o ID do tenant e o ID do aplicativo (cliente) que o script de configuração exibiu, e lê a conta de faturamento e o perfil de faturamento do Contrato de Cliente da Microsoft que você indicar, para você escolher o perfil a conectar. Só a pessoa que iniciou a configuração pode chamá-lo, e ele conta para o mesmo limite de tentativas e o mesmo tempo de espera que CreateCloudConnection.

Erros

404 Not Found - O conector real da Azure não está ativado, ou a configuração não existe mais ou foi iniciada por outra pessoa.
429 Too Many Requests - Nova tentativa cedo demais; retryAfterSeconds diz quando.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/cloud-connections/azure/discover

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/azure/discover" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 201 Created

{
   "scopes": [
      { "billingAccountId": "string", "billingProfileId": "string", "displayName": "string", "billingAccountDisplayName": "string", "agreementType": "string" }
   ]
}

Criar conexão de nuvem

Conclui a conexão de uma conta de nuvem.

POST/v1/workspaces/{regionId}/cloud-connections

Corpo

provider"aws" | "gcp" | "azure" | "oci"Obrigatório
O provedor de nuvem a conectar.
accountLabelstringObrigatório
O seu rótulo para esta conta, por exemplo "Production payer".
dataSourcesArray<"invoices" | "current_cost">
O que a Pleaxy pode ler: faturas finalizadas e/ou custo do mês até a data. Se omitido: ambos. A Pleaxy nunca chama o provedor para uma fonte que você deixa de fora, nem em uma sincronização manual. Alguns provedores cobram por requisição pelo custo atual (AWS Cost Explorer).
supplierContactEmailstring
Contato opcional no provedor para o cadastro de fornecedor que esta chamada cria.
awsConnectionIdstring
AWS, obrigatório: connectionId de InitAwsCloudConnection.
roleArnstring
AWS, obrigatório: a função IAM que o script de configuração criou, arn:aws:iam::<conta de 12 dígitos>:role/<name>.
gcpConnectionIdstring
Google Cloud: connectionId de InitCloudConnection.
gcpProjectNumberstring
Google Cloud: o número do projeto da exportação de faturamento (dígitos).
gcpServiceAccountEmailstring
Google Cloud: a conta de serviço que o script de configuração criou nesse projeto.
gcpExportTablestring
Google Cloud: a tabela padrão de exportação de custo de uso, project.dataset.gcp_billing_export_v1_XXXXXX_XXXXXX_XXXXXX.
azureConnectionIdstring
Azure: connectionId de InitCloudConnection.
azureBillingAccountIdstring
Azure: a conta de faturamento do perfil escolhido com DiscoverAzureBillingScopes.
azureBillingProfileIdstring
Azure: o perfil de faturamento escolhido com DiscoverAzureBillingScopes.
ociConnectionIdstring
Oracle Cloud: connectionId de InitCloudConnection.
ociTenancyOcidstring
Oracle Cloud: o OCID da tenancy (ocid1.tenancy.oc1..…).
ociUserOcidstring
Oracle Cloud: o OCID do usuário pleaxy-billing que o script de configuração criou.
ociHomeRegionstring
Oracle Cloud: a região de origem da tenancy, uma das que InitCloudConnection lista.
detailstring
Só para uma conexão de demonstração, em que o conector real de um provedor está desativado: um identificador de conta que você digita. Uma conexão real o lê do provedor.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Conclui uma configuração iniciada com init: a Pleaxy verifica se consegue ler o seu faturamento com o acesso que o script de configuração criou, depois marca a conexão como conectada e adiciona o provedor aos seus fornecedores. Envie os campos do seu provedor. Só a pessoa que iniciou a configuração pode concluí-la. Limitado pelo plano da região: o plano Free permite um provedor conectado.

Erros

400 Bad Request - A validação falhou; a Pleaxy não conseguiu ler o faturamento com o acesso concedido (o código diz qual provedor, por exemplo CLOUD_VERIFY_FAILED); houve tentativas falhas demais para esta configuração, então comece de novo com init (código terminado em ATTEMPTS_EXHAUSTED); ou o plano da região atingiu o limite de provedores conectados (Free: 1).
404 Not Found - A configuração não existe mais, expirou ou foi iniciada por outra pessoa.
409 Conflict - Esta configuração, ou a mesma conta ou escopo de faturamento, já está conectada.
429 Too Many Requests - Nova tentativa cedo demais depois de uma tentativa falha; retryAfterSeconds diz quando.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/cloud-connections

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "provider": "aws",
   "accountLabel": "string",
   "awsConnectionId": "string",
   "roleArn": "string",
   "dataSources": [ "invoices", "current_cost" ]
}

Resposta · 201 Created

{
   "id": "string",
   "provider": "aws" | "gcp" | "azure" | "oci",
   "accountLabel": "string",
   "detail": "string",
   "spend": number,
   "status": "connected" | "pending" | "error",
   "connectedAt": "string",
   "awsAccountId": "string",
   "dataSources": [ "invoices" | "current_cost" ],
   "gcp": { "billingAccountId": "string", "providerId": "string" },
   "oci": { "homeRegion": "string", "keyFingerprint": "string" },
   "azure": { "scopeDisplayName": "string", "agreementType": "string" },
   "lastSyncedAt": "string",
   "lastSyncStatus": "ok" | "error" | "throttled" | "never",
   "lastSyncError": "string",
   "lastSyncErrorCode": "throttled" | "access_revoked" | "platform_config" | "data_not_enabled" | "unknown"
}

Sincronizar conexão de nuvem

Sincroniza agora os dados de faturamento de uma conta de nuvem.

POST/v1/workspaces/{regionId}/cloud-connections/{id}/sync

Parâmetros

idstringObrigatório
O id da conexão de nuvem.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Sincroniza agora os dados de faturamento de uma conta conectada, lendo só os dataSources da conexão. Uma vez a cada 15 minutos por conexão. Não recebe corpo.

Erros

400 Bad Request - Sincronizado há menos de 15 minutos ("…try again in {n}m."), ou a conexão não é uma conta conectada com um conector de faturamento real.
404 Not Found - Essa conexão não existe no espaço de trabalho, ou foi desconectada.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/cloud-connections/{id}/sync

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{id}/sync" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 201 Created

{
   "id": "string",
   "provider": "aws" | "gcp" | "azure" | "oci",
   "accountLabel": "string",
   "detail": "string",
   "spend": number,
   "status": "connected" | "pending" | "error",
   "connectedAt": "string",
   "awsAccountId": "string",
   "dataSources": [ "invoices" | "current_cost" ],
   "gcp": { "billingAccountId": "string", "providerId": "string" },
   "oci": { "homeRegion": "string", "keyFingerprint": "string" },
   "azure": { "scopeDisplayName": "string", "agreementType": "string" },
   "lastSyncedAt": "string",
   "lastSyncStatus": "ok" | "error" | "throttled" | "never",
   "lastSyncError": "string",
   "lastSyncErrorCode": "throttled" | "access_revoked" | "platform_config" | "data_not_enabled" | "unknown"
}

Desconectar conexão de nuvem

Desconecta uma conta de nuvem.

DELETE/v1/workspaces/{regionId}/cloud-connections/{id}

Parâmetros

idstringObrigatório
O id da conexão de nuvem.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Desconecta uma conta de nuvem ou cancela uma configuração em andamento. Exclui a conexão com tudo o que a Pleaxy armazenou para ela (para a Oracle Cloud, a chave de API criptografada) e registra quem a desconectou. Para a Oracle Cloud, a resposta indica a impressão digital da chave a excluir do usuário pleaxy-billing. Remova também o acesso na sua própria conta.

Sessão conectada com acesso 'edit' a fornecedores; uma chave de API recebe 403. Uma configuração em andamento só pode ser cancelada pela pessoa que a iniciou.

Erros

403 Forbidden - Quem chama é uma chave de API, não tem 'edit' em fornecedores, ou está cancelando a configuração de outra pessoa ("Only the person who started this setup can cancel it.").
404 Not Found - Essa conexão não existe no espaço de trabalho.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.

DELETE /v1/workspaces/{regionId}/cloud-connections/{id}

Requisição

curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{id}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

{
   "id": "string",
   "provider": "aws" | "gcp" | "azure" | "oci",
   "ociKeyFingerprint": "string"
}

Adicionar provedor de nuvem como fornecedor

Adiciona um provedor de nuvem como fornecedor sem conectar uma conta.

POST/v1/workspaces/{regionId}/cloud-connections/{provider}/supplier

Parâmetros

provider"aws" | "gcp" | "azure" | "oci"Obrigatório
O provedor a adicionar.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Adiciona um provedor de nuvem à sua lista de fornecedores sem conectar uma conta, para você poder emitir pedidos de compra para ele. Nada é lido do provedor. Retorna o cadastro de fornecedor existente do provedor, se houver um, e conectar depois vincula ao mesmo cadastro. Exige acesso 'create' a fornecedores. Não recebe corpo.

Erros

404 Not Found - Provedor desconhecido.
409 Conflict - Código SUPPLIER_ALREADY_LISTED: um fornecedor com esse nome já tem uma integração em andamento ou aprovada.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/cloud-connections/{provider}/supplier

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/cloud-connections/{provider}/supplier" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 201 Created

{
   "id": "string",
   "buyerOrgId": "string",
   "supplierName": "string",
   "cloudProvider": "aws" | "gcp" | "azure" | "oci",
   "status": "pending_invite" | "invited" | "in_progress" | "submitted" | "approved" | "rejected",
   "createdAt": "string"
}