KF
k-factu

Developer API

Integrate k-factu data into your own apps and automations using REST API tokens.

Get API TokenView Endpoints

REST API

Standard HTTP JSON API. Works with any language or tool.

Secure by design

Tokens are SHA-256 hashed. Only you see the raw token once, at creation.

Per-account tokens

Each token is scoped to your account. Revoke anytime from Settings.

Authentication

All API endpoints require a Bearer token in the Authorization header.

Step 1 — Create a token

Go to Settings → API Tokens.

Step 2 — Use the token

Include the token in every request:

Authorization: Bearer kf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Security: Tokens are shown only once. Store yours in a secure vault. If lost, revoke it and create a new one.

Rate Limits

API token requests are rate-limited to protect the service.

PlanRate limit
Autonomo / PYME / Gestoria100 req/min

Exceeded requests return 429 Too Many Requests. Retry after the Retry-After header value (seconds).

Endpoints

GET/api/invoices

Returns a paginated list of invoices for your account, ordered by issue date descending.

Query Parameters

pageintegerPage number (default: 1, 50 items per page)
statusstringFilter by status: draft, sent, paid, overdue, cancelled
dateFromstring (YYYY-MM-DD)Start date filter (inclusive)
dateTostring (YYYY-MM-DD)End date filter (inclusive)
searchstringFull-text search

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

Returns all clients in your account. Optionally filter by name, NIF, or email.

Query Parameters

searchstringFull-text search

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

Returns a paginated list of expenses. All amounts are in euro cents.

Query Parameters

pageintegerPage number (default: 1, 50 items per page)
dateFromstring (YYYY-MM-DD)Start date filter (inclusive)
dateTostring (YYYY-MM-DD)End date filter (inclusive)
deductiblebooleanFilter by deductibility: true or false
searchstringFull-text search

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
}

Money amounts

All monetary amounts are returned as integers in euro cents. Divide by 100 to get euros.

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

Error codes

HTTP StatusMeaning
200Success
400Bad request — invalid parameters or body
401Unauthorized — missing or invalid token
404Resource not found
429Rate limit exceeded
500Internal server error
GET/api/invoices/{id}

Returns a single invoice with all line items and client info.

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

Creates a new draft invoice. Amounts are server-calculated. `irpfRate` is in basis points (1500 = 15%). `quantity` and `unitPrice` are in euro cents.

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

Updates the status of an invoice. Valid transitions: draft → sent → paid. `paidAt` is required when setting status to `paid` (ISO 8601 date string).

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

Creates a new client. NIF/CIF/NIE is validated for Spanish clients (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

Creates a new expense entry. Amount is in euro cents. `categoryId` can be obtained from GET /api/expenses/categories (session-only for now).

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
}