Faktero API dokumentácia

Faktero REST API umožňuje plne automatizovať fakturáciu — vytvárať odberateľov, vystavovať faktúry, sťahovať PDF, posielať e-maily a prijímať webhooky o udalostiach. Všetky odpovede sú v JSON formáte (UTF-8).

2. Autentifikácia

Každú požiadavku autentifikujte hlavičkou Authorization s Bearer API kľúčom. Kľúče sú viazané na konkrétnu firmu a oprávnenia.

Authorization: Bearer fk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Kľúč nikdy nezdieľajte ani neukladajte do verejných repozitárov. Stratený kľúč okamžite revokujte v sekcii API kľúče.

3. Test a live režim

Faktero rozlišuje dva typy kľúčov podľa prefixu:

• fk_test_… — testovací režim. Faktúry sa neodosielajú reálne, e-maily idú do sandboxu.
• fk_live_… — produkčný režim. Akcie sú reálne a fakturačné údaje sa zapisujú do ostrých dokumentov.

4. Chyby

Všetky chybové odpovede majú jednotný formát:

{
  "error": {
    "code": "validation_error",
    "message": "Human readable message",
    "details": {}
  }
}

5. Odberatelia

• POST/api/v1/customers— Vytvorenie odberateľa
• GET/api/v1/customers— Zoznam odberateľov
• GET/api/v1/customers/{id}— Detail odberateľa
• PUT/api/v1/customers/{id}— Úprava odberateľa

6. Faktúry

• POST/api/v1/invoices— Vystavenie faktúry
• GET/api/v1/invoices— Zoznam faktúr
• GET/api/v1/invoices/{id}— Detail faktúry
• PUT/api/v1/invoices/{id}— Úprava (len drafty)
• GET/api/v1/invoices/{id}/pdf— Signed URL na PDF
• POST/api/v1/invoices/{id}/send— Odoslanie e-mailom
• POST/api/v1/invoices/{id}/mark-paid— Označenie ako uhradené
• POST/api/v1/invoices/{id}/cancel— Storno faktúry

7. Cenové ponuky

• POST/api/v1/quotes— Vytvorenie ponuky
• GET/api/v1/quotes— Zoznam ponúk
• GET/api/v1/quotes/{id}— Detail ponuky
• PUT/api/v1/quotes/{id}— Úprava ponuky
• POST/api/v1/quotes/{id}/convert— Konverzia na faktúru

8. Opakované faktúry

• POST/api/v1/recurring-invoices— Vytvorenie šablóny
• GET/api/v1/recurring-invoices— Zoznam šablón
• GET/api/v1/recurring-invoices/{id}— Detail šablóny
• PUT/api/v1/recurring-invoices/{id}— Úprava šablóny

9. Náklady

10. Webhooky

Webhooky vás v reálnom čase informujú o udalostiach vo Faktero. Endpoint nastavíte v sekcii Webhooky vo vašom účte, kde získate aj signing secret.

Udalosti

• invoice.created
• invoice.sent
• invoice.paid
• invoice.cancelled
• customer.created
• quote.created
• quote.sent
• quote.converted

Overovanie podpisu

Každá požiadavka má hlavičku X-Faktero-Signature obsahujúcu HMAC SHA-256 podpis tela požiadavky vytvorený pomocou vášho signing secret.

import crypto from "crypto";

function verifyFaktero(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected),
  );
}

Opakovanie pri zlyhaní

Ak váš endpoint nevráti 2xx do 10 sekúnd, Faktero pokus zopakuje s exponenciálnym odstupom (1 min, 5 min, 30 min, 2 h, 12 h) — celkovo max. 5 pokusov. Všetky pokusy a ich stavy nájdete v sekcii Webhooky → Logy.

11. Príklady kódu

Vytvorenie odberateľa

curl -X POST https://faktero.sk/api/v1/customers \
  -H "Authorization: Bearer fk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme s.r.o.",
    "ico": "12345678",
    "ic_dph": "SK2020123456",
    "street": "Hlavná 1",
    "city": "Bratislava",
    "zip": "81101",
    "country": "SK",
    "email": "fakturacia@acme.sk"
  }'

const res = await fetch("https://faktero.sk/api/v1/customers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fk_live_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Acme s.r.o.",
    ico: "12345678",
    email: "fakturacia@acme.sk",
  }),
});
const customer = await res.json();

<?php
$ch = curl_init("https://faktero.sk/api/v1/customers");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer fk_live_xxx",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "name" => "Acme s.r.o.",
    "ico" => "12345678",
    "email" => "fakturacia@acme.sk",
  ]),
]);
$customer = json_decode(curl_exec($ch), true);

Vystavenie faktúry

curl -X POST https://faktero.sk/api/v1/invoices \
  -H "Authorization: Bearer fk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_123",
    "issue_date": "2026-06-12",
    "due_date": "2026-06-26",
    "currency": "EUR",
    "items": [
      { "name": "Konzultácia", "quantity": 4, "unit": "hod",
        "unit_price": 75, "vat_rate": 23 }
    ]
  }'

Stiahnutie PDF

const res = await fetch(
  "https://faktero.sk/api/v1/invoices/inv_123/pdf",
  { headers: { Authorization: "Bearer fk_live_xxx" } }
);
const { signed_url } = await res.json();
// signed_url platí 5 minút — stiahnite alebo presmerujte používateľa

Odoslanie faktúry e-mailom

curl -X POST https://faktero.sk/api/v1/invoices/inv_123/send \
  -H "Authorization: Bearer fk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "recipient_email": "klient@example.com" }'

Označiť faktúru ako uhradenú

curl -X POST https://faktero.sk/api/v1/invoices/inv_123/mark-paid \
  -H "Authorization: Bearer fk_live_xxx"

Prijatie webhooku (PHP)

<?php
$secret = getenv("FAKTERO_WEBHOOK_SECRET");
$payload = file_get_contents("php://input");
$sig = $_SERVER["HTTP_X_FAKTERO_SIGNATURE"] ?? "";
$expected = hash_hmac("sha256", $payload, $secret);

if (!hash_equals($expected, $sig)) {
  http_response_code(401);
  exit;
}

$event = json_decode($payload, true);
// $event["type"] === "invoice.paid" …
http_response_code(200);

12. Stavové kódy

13. Rate limity

14. Pre vývojárov