Referencia de la API

FOCUS

Exporta tus facturas como un conjunto de datos FOCUS y lee los datos de facturación FOCUS de tus proveedores.

Más sobre este recurso

FOCUS es el formato abierto de la FinOps Foundation para datos de facturación. Pleaxy trabaja con él en ambos sentidos. Una exportación escribe las facturas, notas de débito y notas de crédito aceptadas del espacio de trabajo como un conjunto de datos FOCUS Cost and Usage, para una herramienta de FinOps o de informes. Un origen FOCUS lee datos de facturación en ese formato, de archivos que cargas o de la exportación FOCUS del propio proveedor, y guarda los totales de cada mes por factura, emisor y centro de costo. La exportación y la importación se activan por espacio de trabajo; mientras una está desactivada, sus endpoints responden 404.

Listar exportaciones FOCUS

Lista las exportaciones FOCUS de los últimos 7 días y si la exportación está activada.

GET/v1/workspaces/{regionId}/focus-exports

Devuelve

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

Más detalles

Devuelve si la exportación FOCUS está activada para el espacio de trabajo y sus exportaciones de los últimos 7 días, de la más reciente a la más antigua, 20 como máximo. La lista no trae enlaces de descarga; obtenlos con GetFocusExport.

Necesita acceso 'view' a las facturas. Una clave de API puede llamarlo.

Campos de la respuesta

  • enabledboolean

    Si la exportación FOCUS está activada para el espacio de trabajo.

  • from, tostring

    El primer y el último periodo de facturación de la exportación, como YYYY-MM.

  • rowCount, documentCountnumber

    Las filas del conjunto de datos y las facturas, notas de débito y notas de crédito de las que provienen.

  • expiresAtstring

    Cuándo elimina Pleaxy los archivos de la exportación, 7 días después de crearla.

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}/focus-exports
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-exports" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "enabled": boolean,
   "exports": [
      {
         "id": "string",
         "status": "ready",
         "createdAt": "string",
         "version": "1.2" | "1.4",
         "include": "all" | "non_cloud",
         "from": "string",
         "to": "string",
         "format": "csv" | "parquet",
         "rowCount": number,
         "documentCount": number,
         "commitmentCount": number,
         "expiresAt": "string"
      }
   ]
}

Crear exportación FOCUS

Exporta las facturas de un rango de meses como un conjunto de datos FOCUS.

POST/v1/workspaces/{regionId}/focus-exports

Cuerpo

  • fromstringObligatorio

    El primer periodo de facturación, como YYYY-MM.

  • tostringObligatorio

    El último periodo de facturación, como YYYY-MM, incluido. El rango abarca 36 meses como máximo.

  • version"1.2" | "1.4"

    La versión de FOCUS. 1.2 si no aparece. Una exportación 1.4 también puede llevar un conjunto de datos Contract Commitment.

  • include"all" | "non_cloud"

    non_cloud deja fuera las facturas de los proveedores de nube e IA, que una herramienta de FinOps puede leer de las exportaciones FOCUS de los propios proveedores. all si no aparece.

  • format"csv" | "parquet"

    El formato del archivo. csv si no aparece.

Devuelve

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

Más detalles

Escribe las facturas, notas de débito y notas de crédito aceptadas del espacio de trabajo para los periodos de facturación from..to como un conjunto de datos FOCUS Cost and Usage con un archivo de metadatos. Hay una fila por línea, entrada de impuesto y ajuste; las notas de crédito van en negativo; los importes se mantienen en la moneda de cada documento. La respuesta trae enlaces de descarga válidos durante 15 minutos, y los archivos se conservan 7 días. Una exportación no cambia nada en el espacio de trabajo.

Necesita acceso 'view' a las facturas. Una clave de API puede llamarlo.

Campos de la respuesta

  • from, tostring

    El primer y el último periodo de facturación de la exportación, como YYYY-MM.

  • rowCount, documentCountnumber

    Las filas del conjunto de datos y las facturas, notas de débito y notas de crédito de las que provienen.

  • expiresAtstring

    Cuándo elimina Pleaxy los archivos de la exportación, 7 días después de crearla.

  • downloadUrl, metadataUrlstring

    Enlaces al conjunto de datos y a su archivo de metadatos, válidos durante 15 minutos. Llama a GetFocusExport para obtener enlaces nuevos.

  • commitmentsUrlstring

    Un enlace al conjunto de datos Contract Commitment, presente solo cuando la exportación tiene uno.

Errores

  • 400 Bad Request - from o to no es un mes escrito como YYYY-MM, from es posterior a to, o el rango abarca más de 36 meses.
  • 404 Not Found - La exportación FOCUS no está activada para este espacio de trabajo ("FOCUS export isn't switched on for this workspace yet.").
  • 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}/focus-exports
Solicitud
POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/focus-exports
{
   "from": "2026-07",
   "to": "2026-09",
   "include": "non_cloud"
}
Respuesta · 201 Created
{
   "id": "FE-mhu8x2k04f9a1c",
   "status": "ready",
   "createdAt": "2026-11-11T15:04:05.000Z",
   "version": "1.2",
   "include": "non_cloud",
   "from": "2026-07",
   "to": "2026-09",
   "format": "csv",
   "rowCount": 412,
   "documentCount": 57,
   "expiresAt": "2026-11-18T15:04:05.000Z",
   "downloadUrl": "https://...",
   "metadataUrl": "https://..."
}

Obtener exportación FOCUS

Obtiene una exportación FOCUS con enlaces de descarga nuevos.

GET/v1/workspaces/{regionId}/focus-exports/{exportId}

Parámetros

  • exportIdstringObligatorio

    El id de la exportación, tal como lo devuelve CreateFocusExport.

Devuelve

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

Más detalles

Devuelve una exportación de los últimos 7 días con enlaces nuevos a su conjunto de datos y a su archivo de metadatos, válidos durante 15 minutos.

Necesita acceso 'view' a las facturas. Una clave de API puede llamarlo.

Campos de la respuesta

  • from, tostring

    El primer y el último periodo de facturación de la exportación, como YYYY-MM.

  • rowCount, documentCountnumber

    Las filas del conjunto de datos y las facturas, notas de débito y notas de crédito de las que provienen.

  • expiresAtstring

    Cuándo elimina Pleaxy los archivos de la exportación, 7 días después de crearla.

  • downloadUrl, metadataUrlstring

    Enlaces al conjunto de datos y a su archivo de metadatos, válidos durante 15 minutos. Llama a GetFocusExport para obtener enlaces nuevos.

  • commitmentsUrlstring

    Un enlace al conjunto de datos Contract Commitment, presente solo cuando la exportación tiene uno.

Errores

  • 404 Not Found - Ninguna exportación de este espacio de trabajo tiene este id, ha caducado (las exportaciones se conservan 7 días) o la exportación FOCUS no está activada para este 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.
  • 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}/focus-exports/{exportId}
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-exports/{exportId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "id": "string",
   "status": "ready",
   "createdAt": "string",
   "version": "1.2" | "1.4",
   "include": "all" | "non_cloud",
   "from": "string",
   "to": "string",
   "format": "csv" | "parquet",
   "rowCount": number,
   "documentCount": number,
   "commitmentCount": number,
   "expiresAt": "string",
   "downloadUrl": "string",
   "metadataUrl": "string",
   "commitmentsUrl": "string"
}

Listar orígenes FOCUS

Lista los orígenes FOCUS del espacio de trabajo con su última ejecución y si la importación está activada.

GET/v1/workspaces/{regionId}/focus-sources

Devuelve

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

Más detalles

Devuelve si la importación FOCUS está activada y los orígenes FOCUS del espacio de trabajo, cada uno con su última ejecución, los meses que tiene guardados y sus claves de etiqueta más frecuentes.

Necesita acceso 'view' a las facturas.

Campos de la respuesta

  • enabledboolean

    Si la importación FOCUS está activada para el espacio de trabajo.

  • kindstring

    upload: archivos que cargas. aws_s3: una exportación FOCUS de AWS Data Exports. azure_blob: una exportación FOCUS de Azure Cost Management. gcp_bigquery: la tabla FOCUS de Google Cloud. oci: los informes FOCUS de Oracle Cloud. s3_compatible: un bucket en cualquier almacenamiento compatible con S3.

  • periodsArray<string>

    Los meses de los que el origen tiene cifras guardadas, como YYYY-MM.

  • lastRunobject

    La última lectura: los meses, archivos y filas leídos, las filas omitidas por motivo, y failure.reason cuando status es failed.

  • tagKeysArray<string>

    Las claves de etiqueta más frecuentes en las filas del origen.

  • s3.keyHintstring

    Una pista breve de qué clave de acceso secreta está guardada. El secreto en sí nunca se devuelve.

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}/focus-sources
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "enabled": boolean,
   "sources": [
      {
         "id": "string",
         "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
         "label": "string",
         "provider": "aws" | "azure" | "gcp" | "oci",
         "connectionId": "string",
         "aws": { "bucket": "string", "prefix": "string", "region": "string" },
         "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
         "gcp": { "table": "string" },
         "oci": { "region": "string" },
         "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
         "periods": [ "string" ],
         "lastRun": {
            "runId": "string",
            "startedAt": "string",
            "finishedAt": "string",
            "status": "ok" | "partial" | "failed",
            "trigger": "schedule" | "manual" | "upload",
            "periods": [ "string" ],
            "files": number,
            "rows": number,
            "skipped": number,
            "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
            "ignoredFiles": number,
            "version": "string",
            "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
         },
         "tagKeys": [ "string" ],
         "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
         "createdAt": "string",
         "updatedAt": "string"
      }
   ]
}

Crear origen FOCUS

Agrega la exportación FOCUS de un proveedor como origen que Pleaxy lee cada día.

POST/v1/workspaces/{regionId}/focus-sources

Cuerpo

  • kind"aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible"Obligatorio

    Dónde están los datos FOCUS. Envía junto a él el objeto del mismo proveedor.

  • labelstring

    Opcional. Un nombre para el origen.

  • connectionIdstring

    La conexión de nube a la que pertenece el origen, tal como la devuelve ListCloudConnections. Obligatoria para todos los tipos salvo s3_compatible.

  • awsobject

    Para aws_s3: el bucket en el que escribe AWS Data Exports, el prefijo de la exportación (su prefijo de S3 y el nombre de la exportación) y la región del bucket.

  • azureobject

    Para azure_blob: la cuenta de almacenamiento, el contenedor y el directorio de la exportación.

  • gcpobject

    Para gcp_bigquery: la tabla o vista FOCUS, como project.dataset.table.

  • ociobject

    Para oci: la región principal de la tenencia.

  • s3object

    Para s3_compatible: el endpoint HTTPS, la región, el bucket y el prefijo del almacenamiento, y una clave de acceso que pueda leerlo. El secreto se guarda cifrado y nunca se devuelve.

Devuelve

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

Más detalles

Agrega un origen FOCUS. El origen de una nube (aws_s3, azure_blob, gcp_bigquery u oci) pertenece a una de las conexiones de nube del espacio de trabajo del mismo proveedor; pasa entonces a ser el origen de las líneas de IA de esa conexión, en lugar de la lectura de IA propia del conector. Un origen s3_compatible trae su propia clave de acceso. Pleaxy lee un origen a diario, y de inmediato con SyncFocusSource. Una conexión tiene como máximo un origen FOCUS.

Solo sesión iniciada, con acceso 'edit' a las facturas: un origen abre una vía de lectura hacia tu cuenta de nube, así que lo agrega y lo quita una persona.

Campos de la respuesta

  • kindstring

    upload: archivos que cargas. aws_s3: una exportación FOCUS de AWS Data Exports. azure_blob: una exportación FOCUS de Azure Cost Management. gcp_bigquery: la tabla FOCUS de Google Cloud. oci: los informes FOCUS de Oracle Cloud. s3_compatible: un bucket en cualquier almacenamiento compatible con S3.

  • periodsArray<string>

    Los meses de los que el origen tiene cifras guardadas, como YYYY-MM.

  • lastRunobject

    La última lectura: los meses, archivos y filas leídos, las filas omitidas por motivo, y failure.reason cuando status es failed.

  • tagKeysArray<string>

    Las claves de etiqueta más frecuentes en las filas del origen.

  • s3.keyHintstring

    Una pista breve de qué clave de acceso secreta está guardada. El secreto en sí nunca se devuelve.

Errores

  • 400 Bad Request - Falta un campo o no es válido, la conexión es de otra nube que kind, o la conexión ya tiene un origen FOCUS.
  • 403 Forbidden - El llamador no es una persona con sesión iniciada (por ejemplo, una clave de API), o no tiene acceso 'edit' a las facturas.
  • 404 Not Found - Ninguna conexión de nube de este espacio de trabajo tiene este connectionId, o la importación FOCUS no está activada para este 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.
POST /v1/workspaces/{regionId}/focus-sources
Solicitud
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "kind": "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "secretAccessKey": "string" }
}
Respuesta · 201 Created
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

Obtener origen FOCUS

Obtiene un origen FOCUS con su última ejecución.

GET/v1/workspaces/{regionId}/focus-sources/{sourceId}

Parámetros

  • sourceIdstringObligatorio

    El id del origen FOCUS, tal como lo devuelve ListFocusSources.

Devuelve

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

Más detalles

Devuelve un origen FOCUS con su última ejecución. Consúltalo tras SyncFocusSource o CompleteFocusUpload para saber cuándo terminó la lectura.

Necesita acceso 'view' a las facturas.

Campos de la respuesta

  • kindstring

    upload: archivos que cargas. aws_s3: una exportación FOCUS de AWS Data Exports. azure_blob: una exportación FOCUS de Azure Cost Management. gcp_bigquery: la tabla FOCUS de Google Cloud. oci: los informes FOCUS de Oracle Cloud. s3_compatible: un bucket en cualquier almacenamiento compatible con S3.

  • periodsArray<string>

    Los meses de los que el origen tiene cifras guardadas, como YYYY-MM.

  • lastRunobject

    La última lectura: los meses, archivos y filas leídos, las filas omitidas por motivo, y failure.reason cuando status es failed.

  • tagKeysArray<string>

    Las claves de etiqueta más frecuentes en las filas del origen.

  • s3.keyHintstring

    Una pista breve de qué clave de acceso secreta está guardada. El secreto en sí nunca se devuelve.

Errores

  • 404 Not Found - Ningún origen FOCUS de este espacio de trabajo tiene este id, o la importación FOCUS no está activada para este 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.
  • 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}/focus-sources/{sourceId}
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

Sincronizar origen FOCUS

Lee un origen FOCUS ahora, en segundo plano.

POST/v1/workspaces/{regionId}/focus-sources/{sourceId}/sync

Parámetros

  • sourceIdstringObligatorio

    El id del origen FOCUS, tal como lo devuelve ListFocusSources.

Devuelve

202 Accepted con el objeto que se muestra en la respuesta.

Más detalles

Inicia una lectura del origen en segundo plano, que vuelve a leer los meses que contiene, y devuelve el origen. Su lastRun muestra el resultado cuando la lectura ha terminado.

Necesita acceso 'edit' a las facturas. Una clave de API puede llamarlo.

Campos de la respuesta

  • kindstring

    upload: archivos que cargas. aws_s3: una exportación FOCUS de AWS Data Exports. azure_blob: una exportación FOCUS de Azure Cost Management. gcp_bigquery: la tabla FOCUS de Google Cloud. oci: los informes FOCUS de Oracle Cloud. s3_compatible: un bucket en cualquier almacenamiento compatible con S3.

  • periodsArray<string>

    Los meses de los que el origen tiene cifras guardadas, como YYYY-MM.

  • lastRunobject

    La última lectura: los meses, archivos y filas leídos, las filas omitidas por motivo, y failure.reason cuando status es failed.

  • tagKeysArray<string>

    Las claves de etiqueta más frecuentes en las filas del origen.

  • s3.keyHintstring

    Una pista breve de qué clave de acceso secreta está guardada. El secreto en sí nunca se devuelve.

Errores

  • 400 Bad Request - El origen es el origen de cargas, que se lee cuando llega un archivo: vuelve a cargar el archivo para leerlo de nuevo.
  • 404 Not Found - Ningún origen FOCUS de este espacio de trabajo tiene este id, o la importación FOCUS no está activada para este espacio de trabajo.
  • 503 Service Unavailable - La lectura no se puede iniciar ahora mismo. Inténtalo de nuevo en unos minutos.
  • 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}/focus-sources/{sourceId}/sync
Solicitud
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}/sync" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 202 Accepted
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

Eliminar origen FOCUS

Quita un origen FOCUS con los meses que guardó.

DELETE/v1/workspaces/{regionId}/focus-sources/{sourceId}

Parámetros

  • sourceIdstringObligatorio

    El id del origen FOCUS, tal como lo devuelve ListFocusSources.

Devuelve

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

Más detalles

Quita el origen con los meses y las líneas de IA que guardó. La lectura de IA propia del conector se reanuda para su conexión de nube.

Solo sesión iniciada, con acceso 'edit' a las facturas: un origen abre una vía de lectura hacia tu cuenta de nube, así que lo agrega y lo quita una persona.

Errores

  • 403 Forbidden - El llamador no es una persona con sesión iniciada (por ejemplo, una clave de API), o no tiene acceso 'edit' a las facturas.
  • 404 Not Found - Ningún origen FOCUS de este espacio de trabajo tiene este id, o la importación FOCUS no está activada para este 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}/focus-sources/{sourceId}
Solicitud
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "removed": true
}

Obtener periodo de origen FOCUS

Obtiene un mes guardado de un origen FOCUS, por factura, centro de costo y emisor.

GET/v1/workspaces/{regionId}/focus-sources/{sourceId}/periods/{period}

Parámetros

  • sourceIdstringObligatorio

    El id del origen FOCUS, tal como lo devuelve ListFocusSources.

  • periodstringObligatorio

    El mes, como YYYY-MM.

Devuelve

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

Más detalles

Devuelve un mes guardado de un origen: sus totales por moneda, cada factura por número con sus importes por categoría y servicio, el gasto por centro de costo y los totales por emisor.

Necesita acceso 'view' a las facturas.

Campos de la respuesta

  • totalsobject

    El total facturado del mes, por código de moneda.

  • invoicesArray<object>

    Cada factura que nombran las filas del mes, con su total y sus importes por categoría y por servicio.

  • costCentersArray<object>

    El gasto del mes por centro de costo, según lo asignan las reglas de atribución por etiquetas del espacio de trabajo.

Errores

  • 400 Bad Request - period no es un mes escrito como YYYY-MM.
  • 404 Not Found - El origen no tiene cifras guardadas para este mes, ningún origen FOCUS de este espacio de trabajo tiene este id, o la importación FOCUS no está activada para este 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.
  • 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}/focus-sources/{sourceId}/periods/{period}
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}/periods/{period}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
{
   "sourceId": "string",
   "period": "string",
   "rows": number,
   "version": "string",
   "asOf": "string",
   "totals": { "USD": number },
   "issuers": { "string": { "USD": number } },
   "invoices": [
      {
         "issuer": "string",
         "billingAccountId": "string",
         "invoiceId": "string",
         "currency": "string",
         "total": number,
         "byCategory": { "string": number },
         "byService": { "string": number },
         "corrections": number
      }
   ],
   "costCenters": [ { "costCenter": "string", "serviceCategory": "string", "currency": "string", "amount": number } ]
}

Crear carga FOCUS

Inicia la carga de un archivo FOCUS y devuelve la URL a la que enviarlo.

POST/v1/workspaces/{regionId}/focus-sources/uploads

Cuerpo

  • fileNamestringObligatorio

    El nombre del archivo, terminado en .csv o .csv.gz.

Devuelve

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

Más detalles

Inicia la carga de un archivo FOCUS. El archivo es CSV o CSV comprimido con gzip (.csv o .csv.gz), de hasta 500 MB. Envíalo con PUT a uploadUrl con el contentType devuelto y luego llama a CompleteFocusUpload. La URL es válida durante unos minutos. Los archivos cargados van al origen de cargas del espacio de trabajo, sourceId.

Necesita acceso 'edit' a las facturas. Una clave de API puede llamarlo.

Errores

  • 400 Bad Request - El nombre del archivo no termina en .csv o .csv.gz ("Upload a FOCUS file as CSV, or gzipped CSV (.csv.gz). Parquet files are read in a later release.").
  • 404 Not Found - La importación FOCUS no está activada para este espacio de trabajo ("FOCUS import isn't switched on for this workspace yet.").
  • 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}/focus-sources/uploads
Solicitud
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/uploads" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "fileName": "string"
}
Respuesta · 201 Created
{
   "sourceId": "string",
   "uploadId": "string",
   "uploadUrl": "string",
   "contentType": "string",
   "maxBytes": number
}

Completar carga FOCUS

Avisa a Pleaxy de que un archivo FOCUS cargado ya está en su sitio, para que lo lea.

POST/v1/workspaces/{regionId}/focus-sources/uploads/{uploadId}/complete

Parámetros

  • uploadIdstringObligatorio

    El id de la carga, tal como lo devuelve CreateFocusUpload.

Devuelve

202 Accepted con el objeto que se muestra en la respuesta.

Más detalles

Indica que el archivo está cargado. Pleaxy lo lee en segundo plano y devuelve el origen de cargas; su lastRun muestra el resultado cuando la lectura ha terminado.

Necesita acceso 'edit' a las facturas. Una clave de API puede llamarlo.

Campos de la respuesta

  • kindstring

    upload: archivos que cargas. aws_s3: una exportación FOCUS de AWS Data Exports. azure_blob: una exportación FOCUS de Azure Cost Management. gcp_bigquery: la tabla FOCUS de Google Cloud. oci: los informes FOCUS de Oracle Cloud. s3_compatible: un bucket en cualquier almacenamiento compatible con S3.

  • periodsArray<string>

    Los meses de los que el origen tiene cifras guardadas, como YYYY-MM.

  • lastRunobject

    La última lectura: los meses, archivos y filas leídos, las filas omitidas por motivo, y failure.reason cuando status es failed.

  • tagKeysArray<string>

    Las claves de etiqueta más frecuentes en las filas del origen.

  • s3.keyHintstring

    Una pista breve de qué clave de acceso secreta está guardada. El secreto en sí nunca se devuelve.

Errores

  • 400 Bad Request - El archivo supera los 500 MB, o uploadId no es un id de carga.
  • 404 Not Found - Ninguna carga con este id está en espera en este espacio de trabajo: vuelve a cargar el archivo. También cuando la importación FOCUS no está activada para este 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.
  • 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}/focus-sources/uploads/{uploadId}/complete
Solicitud
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/uploads/{uploadId}/complete" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 202 Accepted
{
   "id": "string",
   "kind": "upload" | "aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible",
   "label": "string",
   "provider": "aws" | "azure" | "gcp" | "oci",
   "connectionId": "string",
   "aws": { "bucket": "string", "prefix": "string", "region": "string" },
   "azure": { "storageAccount": "string", "container": "string", "directory": "string" },
   "gcp": { "table": "string" },
   "oci": { "region": "string" },
   "s3": { "endpoint": "string", "region": "string", "bucket": "string", "prefix": "string", "accessKeyId": "string", "keyHint": "string" },
   "periods": [ "string" ],
   "lastRun": {
      "runId": "string",
      "startedAt": "string",
      "finishedAt": "string",
      "status": "ok" | "partial" | "failed",
      "trigger": "schedule" | "manual" | "upload",
      "periods": [ "string" ],
      "files": number,
      "rows": number,
      "skipped": number,
      "skippedByReason": { "noBillingPeriod": number, "badNumber": number, "badCurrency": number, "badChargePeriod": number },
      "ignoredFiles": number,
      "version": "string",
      "failure": { "reason": "accessDenied" | "notFound" | "wrongRegion" | "notFocus" | "parquetUnsupported" | "connectionMissing" | "credentialRejected" | "unreachable" | "other", "detail": "string" }
   },
   "tagKeys": [ "string" ],
   "commitments": [ { "id": "string", "contractId": "string", "category": "string", "type": "string", "periodStart": "string", "periodEnd": "string", "cost": number, "currency": "string" } ],
   "createdAt": "string",
   "updatedAt": "string"
}

Listar emisores FOCUS

Lista los emisores de facturas de los meses FOCUS guardados y el proveedor al que corresponde cada uno.

GET/v1/workspaces/{regionId}/focus-sources/issuers

Devuelve

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

Más detalles

Devuelve todos los emisores de facturas de los meses FOCUS guardados (los tres últimos por origen), con lo que facturó cada uno por moneda y el proveedor al que corresponde, si lo hay.

Necesita acceso 'view' a las facturas.

Campos de la respuesta

  • issuerstring

    El nombre del emisor de la factura tal como figura en los archivos FOCUS.

  • mappedBy"person" | "name"

    person: alguien asoció el emisor con el proveedor. name: Pleaxy reconoció por su nombre a un emisor conocido (AWS, Microsoft, Google, Oracle). No aparece cuando el emisor no tiene proveedor.

  • totalsobject

    Lo que facturó el emisor en los meses guardados, por código de moneda.

Errores

  • 404 Not Found - La importación FOCUS no está activada para este espacio de trabajo ("FOCUS import isn't switched on for this workspace yet.").
  • 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}/focus-sources/issuers
Solicitud
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/issuers" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Respuesta · 200 OK
[
   {
      "issuer": "string",
      "supplierConnectionId": "string",
      "supplierName": "string",
      "mappedBy": "person" | "name",
      "totals": { "USD": number }
   }
]

Asociar emisor FOCUS

Asocia un emisor de facturas FOCUS con uno de tus proveedores, u olvida la asociación.

PUT/v1/workspaces/{regionId}/focus-sources/issuers/{issuer}

Parámetros

  • issuerstringObligatorio

    El nombre del emisor tal como figura en los archivos FOCUS, codificado para URL.

Cuerpo

  • supplierConnectionIdstring | null

    El id de conexión del proveedor. null, u omitirlo, olvida la asociación.

Devuelve

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

Más detalles

Asocia un emisor de facturas con uno de los proveedores del espacio de trabajo. Devuelve los emisores como lo hace ListFocusIssuers.

Necesita acceso 'edit' a las facturas. Una clave de API puede llamarlo.

Campos de la respuesta

  • issuerstring

    El nombre del emisor de la factura tal como figura en los archivos FOCUS.

  • mappedBy"person" | "name"

    person: alguien asoció el emisor con el proveedor. name: Pleaxy reconoció por su nombre a un emisor conocido (AWS, Microsoft, Google, Oracle). No aparece cuando el emisor no tiene proveedor.

  • totalsobject

    Lo que facturó el emisor en los meses guardados, por código de moneda.

Errores

  • 400 Bad Request - El nombre del emisor está vacío o es demasiado largo.
  • 404 Not Found - Ningún proveedor de este espacio de trabajo tiene este supplierConnectionId, o la importación FOCUS no está activada para este 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.
  • 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.
PUT /v1/workspaces/{regionId}/focus-sources/issuers/{issuer}
Solicitud
curl -X PUT "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/issuers/{issuer}" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "supplierConnectionId": "string" | null
}
Respuesta · 200 OK
[
   {
      "issuer": "string",
      "supplierConnectionId": "string",
      "supplierName": "string",
      "mappedBy": "person" | "name",
      "totals": { "USD": number }
   }
]
Habla con nosotros