Promob – API de Integração de Budgets

A API de Integração de Budgets permite que sistemas externos consultem, insiram e gerenciem orçamentos gerados no Promob. A API segue arquitetura RESTful, utiliza autenticação via API Key e retorna dados no formato JSON. Foi desenvolvida utilizando Azure Functions.

Principais características:

• Autenticação segura via API Key.

• Retornos em formato JSON.

   

Autenticação

A autenticação é realizada por meio de uma API Key exclusiva. Todas as requisições devem conter o header:

X-Integration-ApiKey: sua-api-key-aqui.

Endpoints da API

A API possui endpoints para consulta e download de orçamentos.

Requisições

1. Consultar Budgets (GET /api/Budgets/SearchBudgets)

Permite buscar orçamentos por período e filtros opcionais.

Retornos possíveis:

• 200 OK: Lista de BudgetInfo em JSON.

• 204 No Content: Nenhum budget encontrado para os filtros aplicados.

• 400 Bad Request: Parâmetros inválidos ou corpo malformado.

• 401 Unauthorized: API Key ausente ou inválida.

• 403 Forbidden: API Key inválida.
   

Exemplo de requisição: 

GET https://api-pr-connect-budgets-integrations.promob.com/api/Budgets/SearchBudgets?createdAfter=2024-01-01T00:00:00&createdBefore=2024-12-31T23:59:59&serialNumber=58192707&accountId=3942&systemId=SYS-001 

Headers:

X-Integration-ApiKey: abc123xyz789

Exemplo de resposta (200 OK):

[
 {
    "id":"8e92b1a5-42d1-4b12-a9e8-3f8c109d22b4",
    "lang":"pt-BR",
    "createOn":"2026-03-05T14:20:00Z",
    "currencySymbol":"R$",
    "connectInfo":{
       "projectId":"f9e8d7c6-b5a4-4321-0fed-cba987654321",
       "projectDesignId":null,
       "projectDesignVersionId":null
    },
    "systemId":"SYS-999",
    "accountId":"ACC-888777",
    "distribution":"Enterprise",
    "serialnumber":"SN-2026-XPT",
    "systemRevision":"2026-02-15T08:00:00Z",
    "promobVersion":"6.1.2.5",
    "connectVersion":"3.1.0",
    "metadatas":[
       {
          "id":"CustomerName",
          "value":"Mariana Oliveira"
       }
    ],
    "paymentTerms":{
       "additionalEntries":[
          {
             "id":"ADIT-001",
             "description":"Tarifa de Instalación",
             "operationType":"Service",
             "value":"350.00",
             "deleted":false,
             "systemMd5":"mno456pqr789"
          }
       ],
       "terms":[
          {
             "id":"TERM-999",
             "description":"Pago a Plazos",
             "hasDownPayment":false,
             "selected":true,
             "parcelQuantity":10,
             "percentualDiscount":5.0,
             "parcelValue":1200.00,
             "initialValue":0.00,
             "parceledTotal":12000.00,
             "generalTotal":11750.00,
             "calculusValue":12000.00,
             "deleted":false,
             "hasCustomParcels":false
          }
       ]
    },
    "pluginId":"9900"
 }
]

2. Obter Budget por ID (GET /api/Budgets/GetBudgetInfoId/{id})

Retorna um orçamento específico com base em seu identificador único (GUID).

Retornos possíveis:

• 200 OK: Objeto BudgetInfo retornado com sucesso.

• 204 No Content: Budget não encontrado.

• 400 Bad Request: Identificador inválido ou malformado.

• 401 Unauthorized: Falha de autenticação (API Key ausente ou PluginID inválido).

• 403 Forbidden: API Key inválida.
   

Exemplo de requisição:

GET https://api-pr-connect-budgets-integrations.promob.com/api/Budgets/GetBudgetInfoId/123e4567-e89b-12d3-a456-426614174000 

3. Obter URI de Download do Budget (GET /api/Budgets/{budgetId})

Retorna a URI de download do arquivo de orçamento.

Retornos possíveis:

• 200 OK: Objeto BudgetInfoURI retornado com sucesso.

• 204 No Content: Budget não encontrado ou URI não pôde ser gerada.

• 400 Bad Request: Parâmetros inválidos ou malformados.

• 401 Unauthorized: Não autorizado ou headers inválidos.

• 403 Forbidden: API Key inválida.
   

Exemplo de resposta:

{
"budgetId": "123e4567-e89b-12d3-a456-426614174000",
"uri": "https://api-pr-connect-budgets-integrations.promob.com/budgets/123e4567-e89b-12d3-a456-426614174000/download"
}

Modelos de Dados

Confira abaixo os principais modelos de dados utilizados pela API. Todos os retornos seguem o formato JSON.

• BudgetInfo contém os campos: Id, Lang, CreateOn, CurrencySymbol, SystemId, AccountId, Serialnumber, PromobVersion, ConnectInfo, PaymentTerms, PluginId.

• ConnectInfo contém: ProjectId, DesignOptionId e DesignVersionId.

• PaymentTerms contém: AdditionalEntries e Terms.

Códigos de Retorno HTTP

A API utiliza os códigos HTTP padrão para indicar o status das requisições:

• 200 OK: Sucesso com retorno de dados.

• 201 Created: Recurso criado com sucesso.

• 204 No Content: Requisição bem-sucedida sem conteúdo.

• 400 Bad Request: Erro de requisição.

• 401 Unauthorized: Autenticação inválida.

• 403 Forbidden: Acesso negado.

• 404 Not Found: Recurso inexistente.

• 500 Internal Server Error: Erro interno no servidor.

Estrutura do arquivo budget.json

O arquivo budget.json, retornado no download do orçamento, contém informações detalhadas do projeto, preços totais e categorias do orçamento.

Objeto Project

O objeto Project identifica o projeto, a opção de design e a versão de design associados ao orçamento.

Campos

Campo removido

O campo DesignOptionType foi descontinuado e não é mais retornado no budget.json.

Exemplo:

"Project": {
  "ProjectId": "f9e8d7c6-b5a4-4321-0fed-cba987654321",
  "DesignOptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "DesignVersionId": "11223344-5566-7788-99aa-bbccddeeff00"
}

Objeto TotalPrices

O objeto TotalPrices representa os preços totais consolidados do orçamento, separados entre preço de pedido (Order) e preço de orçamento (Budget).

Campos

Estrutura do objeto PriceInfo

Estrutura do objeto PriceItem

Exemplo:

"TotalPrices": {
  "Value": "15000.00",
  "Order": {
      "Value": "15000.00",
      "Items": [
          {
              "Id": "PRICE-001",
              "Description": "Preço de tabela",
              "Value": "15000.00"
          }
      ]
  },
  "Budget": {
      "Value": "14250.00",
      "Items": [
          {
              "Id": "PRICE-001",
              "Description": "Preço de tabela",
              "Value": "14250.00"
          }
      ]
  }
}

Objeto Categories

A lista Categories agrupa os itens do orçamento por categoria, cada uma contendo seus respectivos preços totais.

Campos de cada categoria

Exemplo:

"Categories": [
  {
      "Description": "Cozinha",
      "TotalPrices": {
          "Value": "8500.00",
          "Order": {
              "Value": "8500.00",
              "Items": [
                  {
                      "Id": "PRICE-001",
                      "Description": "Preço de tabela",
                      "Value": "8500.00"
                  }
              ]
          },
          "Budget": {
              "Value": "8000.00",
              "Items": [
                  {
                      "Id": "PRICE-001",
                      "Description": "Preço de tabela",
                      "Value": "8000.00"
                  }
              ]
          }
      }
  },
  {
      "Description": "Dormitório",
      "TotalPrices": {
          "Value": "6500.00",
          "Order": {
              "Value": "6500.00",
              "Items": [
                  {
                      "Id": "PRICE-001",
                      "Description": "Preço de tabela",
                      "Value": "6500.00"
                  }
              ]
          },
          "Budget": {
              "Value": "6250.00",
              "Items": [
                  {
                      "Id": "PRICE-001",
                      "Description": "Preço de tabela",
                      "Value": "6250.00"
                  }
              ]
          }
      }
  }
]