Writes & idempotency

# The key identifies the ORDER you are placing, not this HTTP attempt.
# Generate it once, store it with your own record, and reuse it on retries.
IDEMPOTENCY_KEY=$(uuidgen)

curl -sS -X POST "https://api.salafems.com/ext/v1/orders" \
  -H "Authorization: Bearer $SALAF_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "facebook",
    "customer": { "phone": "01712345678", "full_name": "Rafiqul Islam" },
    "items": [
      { "sku": "TSHIRT-RED-M", "quantity": 2 }
    ],
    "shipping_charge": 120,
    "note": "Deliver after 6pm."
  }'

import { randomUUID } from "node:crypto";

// One key per logical order. Persist it next to your own order record BEFORE
// the call, so a retry after a process restart still sends the same one.
const idempotencyKey = randomUUID();

const response = await fetch("https://api.salafems.com/ext/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SALAF_API_KEY}`,
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "facebook",
    customer: { phone: "01712345678", full_name: "Rafiqul Islam" },
    items: [{ sku: "TSHIRT-RED-M", quantity: 2 }],
    shipping_charge: 120,
    note: "Deliver after 6pm.",
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message} [${error.request_id}]`);
}

// 201 with the full order: items and customer expanded, totals computed,
// stock already reserved.
const order = await response.json();
console.log(order.number, order.total_amount, order.payment_status);

// true when this was a replay of an earlier identical call.
console.log(response.headers.get("Idempotent-Replayed") === "true");

import os
import uuid

import requests

# One key per logical order — generated where the order is DECIDED, not
# inside the retry loop, and stored with your own record.
idempotency_key = str(uuid.uuid4())

response = requests.post(
    "https://api.salafems.com/ext/v1/orders",
    json={
        "channel": "facebook",
        "customer": {"phone": "01712345678", "full_name": "Rafiqul Islam"},
        "items": [{"sku": "TSHIRT-RED-M", "quantity": 2}],
        "shipping_charge": 120,
        "note": "Deliver after 6pm.",
    },
    headers={
        "Authorization": f"Bearer {os.environ['SALAF_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
    timeout=30,
)

if not response.ok:
    error = response.json()["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")

order = response.json()
print(order["number"], order["total_amount"], order["payment_status"])
print(response.headers.get("Idempotent-Replayed") == "true")

<?php

// One key per logical order. Store it with your own record before calling.
$idempotencyKey = bin2hex(random_bytes(16));

$payload = json_encode([
    'channel' => 'facebook',
    'customer' => ['phone' => '01712345678', 'full_name' => 'Rafiqul Islam'],
    'items' => [
        ['sku' => 'TSHIRT-RED-M', 'quantity' => 2],
    ],
    'shipping_charge' => 120,
    'note' => 'Deliver after 6pm.',
]);

$ch = curl_init('https://api.salafems.com/ext/v1/orders');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SALAF_API_KEY'),
        'Idempotency-Key: ' . $idempotencyKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_TIMEOUT => 30,
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$response = json_decode($body, true);

if ($status >= 400) {
    throw new RuntimeException("{$response['error']['code']}: {$response['error']['message']}");
}

echo $response['number'] . ' ' . $response['total_amount'] . PHP_EOL;

# Retrying is just sending the SAME key again.
KEY="3f1a5c8e-0b2d-4f77-9a13-5e6c7d8f9a10"

send() {
  curl -sS -o body.json -w '%{http_code}' -D headers.txt \
    -X POST "https://api.salafems.com/ext/v1/orders" \
    -H "Authorization: Bearer $SALAF_API_KEY" \
    -H "Idempotency-Key: $KEY" \
    -H "Content-Type: application/json" \
    -d @order.json
}

STATUS=$(send)

# 409 means the first attempt is still running. Wait, then ask again —
# do NOT generate a new key, that would create a second order.
while [ "$STATUS" = "409" ]; do
  sleep 2
  STATUS=$(send)
done

# On a replay the body is byte-identical to the original response and this
# header is present:
grep -i '^idempotent-replayed' headers.txt

async function createOrderOnce(order, idempotencyKey, attempt = 0) {
  const response = await fetch("https://api.salafems.com/ext/v1/orders", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SALAF_API_KEY}`,
      "Idempotency-Key": idempotencyKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(order),
  });

  // 201 first time, 201 again on every replay — with the original body.
  if (response.ok) {
    return response.json();
  }

  const { error } = await response.json();

  // The original request is still in flight. Wait for it; never re-key.
  if (error.code === "IDEMPOTENCY_IN_FLIGHT" && attempt < 5) {
    await new Promise((resolve) => setTimeout(resolve, 2000));
    return createOrderOnce(order, idempotencyKey, attempt + 1);
  }

  // Same key, different body: a bug in YOUR code, not a transient failure.
  // Retrying cannot fix it — the key is already bound to another request.
  if (error.code === "IDEMPOTENCY_CONFLICT") {
    throw new Error(
      `Key ${idempotencyKey} was already used for a different order.`,
    );
  }

  throw new Error(`${error.code}: ${error.message} [${error.request_id}]`);
}

import os
import time

import requests

HEADERS = {"Authorization": f"Bearer {os.environ['SALAF_API_KEY']}"}


def create_order_once(order, idempotency_key, attempts=5):
    for _ in range(attempts):
        response = requests.post(
            "https://api.salafems.com/ext/v1/orders",
            json=order,
            headers={**HEADERS, "Idempotency-Key": idempotency_key},
            timeout=30,
        )

        if response.ok:
            # A replay returns the ORIGINAL response, marked as one.
            replayed = response.headers.get("Idempotent-Replayed") == "true"
            return response.json(), replayed

        error = response.json()["error"]

        if error["code"] == "IDEMPOTENCY_IN_FLIGHT":
            # The first attempt is still running. Wait — do not re-key.
            time.sleep(2)
            continue

        if error["code"] == "IDEMPOTENCY_CONFLICT":
            raise RuntimeError(
                f"Key {idempotency_key} was already used for a different order."
            )

        raise RuntimeError(f"{error['code']}: {error['message']}")

    raise RuntimeError("The original request is still in flight.")

<?php

function create_order_once(array $order, string $idempotencyKey, int $attempts = 5): array
{
    for ($attempt = 0; $attempt < $attempts; $attempt++) {
        $ch = curl_init('https://api.salafems.com/ext/v1/orders');
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . getenv('SALAF_API_KEY'),
                'Idempotency-Key: ' . $idempotencyKey,
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode($order),
            CURLOPT_TIMEOUT => 30,
        ]);

        $body = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        curl_close($ch);

        $response = json_decode($body, true);

        if ($status < 400) {
            return $response;
        }

        // Still running: wait for the original, never mint a new key.
        if ($response['error']['code'] === 'IDEMPOTENCY_IN_FLIGHT') {
            sleep(2);
            continue;
        }

        if ($response['error']['code'] === 'IDEMPOTENCY_CONFLICT') {
            throw new RuntimeException("Key {$idempotencyKey} was already used for a different order.");
        }

        throw new RuntimeException("{$response['error']['code']}: {$response['error']['message']}");
    }

    throw new RuntimeException('The original request is still in flight.');
}