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.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":"Taxa de Instalação", "operationType":"Service", "value":"350.00", "deleted":false, "systemMd5":"mno456pqr789" } ], "terms":[ { "id":"TERM-999", "description":"Pagamento Parcelado", "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.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.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, ProjectDesignId e ProjectDesignVersionId.
- 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.