CPQ.core API - Documentation

Authentication

All API calls (except /health) require authentication via an API Key in the request header.

Get API Key

API Keys are managed in the backoffice under Stores > API Keys. Each key is associated with a tenant and has specific permissions.

Authentication Header

X-API-Key: your-api-key-here

ⓘ

Alternative: You can also use the header Authorization: Bearer your-api-key

Rate Limits

Request limits depend on your plan:

Plan	Requests/minute	Requests/day
Free	60	1,000
Pro	300	10,000
Enterprise	Unlimited	Unlimited

Rate Limit Headers

Each response includes rate limit information:

Header	Description
`X-RateLimit-Limit`	Maximum request limit
`X-RateLimit-Remaining`	Remaining requests in the period
`X-RateLimit-Reset`	Unix timestamp when the limit resets

Error Handling

The API uses standard HTTP codes to indicate success or failure of requests.

Code	Meaning	Recommended Action
`200`	Success	Process response normally
`400`	Bad Request	Check JSON structure
`401`	Unauthorized	Check API Key
`403`	Forbidden	API Key lacks access to tenant
`404`	Not Found	Check product_id
`422`	Validation Failed	Show errors to user
`429`	Rate Limited	Wait and retry
`500`	Internal Error	Contact support

Error Format

Resposta de Erro

{
  "error": "Missing or invalid API key",
  "code": "UNAUTHORIZED"
}

Endpoints

GET /health Check service status ▼

Returns the service health status. No authentication required.

Exemplo

Request

curl -X GET https://cpq.peopleware.pt/api/health

Response 200

{
  "status": "healthy",
  "version": "1.9"
}

GET /v1/products/{product_id}/form Get product form ▼

Returns the form structure for a product configurator, including fields, validations and visibility conditions.

Parametros

Parametro	Tipo	Obrigatorio	Descricao
`product_id`	path	Sim	ID do produto (external_id)
`tenant_id`	query	Sim	ID do tenant
`lang`	query	Nao	Codigo de idioma (default: en)

Exemplo

Request

curl -X GET "https://cpq.peopleware.pt/api/v1/products/janela-aluminio/form?tenant_id=demo&lang=pt-PT" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "product_id": "janela-aluminio",
  "layout": "sections",
  "groups": [
    {
      "id": "dimensoes",
      "label": "Dimensoes",
      "fields": [
        {
          "id": "largura",
          "type": "number",
          "label": "Largura",
          "validation": { "min": 400, "max": 2400 },
          "unit": "mm"
        }
      ]
    }
  ],
  "quantity": {
    "min": 1,
    "max": 100,
    "step": 1
  }
}

Codigos de Resposta

200 Sucesso

401 Nao autorizado

403 Proibido

404 Nao encontrado

POST /v1/calculate Calculate price and BOM ▼

Calculates the price and outputs (including production BOM) based on the provided configuration.

💡

Dica: Use output_groups: ["*"] para obter todos os grupos de output, incluindo dados de producao (BOM).

Body

Campo	Tipo	Obrigatorio	Descricao
`tenant_id`	string	Sim	ID do tenant
`product_id`	string	Sim	ID do produto
`configuration`	object	Sim	Valores dos campos do formulario
`quantity`	integer	Nao	Quantidade (default: 1)
`lang`	string	Nao	Codigo de idioma (default: en)
`output_groups`	array	Nao	Grupos de output a incluir (["*"] para todos)

Exemplo

Request

curl -X POST https://cpq.peopleware.pt/api/v1/calculate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "demo",
    "product_id": "janela-aluminio",
    "configuration": {
      "largura": 1200,
      "altura": 1000,
      "vidro": "temperado",
      "cor": "branco"
    },
    "quantity": 1,
    "lang": "pt-PT",
    "output_groups": ["*"]
  }'

Response 200

{
  "product_id": "janela-aluminio",
  "configuration": {
    "largura": 1200,
    "altura": 1000,
    "vidro": "temperado",
    "cor": "branco"
  },
  "result": {
    "totals": {
      "price": 287.00
    },
    "groups": {
      "production": {
        "vidro_m2": 1.20,
        "perfil_m": 4.40,
        "kit_ferragens": 1,
        "parafusos": 20
      }
    }
  },
  "quantity": { "min": 1, "max": 100 },
  "warnings": [],
  "errors": []
}

Codigos de Resposta

200 Sucesso

400 Pedido invalido

401 Nao autorizado

404 Nao encontrado

422 Validacao falhou

POST /v1/validate Validate DSL schema ▼

Validates a DSL schema without saving it. Useful for checking syntax before saving or testing schemas in development.

Body

Campo	Tipo	Obrigatorio	Descricao
`schema`	string	Sim	Schema DSL a validar

Exemplo

Request

curl -X POST https://cpq.peopleware.pt/api/v1/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "let base = 100\nadd price: base * 1.23"
  }'

Response 200 - Valido

{
  "valid": true,
  "errors": [],
  "warnings": []
}

Response 200 - Invalido

{
  "valid": false,
  "errors": [
    {
      "line": 3,
      "column": 5,
      "message": "undefined variable 'y'"
    }
  ],
  "warnings": []
}

Codigos de Resposta

200 Sucesso (ver valid)

401 Nao autorizado