# Integração com a Azure Pricing Calculator

Esta especificação descreve como consultar os recursos disponíveis e criar uma
estimativa compartilhada na Azure Pricing Calculator.

## Estado da integração

`POST /api/azure/create` utiliza um snapshot versionado dos estados de produto
do frontend e o endpoint interno de compartilhamento da calculadora. Em caso de
sucesso, retorna uma URL `https://azure.com/e/...` que abre a estimativa preenchida.

Essa integração é experimental: o endpoint e os esquemas usados não são públicos
nem documentados pela Microsoft e podem mudar sem aviso. O snapshot foi capturado
em `2026-11-11T10:05:49.065Z`, na versão
`20261105-0543-20261106-0128-189731462` da calculadora.

Referência oficial:

- [Calculator](https://calculator.app.br)

## Autenticação

Os endpoints descritos neste documento não exigem autenticação atualmente. Nunca
envie credenciais, tokens, chaves ou outros segredos encontrados no repositório.

## `GET /spec.md`

Retorna esta especificação com `Content-Type: text/markdown; charset=utf-8`.

Respostas:

- `200 OK`: especificação gerada.

## `GET /api/azure/resources`

Retorna o catálogo atual de produtos da Azure Pricing Calculator. O campo `slug`
identifica o valor aceito em `resources[].type`. Consulte os recursos e suas
propriedades por meio do seguinte cURL:

```bash
curl --location 'https://calculator.app.br/api/azure/resources' \
--header 'Accept: application/json'
```

Respostas:

- `200 OK`: catálogo atual.
- `502 Bad Gateway`: falha ao consultar o catálogo externo.

## `POST /api/azure/create`

Para gerar o calculator, chame este endpoint com os recursos de infraestrutura
desejados. Em caso de sucesso, a resposta conterá o link para acessar o cálculo
gerado.

Cabeçalho:

```http
Content-Type: application/json
```

Regras:

- `name`: obrigatório, de 1 a 200 caracteres.
- `currency`: código ISO 4217 com exatamente três letras maiúsculas.
- `resources`: obrigatório, de 1 a 100 itens.
- `resources[].type`: `slug` existente no catálogo retornado por
  `GET /api/azure/resources`.
- `configuration`: pode ficar vazio para usar a configuração padrão capturada.
- Campos nativos presentes no estado do produto podem ser substituídos diretamente.
- `region`, `quantity` e `hoursPerMonth` são convertidos para os campos nativos
  `region`, `count` e `hours`, quando disponíveis.
- Para `virtual-machines`, `sku` é convertido para `size`, o preço público é
  atualizado pela Retail Prices API e `operatingSystem` aceita `Linux` ou `Windows`.
- Para `githubenterprise`, `planLicenseUsers` informa a quantidade de usuários do
  GitHub Enterprise, enquanto `copilotEnterpriseUsers` e `copilotBusinessUsers`
  representam as licenças atribuídas de GitHub Copilot Enterprise e Business.
  Esses campos incluem os respectivos custos na estimativa, mas não provisionam
  nem atribuem assentos diretamente em uma organização GitHub.
- `layoutId`, `prices`, `resourceId`, `serviceSlug`, `total` e `upfrontTotal` são
  controlados pelo servidor e não podem ser enviados.
- Configurações customizadas de produtos diferentes de VM usam o esquema interno
  capturado e podem exigir atualização do snapshot quando a Microsoft alterar o frontend.

Respostas:

- `200 OK`: estimativa compartilhada criada.
- `400 Bad Request`: JSON inválido ou campos básicos inválidos.
- `422 Unprocessable Entity`: configuração inválida, preço ausente ou preço ambíguo.
- `502 Bad Gateway`: falha ao consultar preços ou compartilhar a estimativa.

Exemplo de resposta com `Content-Type: text/plain; charset=utf-8`:

```json
https://azure.com/e/753ad3f3630b4697abd02773a589e888
```

Cada chamada bem-sucedida cria uma nova URL específica.

Exemplo de erro de validação:

```json
{
  "title": "The shared Azure calculator estimate could not be created.",
  "status": 422,
  "errors": {
    "resources[0].type": [
      "Resource type 'unknown' is not present in the calculator snapshot."
    ]
  }
}
```

## Exemplos de criação por recurso

Todos os exemplos abaixo foram validados com sucesso contra
`https://calculator.app.br/api/azure/create`. Uma configuração vazia utiliza os
valores padrão capturados para o recurso.

### Virtual Machines

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Virtual Machines",
    "currency": "USD",
    "resources": [
      {
        "type": "virtual-machines",
        "configuration": {
          "region": "brazilsouth",
          "sku": "Standard_D2s_v5",
          "operatingSystem": "Linux",
          "quantity": 1,
          "hoursPerMonth": 730
        }
      }
    ]
  }'
```

### Storage Accounts

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Storage Accounts",
    "currency": "USD",
    "resources": [
      {
        "type": "storage",
        "configuration": {}
      }
    ]
  }'
```

### PostgreSQL Database

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de PostgreSQL Database",
    "currency": "USD",
    "resources": [
      {
        "type": "postgresql",
        "configuration": {}
      }
    ]
  }'
```

### SQL Database

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de SQL Database",
    "currency": "USD",
    "resources": [
      {
        "type": "azure-sql-database",
        "configuration": {}
      }
    ]
  }'
```

### Redis Cache

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Redis Cache",
    "currency": "USD",
    "resources": [
      {
        "type": "redis-cache",
        "configuration": {}
      }
    ]
  }'
```

### Kubernetes Service

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Kubernetes Service",
    "currency": "USD",
    "resources": [
      {
        "type": "kubernetes-service",
        "configuration": {}
      }
    ]
  }'
```

### Load Balancer

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Load Balancer",
    "currency": "USD",
    "resources": [
      {
        "type": "load-balancer",
        "configuration": {}
      }
    ]
  }'
```

### Application Gateway

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Application Gateway",
    "currency": "USD",
    "resources": [
      {
        "type": "application-gateway",
        "configuration": {}
      }
    ]
  }'
```

### Function App

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Function App",
    "currency": "USD",
    "resources": [
      {
        "type": "functions",
        "configuration": {}
      }
    ]
  }'
```

### Cosmos DB

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Cosmos DB",
    "currency": "USD",
    "resources": [
      {
        "type": "cosmos-db",
        "configuration": {}
      }
    ]
  }'
```

### Event Hubs

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Event Hubs",
    "currency": "USD",
    "resources": [
      {
        "type": "event-hubs",
        "configuration": {}
      }
    ]
  }'
```

### Logic Apps

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Logic Apps",
    "currency": "USD",
    "resources": [
      {
        "type": "logic-apps",
        "configuration": {}
      }
    ]
  }'
```

### Event Grid

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Event Grid",
    "currency": "USD",
    "resources": [
      {
        "type": "event-grid",
        "configuration": {}
      }
    ]
  }'
```

### API Management

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de API Management",
    "currency": "USD",
    "resources": [
      {
        "type": "api-management",
        "configuration": {}
      }
    ]
  }'
```

### Key Vault

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Key Vault",
    "currency": "USD",
    "resources": [
      {
        "type": "key-vault",
        "configuration": {}
      }
    ]
  }'
```

### App Service

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de App Service",
    "currency": "USD",
    "resources": [
      {
        "type": "app-service",
        "configuration": {}
      }
    ]
  }'
```

### Container Instances

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Container Instances",
    "currency": "USD",
    "resources": [
      {
        "type": "container-instances",
        "configuration": {}
      }
    ]
  }'
```

### Virtual Networks

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Virtual Networks",
    "currency": "USD",
    "resources": [
      {
        "type": "virtual-network",
        "configuration": {}
      }
    ]
  }'
```

### Firewall

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Firewall",
    "currency": "USD",
    "resources": [
      {
        "type": "azure-firewall",
        "configuration": {}
      }
    ]
  }'
```

### DNS Zones

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de DNS Zones",
    "currency": "USD",
    "resources": [
      {
        "type": "dns",
        "configuration": {}
      }
    ]
  }'
```

### Purview

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Purview",
    "currency": "USD",
    "resources": [
      {
        "type": "purview",
        "configuration": {}
      }
    ]
  }'
```

### Azure Monitor

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Azure Monitor",
    "currency": "USD",
    "resources": [
      {
        "type": "monitor",
        "configuration": {}
      }
    ]
  }'
```

### Databricks

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Databricks",
    "currency": "USD",
    "resources": [
      {
        "type": "databricks",
        "configuration": {}
      }
    ]
  }'
```

### Synapse Analytics

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Synapse Analytics",
    "currency": "USD",
    "resources": [
      {
        "type": "synapse-analytics",
        "configuration": {}
      }
    ]
  }'
```

### Machine Learning

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Machine Learning",
    "currency": "USD",
    "resources": [
      {
        "type": "machine-learning-service",
        "configuration": {}
      }
    ]
  }'
```

### GitHub Enterprise com GitHub Copilot

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de GitHub Enterprise com GitHub Copilot",
    "currency": "USD",
    "resources": [
      {
        "type": "githubenterprise",
        "configuration": {
          "planLicenseUsers": 25,
          "copilotEnterpriseUsers": 10,
          "copilotBusinessUsers": 15
        }
      }
    ]
  }'
```

### Service Bus

```bash
curl --location 'https://calculator.app.br/api/azure/create' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Estimativa de Service Bus",
    "currency": "USD",
    "resources": [
      {
        "type": "service-bus",
        "configuration": {}
      }
    ]
  }'
```

## Procedimento autônomo para agentes

1. Inspecione arquivos Terraform, Bicep, ARM, Kubernetes, Docker, pipelines,
   configurações e documentação de arquitetura.
2. Considere apenas recursos efetivamente configurados ou explicitamente planejados.
3. Consulte `GET /api/azure/resources` e mapeie cada recurso para um `slug` do
   catálogo. Liste separadamente recursos sem correspondência.
4. Reutilize região, SKU, sistema operacional, quantidade e utilização encontradas.
5. Não invente parâmetros críticos. Para ausências, use somente padrões
   documentados pelo próprio projeto ou pela Microsoft e registre cada premissa.
6. Monte o JSON conforme o contrato e envie-o a `POST /api/azure/create`.
7. Apresente a URL específica retornada e as premissas utilizadas.
8. Diferencie preços públicos, preços negociados, reservas, Savings Plans e cobrança
   real. Este contrato não comprova valores faturados.