Bretzel Logo

Documentação do Endpoint de Webhook ForgeOtium v1

Visão Geral

Seu sistema receberá requisições HTTP POST contendo eventos de abastecimento (preset) em formato JSON. Esses eventos são enviados quando um preset está em andamento ou foi concluído.

Informações Necessárias para Integração

Para que possamos realizar a integração e enviar os webhooks corretamente, precisamos que o cliente forneça:

URL do endpoint: endereço HTTPS onde os webhooks deverão ser recebidos.
AccessKey: chave de acesso (GUID) para autenticação.
AccessToken: token de acesso (GUID) para autenticação.

Essas credenciais serão utilizadas nos headers das requisições.

Requisitos do Endpoint

Método: POST
Content-Type: application/json
Autenticação: Headers customizados (veja abaixo)
Timeout: O endpoint deve responder em até 5 segundos

Headers da Requisição

Header Name	Descrição	Exemplo
`X-Otium-Event`	Tipo do evento (`preset.progress` ou `preset.completed`)	`preset.progress`
`X-Otium-Webhook-Version`	Versão do webhook	`1`
`X-Otium-Access-Key`	Chave de acesso (GUID)	`f3a9b7d2-8c4e-4a1b-9e2f-7d6c5b4a3e2f`
`X-Otium-Access-Token`	Token de acesso (GUID)	`b2c5e7a1-9d8f-4c3b-8e2a-7f6d5c4b3a2e`
`X-Otium-Timestamp`	(Opcional) Timestamp UTC para registro/log	`2025-08-27T12:34:56Z`

Corpo da Requisição

O corpo é um objeto JSON conforme o exemplo abaixo:

{
  "eventId": "e7b8c8a2-4f3e-4b7a-9c2e-8d1f2a6b7c3d",
  "eventType": "preset.progress",
  "version": "1",
  "occurredAt": "2025-08-27T12:34:56.789Z",
  "preset": {
    "orderId": "a1d4e5f6-7b8c-4d9e-8f2a-3c4b5d6e7f8a",
    "presetStatus": "Success",
    "unitPrice": 5.49,
    "maxTotalValue": 100.00,
    "totalValue": 50.00,
    "totalFueledVolume": 36.27,
    "requestedAt": "2025-08-27T12:00:00Z",
    "finishedAt": "2025-08-27T12:30:00Z",
    "serverRequestedAt": "2025-08-27T12:00:01",
    "serverUpdatedAt": "2025-08-27T12:15:00",
    "serverFinishedAt": "2025-08-27T12:30:01"
  }
}

Exemplo de Payload JSON

Detalhes dos Campos

eventId: Identificador único do evento (GUID)
eventType: Tipo do evento (preset.progress ou preset.completed)
version: Versão do webhook (1)
occurredAt: Data/hora em que o evento ocorreu (ISO 8601 UTC)
preset: Objeto com detalhes do abastecimento

Objeto Preset

Campo	Tipo	Descrição
orderId	GUID	Identificador da venda/pedido
presetStatus	string	Status do preset (enum como string)
unitPrice	decimal	Preço unitário
maxTotalValue	decimal	Valor total máximo presetado
totalValue	decimal	Valor atual abastecido
totalFueledVolume	decimal	Volume total abastecido (litros)
requestedAt	string	Quando um abastecimento foi iniciado na bomba
finishedAt	string	Quando um abastecimento foi finalizado na bomba
serverRequestedAt	datetime	Timestamp do servidor para o pedido
serverUpdatedAt	datetime?	Timestamp do servidor para atualização
serverFinishedAt	datetime?	Timestamp do servidor para finalização

Resposta

Sucesso: HTTP status code 200 OK
Falha: Qualquer outro status code (o sistema tentará até 3 vezes: 1s, 3s, 10s)

Segurança

Valide os headers X-Otium-Access-Key e X-Otium-Access-Token conforme as credenciais fornecidas.

Exemplo cURL

curl -X POST https://your-endpoint.com/webhook -H "Content-Type: application/json" -H "X-Otium-Event: preset.progress" -H "X-Otium-Webhook-Version: 1" -H "X-Otium-Access-Key: e2b7c8a2-4f3e-4b7a-9c2e-8d1f2a6b7c3d" -H "X-Otium-Access-Token: a1d4e5f6-7b8c-4d9e-8f2a-3c4b5d6e7f8a" -d ''

Documentação Interativa da API

Acesse o Swagger para testar e explorar os endpoints da API:

🔗 Swagger UI

Observações

O endpoint deve ser acessível via HTTPS.
Recomenda-se registrar/logar o corpo e os headers das requisições para auditoria.
O sistema fará até 3 tentativas caso não receba HTTP 2xx.

Se precisar de mais detalhes entre em contato com nossa equipe técnica em suporte@bretzelti.com.br.