Davveroo Backend - API e integrazioni

Superficie disponibile

Questa pagina documenta le route effettivamente montate in index.js tramite src/modules. I file legacy non montati restano indicati in fondo come codice presente ma non esposto dall'entrypoint attuale.

0endpoint montati

3schemi auth principali

2webhook raw-body

9aree funzionali core

Base URL

In locale il server ascolta su PORT o 4020. Produzione tipica: https://api.davveroo.it. La docs è su /docs e /api/docs.

Risposte

Molti moduli usano { ok: true }; ROO AI usa { success, data, error }. Gli errori includono spesso error, message e status HTTP coerente.

Idempotenza

Idempotency-Key è supportato per Stripe Terminal payment intent e viene inoltrato a Stripe quando presente.

Autenticazione

JWT firmati con JWT_SECRET. L'admin può usare JWT con ruolo admin oppure x-admin-token validato tramite hash SHA-256.

Tipo	Header	Come si ottiene	Uso
customer/admin JWT	`Authorization: Bearer TOKEN`	`POST /api/auth/login` o `POST /api/admin/login`	Utenti, admin, seller e funzioni protette da ruolo.
business JWT	`Authorization: Bearer TOKEN`	`POST /api/business/token/login`	Portale merchant, coupon, pagamenti, terminal, Softpay, supporto e AI.
admin API key	`x-admin-token: TOKEN`	Token il cui SHA-256 combacia con `ADMIN_API_KEY_SHA256`	Endpoint admin, agenti, inviti Stripe Connect e notifiche activity.
agent	`Authorization: Bearer AGENT_JWT` o `x-agent-email`	`POST /api/agent/login`	Dashboard agente e gestione ticket assegnati.

Endpoint montati

Filtra per area, metodo o testo. I path includono già il prefisso finale effettivo.

Quickstart

Sequenze minime per usare il backend da app, pannello admin o integrazione esterna.

# Login business con token API
curl -X POST http://localhost:4020/api/business/token/login \
  -H "Content-Type: application/json" \
  -d '{"token":"biz_xxx","email":"merchant@example.com"}'

# Lista coupon merchant
curl http://localhost:4020/api/portal/coupons \
  -H "Authorization: Bearer BUSINESS_JWT"

# Crea pagamento business via Stripe Checkout
curl -X POST http://localhost:4020/api/business/payments/create \
  -H "Authorization: Bearer BUSINESS_JWT" \
  -H "Content-Type: application/json" \
  -d '{"amount":2500,"currency":"eur","description":"Acconto","paymentMethod":"card"}'

# Upload catalogo CSV per generatore catalogo
curl -X POST http://localhost:4020/api/catalog-generator \
  -H "Authorization: Bearer BUSINESS_JWT" \
  -F "file=@catalogo.csv;type=text/csv" \
  -F "filename=catalogo.csv" \
  -F "source=business_portal"

# Catalogo live business
curl http://localhost:4020/api/portal/catalog \
  -H "Authorization: Bearer BUSINESS_JWT"

# ROO AI chat
curl -X POST http://localhost:4020/api/ai/chat \
  -H "Authorization: Bearer BUSINESS_JWT" \
  -H "Content-Type: application/json" \
  -d '{"merchantId":1,"message":"Crea una promo WhatsApp","mode":"marketing"}'

# Terminal Tap to Pay
curl -X POST http://localhost:4020/api/terminal/payment-intent \
  -H "Authorization: Bearer BUSINESS_JWT" \
  -H "Idempotency-Key: order-123" \
  -H "Content-Type: application/json" \
  -d '{"amount":1200,"currency":"eur","description":"Pagamento in negozio"}'

Payload principali

I campi extra non validati vengono ignorati in vari endpoint. Gli importi Stripe sono in centesimi; Softpay usa centesimi e currency code numerico ISO, default EUR 978.

Coupon merchant

title, description, original_value_cents, price_cents, currency, quantity_total, per_customer_limit, start_at, end_at, terms, is_active.

Business admin

name, city, address, tags_json, quote, img_url, description, contact_email, contact_phone, rating, lat, lng, stripeAccountId, agentId.

Catalogo live

multipart/form-data con file CSV oppure campo csv. L'import popola prodotti con categoria, marca, prezzo, spedizione, totale, quantità e stato; il business può modificare ed esportare CSV.

ROO AI

merchantId, conversationId, message, mode; offerte con goal, target, tone, discount, service, channel.

Config ambiente

Variabili ricavate dal codice corrente. I valori sensibili non vanno mai esposti al frontend.

Area	Variabili	Note
Server	`PORT`, `CORS_ORIGINS`/`ALLOWED_ORIGINS`, `CORS_ALLOW_LOCALHOST`, `CORS_ALLOW_LOCALHOST_WILDCARD`, `JSON_BODY_LIMIT`, `FORM_BODY_LIMIT`	CORS accetta richieste senza Origin e include gli origin Expo/locali più comuni; imposta `CORS_ALLOW_LOCALHOST=0` per disabilitarli.
Auth	`JWT_SECRET`, `JWT_EXPIRES_IN`, `ADMIN_API_KEY_SHA256`	Default dev presente per JWT, da cambiare in produzione.
Database	`DATABASE_URL`	Prisma 6, schema in `prisma/schema.prisma`.
Stripe	`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PUBLISHABLE_KEY`, `STRIPE_TERMINAL_DEFAULT_ACCOUNT_ID`	Terminal valida coerenza test/live tra secret, publishable key e location.
Frontend/App	`FRONTEND_URL`, `FRONTEND_BASE_URL`, `PUBLIC_API_BASE_URL`, `APP_VERIFY_SUCCESS_URL`, `APP_VERIFY_ERROR_URL`, `APP_RESET_PASSWORD_URL`	Usate per redirect, checkout success/cancel e deep link mobile.
Email	`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER_`, `SMTP_PASS_`	Sender predefiniti: partner, info, contratti.
AI	`GEMINI_API_KEY`, `GEMINI_API_KEY_BOT`	Provider Gemini per modulo ROO.
Softpay	`SOFTPAY_AUTH_URL`, credenziali client, `SOFTPAY_DEFAULT_CURRENCY_CODE`, secret webhook	Il controller maschera token, password e authorization nei log/error details.
Catalog generator	`CATALOG_GENERATOR_MAX_BYTES`, `CATALOG_GENERATOR_MAX_ROWS`, `CATALOG_GENERATOR_UPLOAD_DIR`, `CATALOG_GENERATOR_RATE_LIMIT`, `CATALOG_WRITE_RATE_LIMIT`	Limite default 5MB, upload default in `uploads/catalog-generator`. Le notifiche catalogo sono gestite su endpoint admin.

Codice presente ma non montato

Questi moduli/file sono nel repository ma non compaiono nell'array routes di src/modules/index.js, quindi non risultano esposti dall'entrypoint attuale salvo mount esterni.

Legacy

src/modules/legacy: businessPortal, dashboard, stripe legacy. Importato nel modulo ma non inserito in routes.

Customers

src/modules/customers e src/routes/customersRoutes.js sono presenti ma non montati.

Sales

src/modules/sales e top sellers sono presenti ma non montati nell'entrypoint attuale.