Referência da API

FOCUS

Exporte suas faturas como um conjunto de dados FOCUS e leia os dados de faturamento FOCUS dos seus provedores.

Mais sobre este recurso

FOCUS é o formato aberto da FinOps Foundation para dados de faturamento. A Pleaxy trabalha com ele nos dois sentidos. Uma exportação grava as faturas, notas de débito e notas de crédito aceitas do espaço de trabalho como um conjunto de dados FOCUS Cost and Usage, para uma ferramenta de FinOps ou de relatórios. Uma fonte FOCUS lê dados de faturamento nesse formato, de arquivos que você envia ou da exportação FOCUS do próprio provedor, e guarda os totais de cada mês por fatura, emissor e centro de custo. A exportação e a importação são ativadas por espaço de trabalho; enquanto uma está desativada, seus endpoints respondem 404.

Listar exportações FOCUS

Lista as exportações FOCUS dos últimos 7 dias e se a exportação está ativada.

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

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna se a exportação FOCUS está ativada para o espaço de trabalho e suas exportações dos últimos 7 dias, das mais recentes para as mais antigas, no máximo 20. A lista não traz links de download; obtenha-os com GetFocusExport.

Precisa de acesso 'view' às faturas. Uma chave de API pode chamá-lo.

Campos da resposta

  • enabledboolean

    Se a exportação FOCUS está ativada para o espaço de trabalho.

  • from, tostring

    O primeiro e o último período de faturamento da exportação, como YYYY-MM.

  • rowCount, documentCountnumber

    As linhas do conjunto de dados e as faturas, notas de débito e notas de crédito de que elas vêm.

  • expiresAtstring

    Quando a Pleaxy exclui os arquivos da exportação, 7 dias depois de criada.

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}/focus-exports
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-exports" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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"
      }
   ]
}

Criar exportação FOCUS

Exporta as faturas de um intervalo de meses como um conjunto de dados FOCUS.

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

Corpo

  • fromstringObrigatório

    O primeiro período de faturamento, como YYYY-MM.

  • tostringObrigatório

    O último período de faturamento, como YYYY-MM, incluído. O intervalo abrange no máximo 36 meses.

  • version"1.2" | "1.4"

    A versão do FOCUS. 1.2 quando ausente. Uma exportação 1.4 também pode trazer um conjunto de dados Contract Commitment.

  • include"all" | "non_cloud"

    non_cloud deixa de fora as faturas dos provedores de nuvem e IA, que uma ferramenta de FinOps pode ler das exportações FOCUS dos próprios provedores. all quando ausente.

  • format"csv" | "parquet"

    O formato do arquivo. csv quando ausente.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Grava as faturas, notas de débito e notas de crédito aceitas do espaço de trabalho para os períodos de faturamento from..to como um conjunto de dados FOCUS Cost and Usage com um arquivo de metadados. Há uma linha por item, lançamento de imposto e ajuste; as notas de crédito são negativas; os valores ficam na moeda de cada documento. A resposta traz links de download válidos por 15 minutos, e os arquivos são mantidos por 7 dias. Uma exportação não altera nada no espaço de trabalho.

Precisa de acesso 'view' às faturas. Uma chave de API pode chamá-lo.

Campos da resposta

  • from, tostring

    O primeiro e o último período de faturamento da exportação, como YYYY-MM.

  • rowCount, documentCountnumber

    As linhas do conjunto de dados e as faturas, notas de débito e notas de crédito de que elas vêm.

  • expiresAtstring

    Quando a Pleaxy exclui os arquivos da exportação, 7 dias depois de criada.

  • downloadUrl, metadataUrlstring

    Links para o conjunto de dados e seu arquivo de metadados, válidos por 15 minutos. Chame GetFocusExport para obter links novos.

  • commitmentsUrlstring

    Um link para o conjunto de dados Contract Commitment, presente só quando a exportação tem um.

Erros

  • 400 Bad Request - from ou to não é um mês escrito como YYYY-MM, from é posterior a to, ou o intervalo abrange mais de 36 meses.
  • 404 Not Found - A exportação FOCUS não está ativada para este espaço de trabalho ("FOCUS export isn't switched on for this workspace yet.").
  • 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}/focus-exports
Requisição
POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/focus-exports
{
   "from": "2026-07",
   "to": "2026-09",
   "include": "non_cloud"
}
Resposta · 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://..."
}

Obter exportação FOCUS

Obtém uma exportação FOCUS com links de download novos.

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

Parâmetros

  • exportIdstringObrigatório

    O id da exportação, como CreateFocusExport o retorna.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna uma exportação dos últimos 7 dias com links novos para seu conjunto de dados e seu arquivo de metadados, válidos por 15 minutos.

Precisa de acesso 'view' às faturas. Uma chave de API pode chamá-lo.

Campos da resposta

  • from, tostring

    O primeiro e o último período de faturamento da exportação, como YYYY-MM.

  • rowCount, documentCountnumber

    As linhas do conjunto de dados e as faturas, notas de débito e notas de crédito de que elas vêm.

  • expiresAtstring

    Quando a Pleaxy exclui os arquivos da exportação, 7 dias depois de criada.

  • downloadUrl, metadataUrlstring

    Links para o conjunto de dados e seu arquivo de metadados, válidos por 15 minutos. Chame GetFocusExport para obter links novos.

  • commitmentsUrlstring

    Um link para o conjunto de dados Contract Commitment, presente só quando a exportação tem um.

Erros

  • 404 Not Found - Nenhuma exportação neste espaço de trabalho tem este id, ela expirou (as exportações são mantidas por 7 dias) ou a exportação FOCUS não está ativada para este 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.
  • 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}/focus-exports/{exportId}
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-exports/{exportId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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 fontes FOCUS

Lista as fontes FOCUS do espaço de trabalho com sua última execução e se a importação está ativada.

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

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna se a importação FOCUS está ativada e as fontes FOCUS do espaço de trabalho, cada uma com sua última execução, os meses que tem guardados e suas chaves de tag mais comuns.

Precisa de acesso 'view' às faturas.

Campos da resposta

  • enabledboolean

    Se a importação FOCUS está ativada para o espaço de trabalho.

  • kindstring

    upload: arquivos que você envia. aws_s3: uma exportação FOCUS do AWS Data Exports. azure_blob: uma exportação FOCUS do Azure Cost Management. gcp_bigquery: a tabela FOCUS do Google Cloud. oci: os relatórios FOCUS da Oracle Cloud. s3_compatible: um bucket em qualquer armazenamento compatível com S3.

  • periodsArray<string>

    Os meses para os quais a fonte tem valores guardados, como YYYY-MM.

  • lastRunobject

    A última leitura: os meses, arquivos e linhas lidos, as linhas ignoradas por motivo, e failure.reason quando status é failed.

  • tagKeysArray<string>

    As chaves de tag mais comuns nas linhas da fonte.

  • s3.keyHintstring

    Uma pista curta de qual chave de acesso secreta está guardada. O segredo em si nunca é retornado.

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}/focus-sources
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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"
      }
   ]
}

Criar fonte FOCUS

Adiciona a exportação FOCUS de um provedor como fonte que a Pleaxy lê todos os dias.

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

Corpo

  • kind"aws_s3" | "azure_blob" | "gcp_bigquery" | "oci" | "s3_compatible"Obrigatório

    Onde estão os dados FOCUS. Envie junto o objeto do mesmo provedor.

  • labelstring

    Opcional. Um nome para a fonte.

  • connectionIdstring

    A conexão de nuvem à qual a fonte pertence, como ListCloudConnections a retorna. Obrigatória para todos os tipos, exceto s3_compatible.

  • awsobject

    Para aws_s3: o bucket em que o AWS Data Exports grava, o prefixo da exportação (seu prefixo do S3 e o nome da exportação) e a região do bucket.

  • azureobject

    Para azure_blob: a conta de armazenamento, o contêiner e o diretório da exportação.

  • gcpobject

    Para gcp_bigquery: a tabela ou visualização FOCUS, como project.dataset.table.

  • ociobject

    Para oci: a região principal da tenancy.

  • s3object

    Para s3_compatible: o endpoint HTTPS, a região, o bucket e o prefixo do armazenamento, e uma chave de acesso que possa lê-lo. O segredo é guardado criptografado e nunca é retornado.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Adiciona uma fonte FOCUS. A fonte de uma nuvem (aws_s3, azure_blob, gcp_bigquery ou oci) pertence a uma das conexões de nuvem do espaço de trabalho do mesmo provedor; ela passa então a ser a fonte das linhas de IA dessa conexão, no lugar da leitura de IA do próprio conector. Uma fonte s3_compatible traz sua própria chave de acesso. A Pleaxy lê uma fonte diariamente, e na hora com SyncFocusSource. Uma conexão tem no máximo uma fonte FOCUS.

Somente sessão conectada, com acesso 'edit' às faturas: uma fonte abre um caminho de leitura para a sua conta de nuvem, então é uma pessoa que a adiciona e remove.

Campos da resposta

  • kindstring

    upload: arquivos que você envia. aws_s3: uma exportação FOCUS do AWS Data Exports. azure_blob: uma exportação FOCUS do Azure Cost Management. gcp_bigquery: a tabela FOCUS do Google Cloud. oci: os relatórios FOCUS da Oracle Cloud. s3_compatible: um bucket em qualquer armazenamento compatível com S3.

  • periodsArray<string>

    Os meses para os quais a fonte tem valores guardados, como YYYY-MM.

  • lastRunobject

    A última leitura: os meses, arquivos e linhas lidos, as linhas ignoradas por motivo, e failure.reason quando status é failed.

  • tagKeysArray<string>

    As chaves de tag mais comuns nas linhas da fonte.

  • s3.keyHintstring

    Uma pista curta de qual chave de acesso secreta está guardada. O segredo em si nunca é retornado.

Erros

  • 400 Bad Request - Um campo está ausente ou é inválido, a conexão é de outra nuvem que não a de kind, ou a conexão já tem uma fonte FOCUS.
  • 403 Forbidden - Quem chama não é uma pessoa conectada (por exemplo, uma chave de API), ou não tem acesso 'edit' às faturas.
  • 404 Not Found - Nenhuma conexão de nuvem neste espaço de trabalho tem este connectionId, ou a importação FOCUS não está ativada para este 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.
POST /v1/workspaces/{regionId}/focus-sources
Requisição
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" }
}
Resposta · 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"
}

Obter fonte FOCUS

Obtém uma fonte FOCUS com sua última execução.

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

Parâmetros

  • sourceIdstringObrigatório

    O id da fonte FOCUS, como ListFocusSources o retorna.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna uma fonte FOCUS com sua última execução. Consulte-a depois de SyncFocusSource ou CompleteFocusUpload para saber quando a leitura terminou.

Precisa de acesso 'view' às faturas.

Campos da resposta

  • kindstring

    upload: arquivos que você envia. aws_s3: uma exportação FOCUS do AWS Data Exports. azure_blob: uma exportação FOCUS do Azure Cost Management. gcp_bigquery: a tabela FOCUS do Google Cloud. oci: os relatórios FOCUS da Oracle Cloud. s3_compatible: um bucket em qualquer armazenamento compatível com S3.

  • periodsArray<string>

    Os meses para os quais a fonte tem valores guardados, como YYYY-MM.

  • lastRunobject

    A última leitura: os meses, arquivos e linhas lidos, as linhas ignoradas por motivo, e failure.reason quando status é failed.

  • tagKeysArray<string>

    As chaves de tag mais comuns nas linhas da fonte.

  • s3.keyHintstring

    Uma pista curta de qual chave de acesso secreta está guardada. O segredo em si nunca é retornado.

Erros

  • 404 Not Found - Nenhuma fonte FOCUS neste espaço de trabalho tem este id, ou a importação FOCUS não está ativada para este 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.
  • 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}/focus-sources/{sourceId}
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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 fonte FOCUS

Lê uma fonte FOCUS agora, em segundo plano.

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

Parâmetros

  • sourceIdstringObrigatório

    O id da fonte FOCUS, como ListFocusSources o retorna.

Retorna

202 Accepted com o objeto mostrado na resposta.

Mais detalhes

Inicia uma leitura da fonte em segundo plano, relendo os meses que ela contém, e retorna a fonte. Seu lastRun mostra o resultado quando a leitura termina.

Precisa de acesso 'edit' às faturas. Uma chave de API pode chamá-lo.

Campos da resposta

  • kindstring

    upload: arquivos que você envia. aws_s3: uma exportação FOCUS do AWS Data Exports. azure_blob: uma exportação FOCUS do Azure Cost Management. gcp_bigquery: a tabela FOCUS do Google Cloud. oci: os relatórios FOCUS da Oracle Cloud. s3_compatible: um bucket em qualquer armazenamento compatível com S3.

  • periodsArray<string>

    Os meses para os quais a fonte tem valores guardados, como YYYY-MM.

  • lastRunobject

    A última leitura: os meses, arquivos e linhas lidos, as linhas ignoradas por motivo, e failure.reason quando status é failed.

  • tagKeysArray<string>

    As chaves de tag mais comuns nas linhas da fonte.

  • s3.keyHintstring

    Uma pista curta de qual chave de acesso secreta está guardada. O segredo em si nunca é retornado.

Erros

  • 400 Bad Request - A fonte é a fonte de uploads, que é lida quando um arquivo chega: envie o arquivo de novo para relê-lo.
  • 404 Not Found - Nenhuma fonte FOCUS neste espaço de trabalho tem este id, ou a importação FOCUS não está ativada para este espaço de trabalho.
  • 503 Service Unavailable - A leitura não pode ser iniciada agora. Tente de novo em alguns minutos.
  • 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}/focus-sources/{sourceId}/sync
Requisição
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}/sync" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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"
}

Excluir fonte FOCUS

Remove uma fonte FOCUS com os meses que ela guardou.

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

Parâmetros

  • sourceIdstringObrigatório

    O id da fonte FOCUS, como ListFocusSources o retorna.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Remove a fonte com os meses e as linhas de IA que ela guardou. A leitura de IA do próprio conector é retomada para a sua conexão de nuvem.

Somente sessão conectada, com acesso 'edit' às faturas: uma fonte abre um caminho de leitura para a sua conta de nuvem, então é uma pessoa que a adiciona e remove.

Erros

  • 403 Forbidden - Quem chama não é uma pessoa conectada (por exemplo, uma chave de API), ou não tem acesso 'edit' às faturas.
  • 404 Not Found - Nenhuma fonte FOCUS neste espaço de trabalho tem este id, ou a importação FOCUS não está ativada para este 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}/focus-sources/{sourceId}
Requisição
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 200 OK
{
   "removed": true
}

Obter período de fonte FOCUS

Obtém um mês guardado de uma fonte FOCUS, por fatura, centro de custo e emissor.

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

Parâmetros

  • sourceIdstringObrigatório

    O id da fonte FOCUS, como ListFocusSources o retorna.

  • periodstringObrigatório

    O mês, como YYYY-MM.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna um mês guardado de uma fonte: seus totais por moeda, cada fatura por número com seus valores por categoria e serviço, o gasto por centro de custo e os totais por emissor.

Precisa de acesso 'view' às faturas.

Campos da resposta

  • totalsobject

    O total faturado do mês, por código de moeda.

  • invoicesArray<object>

    Cada fatura que as linhas do mês citam, com seu total e seus valores por categoria e por serviço.

  • costCentersArray<object>

    O gasto do mês por centro de custo, como as regras de atribuição por tags do espaço de trabalho o distribuem.

Erros

  • 400 Bad Request - period não é um mês escrito como YYYY-MM.
  • 404 Not Found - A fonte não tem valores guardados para este mês, nenhuma fonte FOCUS neste espaço de trabalho tem este id, ou a importação FOCUS não está ativada para este 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.
  • 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}/focus-sources/{sourceId}/periods/{period}
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/{sourceId}/periods/{period}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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 } ]
}

Criar upload FOCUS

Inicia o upload de um arquivo FOCUS e retorna a URL para onde enviá-lo.

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

Corpo

  • fileNamestringObrigatório

    O nome do arquivo, terminado em .csv ou .csv.gz.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Inicia o upload de um arquivo FOCUS. O arquivo é CSV ou CSV compactado com gzip (.csv ou .csv.gz), de até 500 MB. Envie-o com PUT para uploadUrl com o contentType retornado e depois chame CompleteFocusUpload. A URL é válida por alguns minutos. Os arquivos enviados vão para a fonte de uploads do espaço de trabalho, sourceId.

Precisa de acesso 'edit' às faturas. Uma chave de API pode chamá-lo.

Erros

  • 400 Bad Request - O nome do arquivo não termina em .csv ou .csv.gz ("Upload a FOCUS file as CSV, or gzipped CSV (.csv.gz). Parquet files are read in a later release.").
  • 404 Not Found - A importação FOCUS não está ativada para este espaço de trabalho ("FOCUS import isn't switched on for this workspace yet.").
  • 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}/focus-sources/uploads
Requisição
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"
}
Resposta · 201 Created
{
   "sourceId": "string",
   "uploadId": "string",
   "uploadUrl": "string",
   "contentType": "string",
   "maxBytes": number
}

Concluir upload FOCUS

Avisa a Pleaxy de que um arquivo FOCUS enviado está no lugar, para que seja lido.

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

Parâmetros

  • uploadIdstringObrigatório

    O id do upload, como CreateFocusUpload o retorna.

Retorna

202 Accepted com o objeto mostrado na resposta.

Mais detalhes

Diz que o arquivo foi enviado. A Pleaxy o lê em segundo plano e retorna a fonte de uploads; seu lastRun mostra o resultado quando a leitura termina.

Precisa de acesso 'edit' às faturas. Uma chave de API pode chamá-lo.

Campos da resposta

  • kindstring

    upload: arquivos que você envia. aws_s3: uma exportação FOCUS do AWS Data Exports. azure_blob: uma exportação FOCUS do Azure Cost Management. gcp_bigquery: a tabela FOCUS do Google Cloud. oci: os relatórios FOCUS da Oracle Cloud. s3_compatible: um bucket em qualquer armazenamento compatível com S3.

  • periodsArray<string>

    Os meses para os quais a fonte tem valores guardados, como YYYY-MM.

  • lastRunobject

    A última leitura: os meses, arquivos e linhas lidos, as linhas ignoradas por motivo, e failure.reason quando status é failed.

  • tagKeysArray<string>

    As chaves de tag mais comuns nas linhas da fonte.

  • s3.keyHintstring

    Uma pista curta de qual chave de acesso secreta está guardada. O segredo em si nunca é retornado.

Erros

  • 400 Bad Request - O arquivo tem mais de 500 MB, ou uploadId não é um id de upload.
  • 404 Not Found - Nenhum upload com este id está aguardando neste espaço de trabalho: envie o arquivo de novo. Também quando a importação FOCUS não está ativada para este 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.
  • 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}/focus-sources/uploads/{uploadId}/complete
Requisição
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/uploads/{uploadId}/complete" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 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 emissores FOCUS

Lista os emissores de faturas nos meses FOCUS guardados e o fornecedor a que cada um corresponde.

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

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retorna todos os emissores de faturas nos meses FOCUS guardados (os três últimos por fonte), com o que cada um faturou por moeda e o fornecedor a que corresponde, se houver.

Precisa de acesso 'view' às faturas.

Campos da resposta

  • issuerstring

    O nome do emissor da fatura como aparece nos arquivos FOCUS.

  • mappedBy"person" | "name"

    person: alguém associou o emissor ao fornecedor. name: a Pleaxy reconheceu pelo nome um emissor conhecido (AWS, Microsoft, Google, Oracle). Ausente quando o emissor não tem fornecedor.

  • totalsobject

    O que o emissor faturou nos meses guardados, por código de moeda.

Erros

  • 404 Not Found - A importação FOCUS não está ativada para este espaço de trabalho ("FOCUS import isn't switched on for this workspace yet.").
  • 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}/focus-sources/issuers
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/focus-sources/issuers" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 200 OK
[
   {
      "issuer": "string",
      "supplierConnectionId": "string",
      "supplierName": "string",
      "mappedBy": "person" | "name",
      "totals": { "USD": number }
   }
]

Associar emissor FOCUS

Associa um emissor de faturas FOCUS a um dos seus fornecedores, ou esquece a associação.

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

Parâmetros

  • issuerstringObrigatório

    O nome do emissor como aparece nos arquivos FOCUS, codificado para URL.

Corpo

  • supplierConnectionIdstring | null

    O id de conexão do fornecedor. null, ou omiti-lo, esquece a associação.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Associa um emissor de faturas a um dos fornecedores do espaço de trabalho. Retorna os emissores como ListFocusIssuers faz.

Precisa de acesso 'edit' às faturas. Uma chave de API pode chamá-lo.

Campos da resposta

  • issuerstring

    O nome do emissor da fatura como aparece nos arquivos FOCUS.

  • mappedBy"person" | "name"

    person: alguém associou o emissor ao fornecedor. name: a Pleaxy reconheceu pelo nome um emissor conhecido (AWS, Microsoft, Google, Oracle). Ausente quando o emissor não tem fornecedor.

  • totalsobject

    O que o emissor faturou nos meses guardados, por código de moeda.

Erros

  • 400 Bad Request - O nome do emissor está vazio ou é longo demais.
  • 404 Not Found - Nenhum fornecedor neste espaço de trabalho tem este supplierConnectionId, ou a importação FOCUS não está ativada para este 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.
  • 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.
PUT /v1/workspaces/{regionId}/focus-sources/issuers/{issuer}
Requisição
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
}
Resposta · 200 OK
[
   {
      "issuer": "string",
      "supplierConnectionId": "string",
      "supplierName": "string",
      "mappedBy": "person" | "name",
      "totals": { "USD": number }
   }
]
Fale conosco