Kacinka API

Semantica: Autentica un utente con credenziali email/password e stabilisce una sessione sicura tramite JWT cookies.

Tecnica: Validazione bcrypt della password, generazione coppia JWT (access_token 15min HS256 + refresh_token 7gg), impostazione cookie HttpOnly Secure SameSite=None su dominio .kacinka.it. CSRF token restituito nel body per double-submit pattern.

curl -X POST https://auth.kacinka.it/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "mario.rossi@example.com",
    "password": "Password123!"
  }'

const response = await fetch('https://auth.kacinka.it/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include', // ← Fondamentale per i cookie
  body: JSON.stringify({
    email: 'mario.rossi@example.com',
    password: 'Password123!'
  })
});

const data = await response.json();
const csrfToken = data.csrf_token;
// Salva csrfToken per le richieste successive

$ch = curl_init('https://auth.kacinka.it/login');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_COOKIEJAR => '/tmp/kacinka_cookies.txt',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'email' => 'mario.rossi@example.com',
        'password' => 'Password123!'
    ])
]);
$response = json_decode(curl_exec($ch), true);
$csrfToken = $response['csrf_token'];
curl_close($ch);

import requests

session = requests.Session()
response = session.post('https://auth.kacinka.it/login', json={
    'email': 'mario.rossi@example.com',
    'password': 'Password123!'
})
data = response.json()
csrf_token = data['csrf_token']
# La sessione mantiene i cookie automaticamente

{
  "status": "success",
  "data": {
    "user": {
      "id": 1,
      "email": "mario.rossi@example.com",
      "name": "Mario Rossi",
      "role": "user",
      "plan": "starter",
      "email_verified": true,
      "created_at": "2025-01-15T10:30:00Z"
    }
  },
  "csrf_token": "a1b2c3d4e5f6..."
}

Semantica: Crea un nuovo account utente sulla piattaforma Kacinka. Dopo la registrazione l'utente riceve un'email di verifica.

Tecnica: Validazione unicità email, hashing bcrypt (cost 12), inserimento in auth_users, invio email verifica via PHPMailer SMTP, piano Free assegnato di default.

curl -X POST https://auth.kacinka.it/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "nuovo.utente@example.com",
    "password": "SecurePass456!",
    "password_confirm": "SecurePass456!",
    "name": "Marco Bianchi",
    "terms_accepted": true
  }'

Semantica: Rinnova l'access_token scaduto usando il refresh_token valido presente nei cookie.

Tecnica: Decodifica JWT refresh_token dal cookie, verifica validità e scadenza, genera nuovo access_token (15min) e nuovo CSRF token. Il refresh_token rimane invariato fino alla sua scadenza naturale (7 giorni).

curl -X POST https://auth.kacinka.it/refresh \
  -b cookies.txt -c cookies.txt \
  -H "Content-Type: application/json" -d '{}'

Semantica: Termina la sessione corrente dell'utente.

Tecnica: Invalida i cookie JWT impostando Max-Age=0, rimuove la sessione dal database.

curl -X POST https://auth.kacinka.it/logout \
  -b cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" -d '{}'

Semantica: Invia un'email con link di reset password all'indirizzo specificato.

Tecnica: Genera token crypto 64 byte, salva hash SHA-256 in DB con TTL 1h, invia email via PHPMailer. Per sicurezza anti-enumeration, risposta sempre 200.

curl -X POST https://auth.kacinka.it/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "mario.rossi@example.com" }'

Semantica: Usa il token ricevuto via email per impostare una nuova password.

Tecnica: Verifica hash SHA-256 del token, controlla TTL, aggiorna password con bcrypt cost 12, invalida tutte le sessioni attive dell'utente.

curl -X POST https://auth.kacinka.it/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abc123def456...",
    "password": "NuovaPassword789!",
    "password_confirm": "NuovaPassword789!"
  }'

Semantica: Recupera il profilo completo dell'utente dalla sessione corrente.

Tecnica: Decodifica JWT dall'access_token cookie, query su auth_users + join piano abbonamento. Include stato verifica email/telefono e configurazione 2FA.

curl https://auth.kacinka.it/me \
  -b cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"

const res = await fetch('https://auth.kacinka.it/me', {
  credentials: 'include',
  headers: { 'X-CSRF-Token': csrfToken }
});
const { data } = await res.json();

{
  "data": {
    "id": 1, "email": "mario.rossi@example.com",
    "name": "Mario Rossi", "role": "user", "plan": "starter",
    "email_verified": true, "phone_verified": false,
    "two_factor_enabled": false,
    "company": "Rossi Digital SRL",
    "timezone": "Europe/Rome", "language": "it",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Semantica: Modifica i dati personali del profilo utente.

Tecnica: Partial update — solo i campi inclusi nel body vengono aggiornati. Sanitizzazione input, validazione timezone IANA, language ISO 639-1.

curl -X PUT https://auth.kacinka.it/me/profile \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -d '{
    "name": "Mario Rossi",
    "company": "Rossi Digital SRL",
    "timezone": "Europe/Rome",
    "language": "it"
  }'

Semantica: Modifica la password dell'account. Invalida tutte le sessioni attive tranne quella corrente.

Tecnica: Verifica current_password con bcrypt, hash nuova password, DELETE sessioni ≠ current, log in audit.

curl -X PUT https://auth.kacinka.it/me/password \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -d '{
    "current_password": "VecchiaPassword123!",
    "new_password": "NuovaPassword456!",
    "new_password_confirm": "NuovaPassword456!"
  }'

Semantica: Elenco paginato di tutti i progetti dell'utente con statistiche aggregate.

Tecnica: Paginazione cursor-based. Query params: ?page=1&per_page=25&status=active&search=keyword. Include count tasks/deals/members per progetto.

Semantica: Dati completi del progetto con tutte le statistiche aggregate.

Tecnica: JOIN su tasks (count per status), deals (count + sum value), team_members. Verifica ownership o membership.

Semantica: Modifica i dati del progetto. Partial update — solo i campi inclusi vengono modificati.

Semantica: Elimina il progetto e tutti i dati associati (tasks, deals, file). Azione irreversibile.

Tecnica: CASCADE DELETE su foreign keys. Solo l'owner può eseguire. Trigger webhook project.deleted.

Semantica: Importa più contatti in una sola richiesta, ideale per migrazione da altri CRM.

Tecnica: Batch INSERT con transaction, deduplicazione su email, skip_duplicates: true salta duplicati senza errore. Max 500 contatti per richiesta.

curl -X POST https://auth.kacinka.it/contacts/import \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -d '{
    "contacts": [
      {"first_name": "Mario", "last_name": "Rossi", "email": "mario@example.com"},
      {"first_name": "Anna", "last_name": "Bianchi", "email": "anna@example.com"}
    ],
    "tags": ["importato"],
    "skip_duplicates": true
  }'

Semantica: Verifica che l'API sia operativa e il database raggiungibile.

Tecnica: SELECT 1 su MariaDB, check memory usage, timestamp UTC. Nessuna autenticazione, nessun rate limit.

curl https://auth.kacinka.it/health

{ "status": "ok", "timestamp": "2025-07-14T12:00:00Z", "database": "connected" }

Semantica: Elenco paginato di tutte le fatture del progetto con filtri avanzati.

Tecnica: Query params: ?status=draft|finalized|sent|paid&type=invoice|credit_note|proforma&page=1&per_page=25. Include totali aggregati per status.

Semantica: Crea una nuova fattura con righe dettagliate, aliquote IVA configurabili e dati di fatturazione del cliente.

Tecnica: Validazione numero univoco, calcolo automatico subtotal/tax/total da line items, FK su tax_codes, withholding_tax_id, cost_center_id. Stato iniziale "draft".

Semantica: Blocca la fattura — non più modificabile. Genera la registrazione contabile automatica (partita doppia) e assegna numero progressivo.

Semantica: Invia la fattura al cliente tramite email, PEC o SDI. Aggiorna sent_at e sent_via.

Semantica: Genera una nota di credito collegata alla fattura originale. Stornatura automatica della registrazione contabile.

Semantica: Genera e scarica il PDF della fattura con branding personalizzato (logo, colori, footer). Supporta template personalizzabili.

Semantica: Report scadenziario con fatture raggruppate per fascia temporale (30/60/90/120+ giorni). Totali per fascia.

Semantica: Crea una registrazione contabile in partita doppia. Le righe dare/avere devono bilanciarsi.

Tecnica: Validazione somma dare = somma avere, FK su account_id (piano dei conti). Supporta POST/void per stornatura. 7 endpoint totali.

Semantica: Gestisci anni fiscali e periodi contabili. Chiusura anno, apertura anno successivo.

Semantica: CRUD completo conti bancari + summary saldo. Import batch transazioni da CSV/OFX.

Semantica: Lista transazioni con filtri data, importo, tipo. POST per inserimento manuale.

Semantica: Avvia sessione di riconciliazione. Auto-match intelligente tra transazioni bancarie e registrazioni contabili. 9 endpoint per il flusso completo: start, auto-match, match, unmatch, accept-suggestion, complete.

Semantica: CRUD spese + workflow approvazione. Endpoint dedicati per submit, approve, reject, void. Collegamento ricevute e fatturabilità.

Semantica: CRUD categorie spese + POST seed per categorie predefinite italiane.

Semantica: Crea pagamento con allocazione su una o più fatture. Supporta pagamenti parziali, rimborsi e riconciliazione automatica.

Semantica: Fatture scadute, prossime scadenze, riepilogo per periodo. Endpoint: overdue, upcoming, summary + mark-overdue batch.

Semantica: Genera il file XML conforme al formato FatturaPA v1.2.2 per invio al Sistema di Interscambio (SDI). Validazione automatica prima della generazione.

Semantica: Genera file UBL conforme PEPPOL BIS Billing 3.0 per fatturazione elettronica europea.

Semantica: CRUD valute, GET/POST tassi di cambio, POST convert, POST fetch-ecb (aggiornamento automatico da BCE), POST revaluation.

Semantica: CRUD budget con workflow (approve → activate → close). Analisi varianze budget vs actual. CRUD centri di costo. Time-to-invoice tracking.

Semantica: Lista escalation AI da gestire manualmente. Include statistiche, dettagli interazione e contesto. 4 endpoint admin: list, stats, update, interactions.

Semantica: Avvia l'elaborazione OCR. Estrae vendor_name, vendor_vat, total, tax, net, line_items. Confidence score 0-1. POST link-expense per collegare a spesa esistente. Review manuale con PUT review.

Semantica: CRUD siti web. GET /s/{slug} per rendering pubblico. Endpoint separati per template personalizzabili.

Semantica: Lista, mark read, mark all read, preferenze (GET/PUT), grouped, digest, count. Rate real-time via polling o webhook.

Semantica: Invita un utente al progetto con ruolo specifico. Email con link di accettazione. CRUD team members + accept-invite. GET /roles e /permissions per la configurazione RBAC.

Semantica: Upload multipart/form-data. Download, preview, update, delete. Preview info per thumbnail.

Semantica: Aggregazione eventi da tutti i progetti dell'utente. CRUD per progetto sotto /projects/{projectId}/events.

Semantica: CRUD time entries con GET /time-report per report aggregato per periodo/utente/task.

Semantica: Genera una nuova API key con scope definiti. CRUD + revoke, rotate, usage stats. La chiave viene mostrata solo al momento della creazione.

Semantica: Config branding (logo, colori, welcome message). V1: accesso PIN. V2: magic link + sessioni. Sezione client: fatture, messaggi, documenti.

Semantica: Dashboard completa con statistiche utenti, revenue, sistema e chat. Sotto-sezioni: users CRUD (4), impersonation (3), feature flags (5), subscriptions, settings (2), audit, chat monitoring (2), notifications/communications (4), contact submissions (2), AI escalations (4), commerce (6).