Emite órdenes de compra, aprueba y paga facturas, y configura tu espacio de trabajo.

Referencia de la API

Conexiones de nube

Vínculos de solo lectura a la facturación de tus cuentas de proveedores de nube.

Más sobre este recurso

Una conexión de nube da a Pleaxy acceso de solo lectura a la facturación de una cuenta de un proveedor de nube, mediante un acceso que creas en tu propia cuenta con un script de configuración. AWS usa un rol de IAM entre cuentas; Google Cloud, Workload Identity Federation, y Azure, una credencial federada, cada uno para sesiones de corta duración sin ninguna clave de larga duración guardada. Oracle Cloud usa una clave de firma de API que Pleaxy genera para la conexión; tú solo subes su clave pública. Conectar son dos llamadas: init devuelve los valores que necesita el script de configuración y luego CreateCloudConnection verifica el acceso y completa la conexión. Solo la persona que inició una configuración puede completarla o cancelarla.

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 conexiones de nube

Lista las conexiones de nube del espacio de trabajo.

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

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Lista las conexiones de nube del espacio de trabajo, incluidas las configuraciones aún en curso (status pending). Nunca devuelve secretos ni los identificadores que usó la configuración (ARN del rol, ID externo, cuenta de servicio, OCIDs, IDs de inquilino o de aplicación).

Campos de la respuesta

dataSourcesArray<"invoices" | "current_cost">
Lo que Pleaxy puede leer: facturas finalizadas y/o el costo del mes hasta la fecha. Si falta, ambos.
lastSyncStatus"ok" | "error" | "throttled" | "never"
Cómo fue la última sincronización de facturación. lastSyncErrorCode indica por qué falló una: throttled, access_revoked, platform_config, data_not_enabled o unknown.

Errores

401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.

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

Solicitud

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

Respuesta · 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 conexión de nube de AWS

Empieza a conectar una cuenta de AWS.

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

Devuelve

201 Created con el objeto que se muestra en la respuesta.

Más detalles

Empieza a conectar una cuenta de AWS y devuelve los valores que hay que dar al script de configuración (CloudFormation, CDK o CLI), que crea un rol de IAM de solo lectura en tu cuenta. Llamarlo de nuevo devuelve tu propia configuración sin terminar, con el mismo ID externo. No lleva cuerpo.

Campos de la respuesta

connectionIdstring
Pásalo a CreateCloudConnection como awsConnectionId.
cloudFormationTemplateUrlstring
Ausente cuando esta implementación no publica ninguna plantilla de CloudFormation; usa entonces el script de CDK o de CLI.

Errores

401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.

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

Solicitud

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

Respuesta · 201 Created

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

Iniciar conexión de nube

Empieza a conectar una cuenta de Google Cloud, Azure u Oracle Cloud.

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

Parámetros

provider"gcp" | "azure" | "oci"Obligatorio
El proveedor que se conecta.

Devuelve

201 Created con el objeto que se muestra en la respuesta.

Más detalles

Lo mismo que InitAwsCloudConnection para Google Cloud, Azure u Oracle Cloud: devuelve los valores por conexión que fija el script de configuración de ese proveedor, incluido un connectionId que hay que pasar a CreateCloudConnection (como gcpConnectionId, azureConnectionId u ociConnectionId). Llamarlo de nuevo devuelve tu propia configuración sin terminar. No lleva cuerpo.

Campos de la respuesta

gcpobject
connectionId, platformAwsAccountId, federationRoleArn, expectedSubject, poolId y providerId: los valores de Workload Identity Federation que fija el script de configuración.
azureobject
connectionId, issuer, subject, audience, appDisplayName y credentialName: la credencial federada que el script de configuración crea en tu aplicación.
ociobject
connectionId, publicKeyPem, fingerprint y regions: la clave pública que hay que subir al usuario pleaxy-billing y las regiones de origen entre las que elegir.

Errores

404 Not Found - El conector real de este proveedor no está activado en esta implementación ("Real connections to this provider aren't switched on.").
401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.

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

Solicitud

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

Respuesta · 201 Created

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

Descubrir ámbitos de facturación de Azure

Lista los perfiles de facturación de Azure que puedes conectar.

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

Cuerpo

azureConnectionIdstringObligatorio
connectionId de InitCloudConnection.
azureTenantIdstringObligatorio
El inquilino de Microsoft Entra en el que se registró la aplicación (GUID).
azureClientIdstringObligatorio
El ID de aplicación (cliente) del registro de aplicación (GUID).
azureBillingAccountIdstringObligatorio
El ID de la cuenta de facturación del Microsoft Customer Agreement (<guid>:<guid>_YYYY-MM-DD).
azureBillingProfileIdstringObligatorio
El ID del perfil de facturación sobre el que la aplicación tiene el rol Billing profile reader.

Devuelve

201 Created con el objeto que se muestra en la respuesta.

Más detalles

Solo Azure, entre init y CreateCloudConnection: comprueba el ID de inquilino y el ID de aplicación (cliente) que imprimió el script de configuración, y lee la cuenta de facturación y el perfil de facturación del Microsoft Customer Agreement que indicas, para que puedas elegir el perfil que conectar. Solo puede llamarlo la persona que inició la configuración, y cuenta para el mismo límite de intentos y el mismo tiempo de espera que CreateCloudConnection.

Errores

404 Not Found - El conector real de Azure no está activado, o la configuración ya no existe o la inició otra persona.
429 Too Many Requests - Se volvió a intentar demasiado pronto; retryAfterSeconds indica cuándo.
401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.

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

Solicitud

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

Respuesta · 201 Created

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

Crear conexión de nube

Termina de conectar una cuenta de nube.

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

Cuerpo

provider"aws" | "gcp" | "azure" | "oci"Obligatorio
El proveedor de nube que se conecta.
accountLabelstringObligatorio
Tu etiqueta para esta cuenta, p. ej. "Pagadora de producción".
dataSourcesArray<"invoices" | "current_cost">
Lo que Pleaxy puede leer: facturas finalizadas y/o el costo del mes hasta la fecha. Si se omite, ambos. Pleaxy nunca llama al proveedor para una fuente que dejes fuera, ni siquiera en una sincronización manual. Algunos proveedores cobran por solicitud el costo actual (AWS Cost Explorer).
supplierContactEmailstring
Contacto opcional en el proveedor para la entrada de proveedor que esto crea.
awsConnectionIdstring
AWS, obligatorio: connectionId de InitAwsCloudConnection.
roleArnstring
AWS, obligatorio: el rol de IAM que creó el script de configuración, arn:aws:iam::<cuenta de 12 dígitos>:role/<nombre>.
gcpConnectionIdstring
Google Cloud: connectionId de InitCloudConnection.
gcpProjectNumberstring
Google Cloud: el número del proyecto de exportación de facturación (dígitos).
gcpServiceAccountEmailstring
Google Cloud: la cuenta de servicio que creó el script de configuración en ese proyecto.
gcpExportTablestring
Google Cloud: la tabla estándar de exportación de costos de uso, project.dataset.gcp_billing_export_v1_XXXXXX_XXXXXX_XXXXXX.
azureConnectionIdstring
Azure: connectionId de InitCloudConnection.
azureBillingAccountIdstring
Azure: la cuenta de facturación del perfil elegido con DiscoverAzureBillingScopes.
azureBillingProfileIdstring
Azure: el perfil de facturación elegido con DiscoverAzureBillingScopes.
ociConnectionIdstring
Oracle Cloud: connectionId de InitCloudConnection.
ociTenancyOcidstring
Oracle Cloud: el OCID del tenancy (ocid1.tenancy.oc1..…).
ociUserOcidstring
Oracle Cloud: el OCID del usuario pleaxy-billing que creó el script de configuración.
ociHomeRegionstring
Oracle Cloud: la región de origen del tenancy, una de las que lista InitCloudConnection.
detailstring
Solo para una conexión de demostración, en la que el conector real de un proveedor está desactivado: un identificador de cuenta que escribes tú. Una conexión real lo lee del proveedor.

Devuelve

201 Created con el objeto que se muestra en la respuesta.

Más detalles

Completa una configuración iniciada con init: Pleaxy comprueba que puede leer tu facturación con el acceso que creó el script de configuración, luego marca la conexión como conectada y agrega el proveedor a tus proveedores. Envía los campos de tu proveedor. Solo puede completarla la persona que inició la configuración. Depende del plan de la región: el plan Free permite un proveedor conectado.

Errores

400 Bad Request - La validación falló; Pleaxy no pudo leer la facturación con el acceso dado (el código indica qué proveedor, p. ej. CLOUD_VERIFY_FAILED); demasiados intentos fallidos para esta configuración, así que empieza de nuevo con init (código que termina en ATTEMPTS_EXHAUSTED); o el plan de la región alcanzó su límite de proveedores conectados (Free: 1).
404 Not Found - La configuración ya no existe, caducó o la inició otra persona.
409 Conflict - Esta configuración, o la misma cuenta o ámbito de facturación, ya está conectada.
429 Too Many Requests - Se volvió a intentar demasiado pronto tras un intento fallido; retryAfterSeconds indica cuándo.
401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.

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

Solicitud

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" ]
}

Respuesta · 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 conexión de nube

Sincroniza ahora los datos de facturación de una cuenta de nube.

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

Parámetros

idstringObligatorio
El id de la conexión de nube.

Devuelve

201 Created con el objeto que se muestra en la respuesta.

Más detalles

Sincroniza ahora los datos de facturación de una cuenta conectada, leyendo solo los dataSources de la conexión. Una vez cada 15 minutos por conexión. No lleva cuerpo.

Errores

400 Bad Request - Se sincronizó hace menos de 15 minutos ("…try again in {n}m."), o la conexión no es una cuenta conectada con un conector de facturación real.
404 Not Found - No existe esa conexión en el espacio de trabajo, o se desconectó.
401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.

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

Solicitud

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

Respuesta · 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 conexión de nube

Desconecta una cuenta de nube.

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

Parámetros

idstringObligatorio
El id de la conexión de nube.

Devuelve

200 OK con el objeto que se muestra en la respuesta.

Más detalles

Desconecta una cuenta de nube o cancela una configuración en curso. Elimina la conexión con todo lo que Pleaxy guardó para ella (en Oracle Cloud, su clave de API cifrada) y registra quién la desconectó. En Oracle Cloud, la respuesta indica la huella de la clave que hay que eliminar del usuario pleaxy-billing. Elimina también el acceso en tu propia cuenta.

Sesión iniciada con acceso 'edit' a los proveedores; una clave de API recibe 403. Una configuración en curso solo puede cancelarla la persona que la inició.

Errores

403 Forbidden - El llamador es una clave de API, no tiene 'edit' en los proveedores o está cancelando la configuración de otra persona ("Only the person who started this setup can cancel it.").
404 Not Found - No existe esa conexión en el espacio de trabajo.
401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.

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

Solicitud

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

Respuesta · 200 OK

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

Agregar proveedor de nube como proveedor

Agrega un proveedor de nube como proveedor sin conectar una cuenta.

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

Parámetros

provider"aws" | "gcp" | "azure" | "oci"Obligatorio
El proveedor que se agrega.

Devuelve

201 Created con el objeto que se muestra en la respuesta.

Más detalles

Agrega un proveedor de nube a tu lista de proveedores sin conectar una cuenta, para que puedas emitirle órdenes de compra. No se lee nada del proveedor. Devuelve la entrada de proveedor existente si la hay, y conectar más adelante vincula con la misma entrada. Necesita acceso 'create' a los proveedores. No lleva cuerpo.

Errores

404 Not Found - Proveedor desconocido.
409 Conflict - Código SUPPLIER_ALREADY_LISTED: un proveedor con ese nombre ya tiene una incorporación en curso o aprobada.
401 Unauthorized - No se presentó ninguna credencial, o el token Bearer o el valor de X-Api-Key falta, no es válido, caducó o fue revocado.
403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.

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

Solicitud

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

Respuesta · 201 Created

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