Bulutegra API and webhooks: connecting your own software

What this screen is for

On the Ayarlar → Bulutegra API ve webhook (Settings → Bulutegra API and webhook) screen you do two things:

• Create API keys so your own software (ERP, warehouse, reporting) can read the orders, products and stock in Bulutegra.
• Add webhooks to receive new orders and status changes as they happen.

The API is read-only; it cannot change anything. Writing to channels and to your ERP is done by Bulutegra. Technical details of the endpoints and fields are at developers.bulutegra.com.

Who can use it

The Ayarlar (Settings) menu appears for the Yönetici (Admin) role. Managing keys and webhooks, however, is limited to the account owner; other admin users get a permission error on this tab.

Creating an API key

1. In Ad (Name), type the name of the software that will use the key (e.g. Warehouse software).
2. Choose the Kapsam (Scope). With Temel (kişisel veri yok) (Basic, no personal data), customer names are not returned in orders. With Kişisel veri dahil (müşteri adı) (Personal data included, customer name), customer names are returned too; only choose this if you really need it.
3. Click Anahtar oluştur (Create key).
4. Copy the value in the Yeni API anahtarı (New API key) box with Kopyala (Copy) and store it somewhere safe.

The key is shown only at this moment; once you leave the page it can't be shown again. If you lose it, revoke the old one and create a new key. An account can have at most 10 active keys.

For each key the list shows the name, a shortened form of the key, a scope badge (temel or kişisel veri dahil), who created it and when, Son kullanım (Last used) and the request count.

Revoking a key

Click İptal et (Revoke) on the row and confirm. Software using the key loses access immediately. A revoked key appears dimmed in the list with its revocation date. Revoking can't be undone; create a new key if needed.

Using the API

Open the Kullanım (Usage) box to see the address, a sample request and the list of endpoints. In short:

• Send the key with every request in an "Authorization: Bearer" header.
• Only read (GET) requests are accepted.
• Endpoints: ping, siparisler (orders, with start date, channel and status filters), a single order by channel and order number, urunler (products), stok (stock, by a list of SKUs) and kanallar (channels).
• Long lists are paged: pass the "sonraki_imlec" value from the response as "imlec" in the next request.
• Each key has a per-minute request limit, shown in the Kullanım box. If you exceed it, the request is rejected with code 429; wait a moment and try again.

Adding a webhook

A webhook is Bulutegra sending a notification to your address when an event happens.

1. In Adres (Address), type the address that will receive notifications. It must start with https:// and be reachable from the public internet.
2. Under Olaylar (Events), tick the ones you want: Yeni sipariş (New order), Sipariş durumu değişti (Order status changed), Sipariş ERP'ye aktarıldı (Order transferred to ERP). At least one event must be selected.
3. Click Webhook ekle (Add webhook).
4. Copy the value in the Webhook imza sırrı (Webhook signing secret) box and store it. This value is also shown only once.

You can define at most 5 webhooks; disabled webhooks count towards this number. When you add a webhook, no bulk notifications are sent for past orders; notifications start with changes after it was added.

Verifying the signature

Every request comes with an "X-Bulutegra-Imza" header. Its value is a digest prefixed with "sha256=": the HMAC-SHA256 digest of the raw request body using the webhook signing secret. Compute the same digest on your server, compare it with the header and reject requests that don't match. The İmza doğrulama (Signature verification) box on the screen contains a sample verification line.

Delivery and retries

• If your address replies with anything other than 2xx, delivery is retried several times at growing intervals. The intervals are listed in the İmza doğrulama box.
• If many deliveries fail in a row, the webhook is switched off and you get a "Webhook kapatıldı" (Webhook disabled) notification. Once you've fixed the address, click Aç (Enable) on the card.
• The webhook card shows the address, an açık (on) or kapalı (off) badge, the selected events, the last delivery result and the number of consecutive errors.
• The Son teslimler (Recent deliveries) section shows each delivery's time, event, status (teslim delivered, yeniden denenecek will retry, başarısız failed), attempt count and the response received.
• Test gönder (Send test) sends a test request to your address and shows the result. Kapat (Disable) stops the webhook. Sil (Delete) removes the webhook together with its delivery records.

If something is wrong

• "Yalnız https:// adresleri kabul edilir" (Only https:// addresses are accepted): write the address with https.
• "Adres genel internette değil" (Address is not on the public internet) or "İç ağ adresleri kabul edilmez" (Internal network addresses are not accepted): the webhook address must be a domain reachable from the internet.
• "En çok 5 webhook tanımlanabilir" (At most 5 webhooks can be defined): remove a webhook you don't use with Sil.
• "En çok 10 etkin anahtar olabilir" (At most 10 active keys): revoke a key you don't use.
• If your software gets 401, check the header and that the key hasn't been revoked.
• If your software gets 429, it has exceeded the request limit; space out its requests.
• Changes made on the demo account are not saved.

Related articles: Roles, two-step verification and password reset and Data security at a glance.