Една заявка. Фактура, PDF и имейл.

01 / Подготовка

Преди първата заявка

Подгответе фирмата веднъж. След това всяка заявка използва същите правила за номерация, данъци и счетоводство като издаването в приложението.

• Попълнете името, ЕИК, адреса и ДДС статуса на фирмата в Администрация.
• Добавете диапазон за номерата на фактурите. Изберете диапазон по подразбиране или подайте range_id в заявката.
• Добавете банкова сметка за банкови плащания. При повече от една сметка посочете основна или подайте bank_account_id.
• Членът, който разрешава интеграцията, трябва да има активен достъп до фирмата и право да издава документи.
• Клиентът трябва да има адрес за фактурата. Подгответе имейл на получателя или контакти, включени за получаване на документи.

02 / Сигурен достъп

Достъп и API ключове

Отворете Администрация → API ключове, създайте именуван ключ за тази интеграция и изберете член на същата фирма. Отметнете само нужните права:

sales:invoices:issue

Намира или създава клиента, издава фактурата и добавя имейла в опашката. Не позволява произволни промени на клиенти, анулиране или изтриване.

sales:invoices:read

Позволява преглед на статуса и изтегляне на PDF според видимостта на избрания член. Нужно е за примерите за проследяване по-долу.

legacy:access

Само за стария REST/MCP достъп и OAuth. Не е нужно за тази интеграция и не дава право за издаване на фактури.

Настройте API ключа

Копирайте ключа при създаването: показва се само веднъж. Пазете го в мениджър за тайни, а не в публичен код, адреси или съобщения. В примерите се използва променливата INVOICEHUB_API_KEY.

03 / Бърз старт

Първата ви фактура

POST/v1/sales/invoices

Запазете следния JSON във файл invoice.json. Заменете id на клиента и имейла с вашите данни. Ако още нямате id, заменете блока client с ЕИК или ДДС идентичността от следващия раздел.

{
  "client": {
    "id": 123
  },
  "invoice": {
    "payment_method": "bank",
    "language": "bg",
    "lines": [
      {
        "description": "Accounting services",
        "quantity": "1",
        "unit_price": "100.00",
        "vat_rate": "20.00"
      }
    ]
  },
  "delivery": {
    "mode": "explicit",
    "to_email": "[email protected]"
  }
}

Цените, количествата и процентите са десетични низове в кавички, не JSON числа или изрази. Номерът, общите суми, фирмата и издаващият член се определят от сървъра.

Заредете ключа безопасно в променливата и изпратете заявката. YOUR_API_KEY е заместител, не работещ ключ. Използвайте собствена уникална препратка за Idempotency-Key, например номер на поръчката.

export INVOICEHUB_API_KEY="YOUR_API_KEY"

curl --fail-with-body --request POST "https://web.invoicehub.work/v1/sales/invoices" \
  --header "Authorization: Bearer $INVOICEHUB_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-2026-0001" \
  --data-binary @invoice.json

Как изглежда успешният отговор

201 Created означава, че фактурата е издадена и имейлът е в опашката. Примерът е за фирма, регистрирана по ДДС, със ставка 20 процента. Реалните ставки и суми следват настройките на вашата фирма.

{
  "client": {
    "id": 123,
    "created": false,
    "name": "Client Ltd",
    "eik": "203078445",
    "vat": null
  },
  "invoice": {
    "id": 456,
    "kind": "invoice",
    "status": "issued",
    "number": "0000000123",
    "issue_date": "2026-10-10",
    "event_date": "2026-10-10",
    "due_date": null,
    "currency": "EUR",
    "subtotal": "100.00",
    "vat_total": "20.00",
    "total": "120.00",
    "pdf_url": "/v1/sales/invoices/456/pdf"
  },
  "delivery": [
    {
      "id": 789,
      "to_email": "[email protected]",
      "status": "pending"
    }
  ],
  "warnings": []
}

Запазете invoice.id и client.id. Заглавката Location сочи адреса за проследяване. Полето warnings показва приети предупреждения, например корекция на ДДС според статуса на фирмата.

04 / Данни за получателя

Клиенти и получатели

Съществуващ клиент или създаване по идентичност

Подайте client: {"id": 123}, ако имате id от предишен отговор. За първа интеграция или клиент без известен id подайте точно име и ЕИК или ДДС номер. Клиентът се търси само в текущата фирма и се създава, ако няма точен идентификаторен запис.

{
  "name": "Client Ltd",
  "eik": "203078445",
  "address": "Plovdiv, Bulgaria"
}

Името само по себе си не избира клиент. Адресът е задължителен при създаване; mol и vat са незадължителни. Запазените име, адрес и идентификатори не се презаписват от тази заявка. За клиенти без идентификатор използвайте предварително създаден запис и неговото id.

Еднократен имейл или контактите на клиента

delivery.mode = explicit изпраща до един подаден адрес. Това не създава постоянен контакт и не включва проследяване без вече записано съгласие. Вместо това можете да замените delivery с:

{
  "mode": "client_contacts"
}

client_contacts използва всички контакти с включено получаване на документи. Ако няма такива, заявката се отказва преди издаване. Не комбинирайте двата начина и не пропускайте delivery.

05 / След издаването

Доставка и повторни заявки

Издаването е завършено преди отговора, но имейлът се изпраща отделно. Проследявайте фактурата с правото за четене и id от отговора; 456 по-долу е примерен id.

curl --fail-with-body "https://web.invoicehub.work/v1/sales/invoices/456" \
  --header "Authorization: Bearer $INVOICEHUB_API_KEY"

pending / sending

Имейлът е в опашката или се изпраща. Не издавайте нова фактура, докато чакате.

sent

Доставчикът на имейл е приел съобщението. Това още не потвърждава доставка до получателя.

delivered

Получаващият пощенски сървър е приел имейла. Това не означава, че човекът го е прочел.

failed / bounced / complained

Изпращането е неуспешно, адресът е отхвърлил имейла или е получен сигнал за спам. Проверете документа и получателя в приложението.

Изтеглете издадения PDF

curl --fail-with-body "https://web.invoicehub.work/v1/sales/invoices/456/pdf" \
  --header "Authorization: Bearer $INVOICEHUB_API_KEY" \
  --output invoice-456.pdf

Правилото за повторение

• Същият ключ и същите данни връщат оригиналния успешен отговор с Idempotency-Replayed: true, без второ издаване или нов запис за имейл.
• Различни данни със същия вече използван ключ връщат 409 idempotency_conflict. Проверете коя операция е била изпратена, вместо да заобикаляте отказа.
• За текущия статус използвайте GET, не повторения POST. Повтореният успешен POST запазва оригиналния отговор, включително първоначалния статус на имейла.
• При 409 request_in_progress, 429 или 503 изчакайте Retry-After и повторете със същия ключ и тяло. При поправима валидация без издаден документ коригирайте данните преди повторение.

06 / Ако нещо не е наред

Грешки и лимити

Отказът съдържа code, detail и fields. Запазете кода и препратката на операцията за диагностика, но никога не изпращайте API ключа на поддръжката.

401

Липсва валиден активен API ключ. Проверете Bearer заглавката и дали ключът не е сменен или отнет.

403

Липсва нужното право на ключа или членът вече няма необходимия достъп. Проверете и двете настройки в Администрация.

404

Клиентът или фактурата не е достъпен за тази фирма и този член. Не използвайте id от друга фирма.

409

Проверете code: конфликт на идентичности, нужно потвърждение на регистъра, различно тяло за вече използван ключ или операция в ход. Повтаряйте автоматично само request_in_progress.

422

Поправете полетата във fields. Чести причини са липсващ адрес, неподходяща ДДС ставка, банкова сметка, използван диапазон, затворен период или непознато поле.

429 / 503

Достигнат лимит или временно недостъпна инфраструктура. Изчакайте Retry-After. Ако отговорът е изгубен, повторете същата операция безопасно със същия ключ.

Смяна или отнемане на ключ

Сменете избрания ключ в Администрация, запишете новия в мениджъра за тайни и обновете интеграцията. Старият ключ спира веднага. Можете да повторите вече успешна операция с новия ключ и същите данни, ако членът още вижда фактурата.

Ключ само за фактури не засяга другите интеграции. Отнемане на legacy:access, смяна или отнемане на такъв стар ключ анулира OAuth токените на фирмата. Проверете правата преди действието.