KF
k-factu

Entwickler-API

Integrieren Sie k-factu-Daten in Ihre eigenen Apps und Automatisierungen mit REST-API-Tokens.

API-Token erstellenEndpoints anzeigen

REST API

Standard HTTP+JSON-API. Funktioniert mit jeder Sprache oder jedem Tool.

Sicher konzipiert

Tokens werden als SHA-256 gespeichert. Der rohe Token wird nur einmal bei der Erstellung angezeigt.

Tokens pro Konto

Jeder Token ist auf Ihr Konto beschrankt. Widerrufen Sie ihn jederzeit in den Einstellungen.

Authentifizierung

Alle API-Endpoints erfördern einen Bearer-Token im Authorization-Header.

Schritt 1 — Token erstellen

Gehen Sie zu Einstellungen → API Tokens.

Schritt 2 — Token verwenden

Geben Sie den Token in jeder Anfrage an:

Authorization: Bearer kf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Sicherheit: Tokens werden nur einmal angezeigt. Speichern Sie ihn sicher. Bei Verlust widerrufen und neu erstellen.

Ratenbegrenzungen

API-Token-Anfragen sind zum Schutz des Dienstes begrenzt.

PlanLimit
Autonomo / PYME / Gestoria100 req/min

Überschrittene Anfragen erhalten 429. Wiederholen Sie nach dem Wert des Retry-After-Headers (Sekunden).

Endpoints

GET/api/invoices

Gibt eine paginierte Liste von Rechnungen Ihres Kontos zurück, sortiert nach Ausstellungsdatum absteigend.

Query Parameters

pageintegerSeitennummer (Standard: 1, 50 Einträge pro Seite)
statusstringNach Status filtern: draft, sent, paid, overdue, cancelled
dateFromstring (YYYY-MM-DD)Startdatum-Filter (inklusiv)
dateTostring (YYYY-MM-DD)Enddatum-Filter (inklusiv)
searchstringVolltextsuche

Example Request

curl https://factu.krokanti.com/api/invoices \
  -H "Authorization: Bearer kf_your_token"

Example Response

{
  "items": [
    {
      "id": "uuid",
      "invoiceNumber": "2026-A-001",
      "issueDate": "2026-03-01",
      "dueDate": "2026-04-01",
      "clientName": "Acme SL",
      "status": "paid",
      "total": 121000,
      "subtotal": 100000,
      "ivaAmount": 21000,
      "irpfAmount": 0
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 50
}
GET/api/clients

Gibt alle Kunden Ihres Kontos zurück. Optional nach Name, NIF oder E-Mail filtern.

Query Parameters

searchstringVolltextsuche

Example Request

curl https://factu.krokanti.com/api/clients \
  -H "Authorization: Bearer kf_your_token"

Example Response

[
  {
    "id": "uuid",
    "name": "Acme SL",
    "nif": "A12345678",
    "email": "billing@acme.es",
    "address": "Calle Mayor 1",
    "city": "Madrid",
    "postalCode": "28001",
    "country": "ES"
  }
]
GET/api/expenses

Gibt eine paginierte Liste von Ausgaben zurück. Alle Beträge in Euro-Cent.

Query Parameters

pageintegerSeitennummer (Standard: 1, 50 Einträge pro Seite)
dateFromstring (YYYY-MM-DD)Startdatum-Filter (inklusiv)
dateTostring (YYYY-MM-DD)Enddatum-Filter (inklusiv)
deductiblebooleanNach Absetzbarkeit filtern: true oder false
searchstringVolltextsuche

Example Request

curl https://factu.krokanti.com/api/expenses \
  -H "Authorization: Bearer kf_your_token"

Example Response

{
  "items": [
    {
      "id": "uuid",
      "date": "2026-03-10",
      "description": "Cloud hosting",
      "amount": 4999,
      "isDeductible": true,
      "categoryName": "Software y tecnologia",
      "receiptUrl": null
    }
  ],
  "total": 18,
  "page": 1,
  "limit": 50
}

Geldbeträge

Alle Geldbeträge werden als ganze Zahlen in Euro-Cent zurückgegeben. Durch 100 dividieren für Euro.

// total: 121000 → EUR 1,210.00
const euros = amount / 100;

Fehlercodes

HTTP-StatusBedeutung
200Erfolgreich
400Fehlerhafte Anfrage — ungültige Parameter oder Inhalt
401Nicht autorisiert — fehlender oder ungültiger Token
404Ressource nicht gefunden
429Ratenbegrenzung überschritten
500Interner Serverfehler
GET/api/invoices/{id}

Gibt eine einzelne Rechnung mit allen Positionen und Kundendaten zurück.

Example Request

curl https://factu.krokanti.com/api/invoices/INVOICE_ID \
  -H "Authorization: Bearer kf_your_token"

Example Response

{
  "invoice": {
    "id": "uuid",
    "invoiceNumber": "2026-A-001",
    "issueDate": "2026-03-01",
    "dueDate": "2026-04-01",
    "status": "paid",
    "total": 121000
  },
  "lines": [
    { "description": "Consulting", "quantity": 100, "unitPrice": 100000, "amount": 100000 }
  ],
  "clientName": "Acme SL",
  "clientNif": "A12345678"
}
POST/api/invoices

Erstellt eine neue Entwurfsrechnung. Beträge werden serverseitig berechnet. `irpfRate` in Basispunkten. `quantity` und `unitPrice` in Euro-Cent.

Example Request

curl -X POST https://factu.krokanti.com/api/invoices \
  -H "Authorization: Bearer kf_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "CLIENT_UUID",
    "seriesId": "SERIES_UUID",
    "issueDate": "2026-03-13",
    "irpfRate": 1500,
    "applyIrpf": true,
    "lines": [
      {
        "description": "Consulting services",
        "quantity": 100,
        "unitPrice": 100000,
        "ivaType": "general"
      }
    ]
  }'

Example Response

{
  "id": "uuid",
  "invoiceNumber": "2026-A-042",
  "status": "draft",
  "total": 106500
}
PATCH/api/invoices/{id}/status

Aktualisiert den Status einer Rechnung. Gültige Übergange: draft → sent → paid. `paidAt` erforderlich beim Setzen auf paid.

Example Request

curl -X PATCH https://factu.krokanti.com/api/invoices/INVOICE_ID/status \
  -H "Authorization: Bearer kf_your_token" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid", "paidAt": "2026-03-13" }'

Example Response

{
  "id": "uuid",
  "invoiceNumber": "2026-A-001",
  "status": "paid",
  "paidAt": "2026-03-13T00:00:00.000Z"
}
POST/api/clients

Erstellt einen neuen Kunden. NIF/CIF/NIE wird für spanische Kunden validiert (country: ES).

Example Request

curl -X POST https://factu.krokanti.com/api/clients \
  -H "Authorization: Bearer kf_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme SL",
    "nif": "A12345678",
    "email": "billing@acme.es",
    "address": "Calle Mayor 1",
    "city": "Madrid",
    "postalCode": "28001",
    "country": "ES"
  }'

Example Response

{
  "id": "uuid",
  "name": "Acme SL",
  "nif": "A12345678",
  "email": "billing@acme.es"
}
POST/api/expenses

Erstellt einen neuen Ausgabeneintrag. Der Betrag ist in Euro-Cent.

Example Request

curl -X POST https://factu.krokanti.com/api/expenses \
  -H "Authorization: Bearer kf_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-03-13",
    "description": "Cloud hosting March",
    "amount": 4999,
    "categoryId": "CATEGORY_UUID",
    "isDeductible": true,
    "supplierName": "AWS"
  }'

Example Response

{
  "id": "uuid",
  "date": "2026-03-13",
  "description": "Cloud hosting March",
  "amount": 4999,
  "isDeductible": true
}