Fakturace API

Integrace fakturačního systému s vašimi aplikacemi. Vytvářejte faktury, spravujte klienty a mnohem více - vše programově přes REST API.

Začít API Reference 
curl -X GET \
  https://api.fakturace.site/v1/invoices \
  -H 'Authorization: Bearer API_KLIC'

Úvod

Vítejte v dokumentaci Fakturace API. Toto API umožňuje integraci vašich aplikací s fakturačním systémem.

Fakturace API je organizováno podle principů REST. Naše API má předvídatelné URL založené na zdrojích, přijímá požadavky ve formátu JSON, vrací odpovědi v JSON a používá standardní HTTP stavové kódy, autentizaci a HTTP metody.

Základní URL: https://api.fakturace.site/v1
Všechny API požadavky musí být provedeny přes HTTPS. Požadavky přes HTTP budou zamítnuty.

Integrace s e-shopy a online platby

Fakturace API nabízí snadnou integraci s e-shopy a online službami prostřednictvím veřejných odkazů na faktury a plateb přes PayPal.

Při vytvoření faktury s platební metodou PayPal můžete pomocí endpointu /invoices/{id}/setpublic vygenerovat veřejný odkaz, který lze zákazníkovi poslat e-mailem nebo zobrazit přímo v e-shopu. Zákazník může fakturu zaplatit online přes PayPal, aniž by musel mít účet ve Fakturaci.

Nové funkce: API nyní vrací přímý odkaz pro platbu PayPal (payment_url), který můžete použít pro přesměrování zákazníka přímo na platební stránku PayPal. Můžete také specifikovat vlastní návratovou URL (return_url), kam bude zákazník přesměrován po úspěšné platbě.

Typický scénář použití v e-shopu:

  1. Zákazník vytvoří objednávku v e-shopu
  2. Váš systém vytvoří fakturu pomocí POST /invoices s payment_method: "paypal"
  3. Následně nastaví fakturu jako veřejnou pomocí POST /invoices/{id}/setpublic a předá return_url vašeho e-shopu
  4. Z odpovědi získáte odkaz payment_url, který přesměruje zákazníka přímo na PayPal platbu
  5. Po zaplacení se faktura automaticky označí jako zaplacená a zákazník je přesměrován na vaši return_url

Autentizace

Fakturace API používá API klíče pro autentizaci požadavků. Můžete zobrazit a spravovat své API klíče v nastavení účtu Fakturace.

Autentizace k API je prováděna pomocí HTTP Bearer Authentication. API klíč se předává v hlavičce požadavku. 

curl -X GET \
  https://api.fakturace.site/v1/invoices \
  -H 'Authorization: Bearer VAS_API_KLIC'

API Reference

Faktury

GET /v1/invoices

Vrátí seznam faktur.

Parametry dotazu
Parametr Typ Popis
limit integer Maximální počet faktur k vrácení. Výchozí je 10, maximum je 100.
offset integer Počet faktur k přeskočení. Výchozí je 0.
status string Filtrovat podle stavu (paid, unpaid, overdue)
Příklad požadavku
curl -X GET \
  'https://api.fakturace.site/v1/invoices?limit=5&status=unpaid' \
  -H 'Authorization: Bearer VAS_API_KLIC'
Příklad odpovědi
{
  "success": true,
  "data": {
    "invoices": [
      {
        "id": 123,
        "invoice_number": "FAK-2023-0001",
        "client_id": 456,
        "client_name": "ACME Corp",
        "issue_date": "2023-06-15",
        "due_date": "2023-06-30",
        "total_amount": 1250.00,
        "currency": "CZK",
        "status": "unpaid"
      },
      // Více faktur...
    ],
    "total": 15,
    "limit": 5,
    "offset": 0
  },
  "error": null
}
POST /v1/invoices

Vytvoří novou fakturu.

Tělo požadavku
{
  "client_id": 456,
  "issue_date": "2023-06-15",
  "due_date": "2023-06-30",
  "invoice_type": "regular",
  "payment_method": "bank_transfer",
  "currency": "CZK",
  "items": [
    {
      "name": "Webové služby",
      "quantity": 1,
      "unit_price": 10000,
      "vat_rate": 21
    }
  ],
  "note": "Děkujeme za spolupráci"
}
Dostupné platební metody (payment_method): bank_transfer, cash, card, paypal. Pro vytvoření faktury s možností platby přes PayPal použijte hodnotu "paypal" a následně endpoint /setpublic.
Příklad odpovědi
{
  "success": true,
  "data": {
    "invoice_id": 124,
    "invoice_number": "FAK-2023-0002",
    "message": "Faktura byla úspěšně vytvořena"
  },
  "error": null
}
POST /v1/invoices/{id}/setpublic

Nastaví fakturu jako veřejnou a vygeneruje veřejný odkaz pro platbu PayPalem. Funguje pouze pro faktury s platební metodou PayPal.

Tento endpoint je ideální pro e-shopy nebo online služby, kde chcete umožnit zákazníkům platit faktury online přes PayPal.
Parametry cesty
Parametr Typ Popis
id integer ID faktury
Příklad požadavku
curl -X POST \
  https://api.fakturace.site/v1/invoices/102/setpublic \
  -H 'Authorization: Bearer VAS_API_KLIC'
Příklad odpovědi
{
  "success": true,
  "data": {
    "invoice_id": 102,
    "is_public": true,
    "public_token": "7e5c8aaf3414c9b535dd62a078df408241306bf3f67b2628079e42d0e482c94",
    "public_url": "https://cab.fakturace.site/public-invoice?token=7e5c8aaf3414c9b535dd62a078df408241306bf3f67b2628079e42d0e482c94",
    "return_url": "https://example.com/thank-you",
    "payment_method": "paypal",
    "paypal_available": true,
    "payment_url": "https://www.sandbox.paypal.com/checkoutnow?token=6W971358GJ269693H",
    "message": "Invoice set to public successfully"
  },
  "error": null
}
Parametry těla požadavku
Parametr Typ Popis
return_url string URL, na kterou bude zákazník přesměrován po úspěšné platbě. Volitelné.
Příklad požadavku s návratovou URL
curl -X POST \
  https://api.fakturace.site/v1/invoices/102/setpublic \
  -H 'Authorization: Bearer VAS_API_KLIC' \
  -H 'Content-Type: application/json' \
  -d '{"return_url": "https://example.com/thank-you"}'
Možné chyby
Kód Popis
400 Public link is available only for invoices with PayPal payment method
400 PayPal is not configured for this user
404 Invoice not found
GET /v1/invoices/{id}

Získá detail faktury včetně veřejného odkazu (pokud je faktura veřejná).

Parametry cesty
Parametr Typ Popis
id integer ID faktury
Příklad požadavku
curl -X GET \
  https://api.fakturace.site/v1/invoices/102 \
  -H 'Authorization: Bearer VAS_API_KLIC'
Příklad odpovědi
{
  "success": true,
  "data": {
    "id": 102,
    "invoice_number": "FAK202503-0001",
    "invoice_type": "proforma",
    "client": {
      "id": 1,
      "name": "ACME Corp",
      "ico": "12345678",
      "dic": "CZ12345678",
      "address": "Testovací 123, Praha",
      "email": "client@example.com"
    },
    "company": {
      "id": 1,
      "name": "Má Firma",
      "ico": "87654321",
      "dic": "CZ87654321",
      "address": "Firemní 456, Praha",
      "bank_account": "1234567890/0800"
    },
    "dates": {
      "issue_date": "2025-05-01",
      "due_date": "2025-05-15"
    },
    "payment": {
      "method": "paypal",
      "status": "unpaid",
      "variabilni_symbol": "2025030001"
    },
    "amounts": {
      "total_without_vat": 5000,
      "total_vat": 1050,
      "total_with_vat": 6050,
      "currency": "CZK"
    },
    "note": "",
    "items": [
      {
        "id": 144,
        "name": "Webové služby",
        "quantity": 1,
        "unit_price": 5000,
        "vat_rate": 21,
        "total_without_vat": 5000,
        "vat_amount": 1050,
        "total_with_vat": 6050,
        "currency": "CZK"
      }
    ],
    "public_access": {
      "is_public": true,
      "public_token": "7e5c8aaf3414c9b535dd62a078df408241306bf3f67b2628079e42d0e482c94",
      "public_url": "https://cab.fakturace.site/public-invoice?token=7e5c8aaf3414c9b535dd62a078df408241306bf3f67b2628079e42d0e482c94",
      "return_url": "https://example.com/thank-you",
      "paypal_available": true,
      "payment_url": "https://www.sandbox.paypal.com/checkoutnow?token=6W971358GJ269693H"
    }
  },
  "error": null
}
GET /v1/invoices/{id}/pdf

Získá PDF verzi faktury.

Parametry cesty
Parametr Typ Popis
id integer ID faktury
Parametry dotazu
Parametr Typ Popis
template string Šablona PDF (default, modern, classic). Výchozí je "default".
color string Barevné téma pro moderní šablonu (blue, green, red, yellow). Výchozí je "blue".

Klienti

GET /v1/clients

Vrátí seznam vašich klientů.

POST /v1/clients

Vytvoří nového klienta.

Uživatelský profil

GET /v1/users/profile

Získá profil autentizovaného uživatele.

Příklad odpovědi
{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "username": "exider",
      "email": "user@example.com",
      "role": "admin",
      "created_at": "2024-03-27 18:46:04"
    },
    "subscription": {
      "plan_name": "VIP pro firmy",
      "plan_code": "vip",
      "status": "active",
      "start_date": "2024-03-28",
      "end_date": "2025-03-28",
      "max_companies": 5,
      "used_companies": 1
    },
    "stats": {
      "total_invoices": 10,
      "paid_invoices": 8,
      "unpaid_invoices": 2,
      "total_amount": 25000,
      "total_clients": 5
    },
    "companies": {
      "total": 1,
      "remaining": 4
    }
  },
  "error": null
}

Chyby a řešení

Fakturace API používá standardní HTTP stavové kódy pro indikaci úspěchu nebo selhání API požadavku.

Kód Popis
200 OK - Požadavek byl úspěšný.
201 Created - Zdroj byl úspěšně vytvořen.
400 Bad Request - Požadavek byl neplatný.
401 Unauthorized - Autentizace selhala nebo uživatel nemá oprávnění.
404 Not Found - Požadovaný zdroj neexistuje.
429 Too Many Requests - Požadavek byl omezen z důvodu překročení limitu.
500 Server Error - Něco se pokazilo na naší straně.
Formát chybové odpovědi
{
  "success": false,
  "data": null,
  "error": {
    "code": 404,
    "message": "Faktura nebyla nalezena"
  }
}

Limity požadavků

Fakturace API má limity pro ochranu proti zneužití a zajištění stabilního prostředí pro všechny uživatele.

  • Free účty: 60 požadavků za minutu
  • Standard účty: 120 požadavků za minutu
  • Premium účty: 300 požadavků za minutu

Každá API odpověď obsahuje následující hlavičky:

  • X-RateLimit-Limit: Maximální počet povolených požadavků za minutu
  • X-RateLimit-Remaining: Počet zbývajících požadavků v aktuální minutě
  • X-RateLimit-Reset: Čas, kdy se aktuální limit resetuje