KF
k-factu

API para desarrolladores

Integra los datos de k-factu en tus propias apps y automatizaciones usando tokens de API REST.

Obtener tokenVer endpoints

API REST

API HTTP+JSON estandar. Funciona con cualquier lenguaje o herramienta.

Seguro por diseno

Los tokens se almacenan como SHA-256. Solo ves el token en crudo una vez, al crearlo.

Tokens por cuenta

Cada token esta limitado a tu cuenta. Revocalo cuando quieras desde Ajustes.

Autenticacion

Todos los endpoints requieren un Bearer token en el header Authorization.

Paso 1 — Crear un token

Ve a Ajustes → API Tokens.

Paso 2 — Usar el token

Incluye el token en cada peticion:

Authorization: Bearer kf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Seguridad: Los tokens se muestran solo una vez. Guardalo en un lugar seguro. Si lo pierdes, revocalo y crea uno nuevo.

Limites de velocidad

Las peticiones con token estan limitadas para proteger el servicio.

PlanLimite
Autonomo / PYME / Gestoria100 req/min

Las peticiones que superen el limite devuelven 429. Reintenta despues del valor del header Retry-After (segundos).

Endpoints

GET/api/invoices

Devuelve una lista paginada de facturas de tu cuenta, ordenadas por fecha de emision descendente.

Query Parameters

pageintegerNumero de pagina (defecto: 1, 50 elementos por pagina)
statusstringFiltrar por estado: draft, sent, paid, overdue, cancelled
dateFromstring (YYYY-MM-DD)Fecha inicio (inclusiva)
dateTostring (YYYY-MM-DD)Fecha fin (inclusiva)
searchstringBusqueda de texto

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

Devuelve todos los clientes de tu cuenta. Filtra opcionalmente por nombre, NIF o email.

Query Parameters

searchstringBusqueda de texto

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

Devuelve una lista paginada de gastos. Todos los importes estan en centimos de euro.

Query Parameters

pageintegerNumero de pagina (defecto: 1, 50 elementos por pagina)
dateFromstring (YYYY-MM-DD)Fecha inicio (inclusiva)
dateTostring (YYYY-MM-DD)Fecha fin (inclusiva)
deductiblebooleanFiltrar por deducibilidad: true o false
searchstringBusqueda de texto

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
}

Importes monetarios

Todos los importes monetarios se devuelven como enteros en centimos de euro. Divide entre 100 para obtener euros.

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

Codigos de error

Estado HTTPSignificado
200Exito
400Peticion incorrecta — parametros o cuerpo invalidos
401No autorizado — token faltante o invalido
404Recurso no encontrado
429Limite de velocidad superado
500Error interno del servidor
GET/api/invoices/{id}

Devuelve una factura con todas las lineas y datos del cliente.

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

Crea una nueva factura en borrador. Los importes se calculan en servidor. `irpfRate` en puntos basicos (1500 = 15%). `quantity` y `unitPrice` en centimos.

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

Actualiza el estado de una factura. Transiciones validas: draft → sent → paid. `paidAt` requerido al marcar como pagada.

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

Crea un nuevo cliente. NIF/CIF/NIE se valida para clientes espanoles (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

Crea un nuevo gasto. El importe esta en centimos de euro.

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
}