Обновление API: новые методы версионирования

URL-префикс версии

Версия живёт в пути: /v3/invoices. Никаких скрытых переключателей — видно сразу, какой контракт вы вызываете.

Семантические теги

Ответы несут X-Invoicx-Api-Version: 3.2.1. Пэтчи добавляются без изменений контракта, мажор — только отдельным релизом.

Замороженные контракты

Поля, которые вы используете, не удаляются и не переименовываются внутри мажорной версии. Изменения — только в новой мажорке.

Явный sunset

Каждая версия получает дату отключения. Для v2 это 30.09.2025 — у вас есть время на спокойную миграцию.

Предсказуемые ошибки

Единый формат error с кодом, trace_id и ссылками на документацию. Никаких «500 без причины».

Идемпотентность

Все мутации принимают Idempotency-Key. Повторный вызов не создаст дубликат счёта — даже при ретраях.

Генерация и выставление

import requests

API = "https://api.invoicx.io/v3"
H = {
    "Authorization": "Bearer ix_live_9f2a…",
    "Idempotency-Key": "inv-gen-2025-03-12-001",
}

# Генерация по правилу выставления
gen = requests.post(
    f"{API}/invoices",
    headers=H,
    json={"rule_id": "rule_recurring_04", "due_in_days": 14},
)
gen.raise_for_status()
invoice_id = gen.json()["id"]

# Финализация сумм
requests.post(f"{API}/invoices/{invoice_id}:generate", headers=H)

# Выставление контрагенту
issued = requests.post(f"{API}/invoices/{invoice_id}:issue", headers=H)
print(issued.json()["payment_state"])  # "issued"
        

Генерация и выставление

const API = "https://api.invoicx.io/v3";
const H = {
  "Authorization": "Bearer ix_live_9f2a…",
  "Idempotency-Key": "inv-gen-2025-03-12-001",
};

async function issueFromRule(ruleId) {
  const gen = await fetch(`${API}/invoices`, {
    method: "POST",
    headers: H,
    body: JSON.stringify({ rule_id: ruleId, due_in_days: 14 }),
  });
  if (!gen.ok) throw new Error("gen " + gen.status);
  const { id } = await gen.json();

  await fetch(`${API}/invoices/${id}:generate`, { method: "POST", headers: H });
  const issued = await fetch(`${API}/invoices/${id}:issue`, {
    method: "POST",
    headers: H,
  });
  const data = await issued.json();
  console.log(data.payment_state); // "issued"
}

issueFromRule("rule_recurring_04");