CPQ.core API - Documentação

Autenticação

Todas as chamadas à API (exceto /health) requerem autenticação através de uma API Key no header do pedido.

Obter API Key

As API Keys são geridas no backoffice em Stores > API Keys. Cada key está associada a um tenant e tem permissões específicas.

Header de Autenticação

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

ⓘ

Alternativa: Também pode usar o header Authorization: Bearer your-api-key

Rate Limits

Os limites de pedidos dependem do plano contratado:

Plano	Pedidos/minuto	Pedidos/dia
Free	60	1,000
Pro	300	10,000
Enterprise	Ilimitado	Ilimitado

Headers de Rate Limit

Cada resposta inclui informação sobre o rate limit:

Header	Descrição
`X-RateLimit-Limit`	Limite máximo de pedidos
`X-RateLimit-Remaining`	Pedidos restantes no período
`X-RateLimit-Reset`	Timestamp Unix quando o limite reseta

Tratamento de Erros

A API usa códigos HTTP standard para indicar sucesso ou falha dos pedidos.

Código	Significado	Ação Recomendada
`200`	Sucesso	Processar resposta normalmente
`400`	Pedido Inválido	Verificar estrutura do JSON
`401`	Não Autorizado	Verificar API Key
`403`	Proibido	API Key não tem acesso ao tenant
`404`	Não Encontrado	Verificar product_id
`422`	Validação Falhou	Mostrar erros ao utilizador
`429`	Rate Limit	Aguardar e tentar novamente
`500`	Erro Interno	Contactar suporte

Formato de Erro

Resposta de Erro

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

Endpoints

GET /health Verificar estado do serviço ▼

Retorna o estado de saúde do serviço. Não requer autenticação.

Exemplo

Request

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

Response 200

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

GET /v1/products/{product_id}/form Obter formulário do produto ▼

Retorna a estrutura do formulário para um configurador de produto, incluindo campos, validações e condições de visibilidade.

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 Calcular preço e BOM ▼

Calcula o preço e outputs (incluindo BOM para produção) com base na configuração fornecida.

💡

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 Validar schema DSL ▼

Valida um schema DSL sem o guardar. Útil para verificar sintaxe antes de guardar ou testar schemas em desenvolvimento.

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