KF
k-factu

API para desenvolvedores

Integre dados do k-factu nas suas apps e automatizações usando tokens de API REST.

Obter tokenVer endpoints

API REST

API HTTP+JSON padrão. Funciona com qualquer linguagem ou ferramenta.

Seguro por concepcao

Os tokens sao armazenados como SHA-256. O token bruto só e mostrado uma vez, na criação.

Tokens por conta

Cada token e limitado a sua conta. Revogue-o a qualquer momento nas Configurações.

Autenticação

Todos os endpoints requerem um Bearer token no header Authorization.

Passo 1 — Criar um token

Va para Configurações → API Tokens.

Passo 2 — Usar o token

Inclua o token em cada requisicao:

Authorization: Bearer kf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Segurança: Os tokens sao exibidos apenas uma vez. Guarde-o em local seguro. Se perdido, revogue e crie um novo.

Limites de taxa

Requisicoes com token sao limitadas para proteger o serviço.

PlanoLimite
Autonomo / PYME / Gestoria100 req/min

Requisicoes que ultrapassem o limite retornam 429. Tente novamente após o valor do header Retry-After (segundos).

Endpoints

GET/api/invoices

Retorna uma lista páginada de faturas da sua conta, ordenadas por data de emissão decrescente.

Query Parameters

pageintegerNúmero da página (padrão: 1, 50 itens por página)
statusstringFiltrar por status: draft, sent, paid, overdue, cancelled
dateFromstring (YYYY-MM-DD)Data início (inclusiva)
dateTostring (YYYY-MM-DD)Data fim (inclusiva)
searchstringPesquisa textual

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

Retorna todos os clientes da sua conta. Opcionalmente filtre por nome, NIF ou email.

Query Parameters

searchstringPesquisa textual

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

Retorna uma lista páginada de despesas. Todos os valores estão em centimos de euro.

Query Parameters

pageintegerNúmero da página (padrão: 1, 50 itens por página)
dateFromstring (YYYY-MM-DD)Data início (inclusiva)
dateTostring (YYYY-MM-DD)Data fim (inclusiva)
deductiblebooleanFiltrar por dedutibilidade: true ou false
searchstringPesquisa textual

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
}

Valores monetários

Todos os valores monetários sao retornados como inteiros em centimos de euro. Divida por 100 para obter euros.

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

Códigos de erro

Status HTTPSignificado
200Sucesso
400Requisicao incorreta — parametros ou corpo inválidos
401Não autorizado — token ausente ou inválido
404Recurso não encontrado
429Limite de taxa excedido
500Erro interno do servidor
GET/api/invoices/{id}

Retorna uma fatura com todas as linhas e dados do 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

Cria uma nova fatura em rascunho. Os valores sao calculados no servidor. `irpfRate` em pontos base. `quantity` e `unitPrice` em 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

Atualiza o status de uma fatura. Transicoes válidas: draft → sent → paid. `paidAt` obrigatório ao marcar como paga.

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

Cria um novo cliente. NIF/CIF/NIE e válidado para clientes espanhois (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

Cria um novo lançamento de despesa. O valor está em 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
}