Idempotency | Veri Merkezi API

Ağ hatası ya da zaman aşımında isteğinizin sunucuya ulaşıp ulaşmadığını bilemezsiniz. Idempotency-Key başlığı, aynı isteği güvenle tekrarlamanızı ve müşterinin aynı mesajı iki kez almamasını sağlar.

#Desteklenen uçlar

Uç	Not
`POST /messages`	Tüm mesaj türleri.
`POST /numbers/{phone_number_id}/detach`	Numara ayırma.
`POST /calls`	İşletme başlatmalı arama.
`POST /calls/permission-request`	Arama izni isteği.
`POST /flows`	Form oluşturma.

Diğer uçlar başlığı yok sayar. Arama eylemleri (pre_accept, accept, reject, terminate) başlık olmadan da arama kimliği ve eylem bazında idempotenttir.

#Kullanım

Her yeni işlem için benzersiz bir anahtar üretin (UUID önerilir) ve aynı işlemin tekrarlarında aynı anahtarı kullanın. Anahtar 8–128 karakter olmalıdır.

curl -X POST https://api.verimerkezi.app/wa/messages \
  -H "Authorization: Bearer $VM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: siparis-VM-2026-1234-onay" \
  -d '{ "phone_number_id": "1234567890", "to": "905550000000", "type": "text", "text": { "body": "Siparişiniz onaylandı." } }'

import { randomUUID } from 'node:crypto';
const anahtar = randomUUID(); // tekrarlarda aynı değeri kullanın

import uuid
anahtar = str(uuid.uuid4())  # tekrarlarda aynı değeri kullanın

<?php
$anahtar = bin2hex(random_bytes(16)); // tekrarlarda aynı değeri kullanın

İpucu Anahtarı kendi kaydınızdan türetmek (ör. sipariş numarası + mesaj türü) yeniden başlatmalarda da aynı anahtarı üretmenizi kolaylaştırır.

#Davranış

Durum	Sonuç
İlk istek	Normal işlenir; yanıt 24 saat saklanır.
Aynı anahtar, aynı gövde	Saklanan yanıt aynen döner, `Idempotent-Replay: true` başlığıyla. Mesaj ikinci kez gitmez.
Aynı anahtar, farklı gövde	`422 idempotency_key_conflict`.
Aynı anahtarla eşzamanlı ikinci istek	`409 idempotency_in_progress` ve `Retry-After`.
Önceki deneme kesin başarısız oldu (`retryable: true`)	Aynı anahtarla tekrar denenebilir; yeniden işlenir.
Önceki denemede Meta sonucu belirsiz kaldı	Tekrar `409 meta_outcome_unknown` döner; Meta'ya ikinci kez gönderilmez.
24 saat sonra aynı anahtar	Yeni istek olarak işlenir.

Gövde karşılaştırması ham istek gövdesi üzerinden yapılır. Tekrarlarda gövdeyi bayt bayt aynı gönderin.

#Belirsiz sonuç

Meta çağrısı zaman aşımına uğrarsa mesaj gitmiş olabilir. API bu durumda 409 meta_outcome_unknown ve retryable: false döndürür. Aynı anahtarla tekrar denediğinizde mesaj yeniden gönderilmez. Mesajın gidip gitmediğini öğrenmek için:

message.status.* olayını bekleyin. Olaydaki biz_opaque_callback_data değeri, Idempotency-Key değerinizdir.
Ya da GET /messages ile mesaj kayıtlarını kontrol edin.

Durum olayı geldiğinde sunucu kaydı kendiliğinden "gönderildi" olarak kapatır; aynı anahtarla yapılan sonraki tekrar artık 200 döner.

#Gönderimi durum olayıyla eşleştirin

POST /messages isteğinde Idempotency-Key verdiğinizde sunucu Meta'ya biz_opaque_callback_data olarak bu anahtarı iletir. Meta bu değeri message.status.sent, .delivered, .read ve .failed olaylarında data.biz_opaque_callback_data alanında aynen geri gönderir. Böylece ek alan göndermeden her durum olayını kendi kaydınızla eşleştirebilirsiniz.

Farklı bir eşleştirme değeri isterseniz gövdede biz_opaque_callback_data (en fazla 512 karakter) gönderin. Bu değer gövdenin parçası olduğu için idempotency karşılaştırmasına dahildir.

#SDK davranışı

Resmî SDK'lar her yazma isteğine otomatik bir Idempotency-Key ekler ve kendi yeniden denemelerinde aynı anahtarı kullanır. Uygulama düzeyinde (ör. süreç yeniden başlatıldığında) tekrar yapacaksanız anahtarı kendiniz yönetin.