Davveroo API Docs

Autenticazione

Le route admin accettano token admin via bearer e, dove configurato, anche header admin.

Authorization: Bearer <adminToken>
x-admin-token: <adminToken>
Content-Type: application/json

Le route agente richiedono token agente.

Authorization: Bearer <agentToken>
Content-Type: application/json

Assegnazione Consulenti

POST/api/admin/businesses/:businessId/assign-agent

Assegna o riassegna una attività a un consulente/agente.

{
  "agentId": 5,
  "notes": "opzionale"
}

Alias body accettati: agent_id, consultantId, consultant_id.

Alias endpoint:

POST /api/admin/businesses/:businessId/assign-consultant

{
  "ok": true,
  "businessId": 40,
  "agentId": 5,
  "assignment": {},
  "business": {}
}

Attività Assegnate

GET/api/agent/assigned-businesses

Lista veloce per pagina agente. Restituisce tutte le attività assegnate, anche senza transato.

GET /api/agent/assigned-businesses?from=2026-07-01&to=2026-07-31

Alias:

GET /api/agent/businesses
GET /api/agent/merchants
GET /api/agents/businesses

{
  "ok": true,
  "total": 20,
  "items": [
    {
      "businessId": 293,
      "businessName": "Eccellenze Italiane",
      "name": "Eccellenze Italiane",
      "volumeCents": 110000,
      "amountCents": 110000,
      "transatoCents": 110000,
      "totalVolumeCents": 110000,
      "paymentsCount": 2,
      "failedPaymentsCount": 0,
      "hasTransactions": true
    }
  ],
  "activities": [],
  "businesses": [],
  "merchants": [],
  "summary": {
    "totalBusinesses": 20,
    "activeBusinesses": 1,
    "totalVolumeCents": 110000,
    "paymentsCount": 2
  }
}

GET/api/admin/agents/:agentId/businesses

Lista admin delle attività assegnate a un consulente specifico.

GET /api/admin/agents/5/businesses
GET /api/admin/agents/5/businesses?includeRevenue=1&from=2026-07-01&to=2026-07-31

GET/api/agent/assigned-businesses/:businessId

Dettaglio veloce di una singola attività assegnata all'agente loggato.

GET /api/agent/assigned-businesses/293

Transato Merchant

GET/api/admin/businesses/revenue

Endpoint principale admin per transato attività.

GET /api/admin/businesses/revenue?from=2026-07-01&to=2026-07-31
GET /api/admin/businesses/revenue?businessId=293&from=2026-06-01&to=2026-07-31

Alias disponibili:

GET /api/admin/transactions/all
GET /api/admin/transactions
GET /api/admin/businesses/transactions
GET /api/admin/revenue
GET /api/admin/revenue/activities
GET /api/admin/transato

GET/api/agent/transactions

Transazioni per agente loggato. Usare con businessId quando si apre il dettaglio di una singola attività.

GET /api/agent/transactions?businessId=293&from=2026-06-01&to=2026-07-31

GET/api/admin/agents/:agentId/businesses/:businessId/revenue

Transato live di una singola attività assegnata a un consulente specifico.

GET /api/admin/agents/5/businesses/293/revenue?from=2026-06-01&to=2026-07-31

Contratto response transato.

transactions contiene solo riuscite e deduplicate. failedTransactions contiene le non riuscite. allTransactions è solo debug.

{
  "ok": true,
  "activities": [
    {
      "businessId": 293,
      "businessName": "Eccellenze Italiane",
      "volumeCents": 110000,
      "amountCents": 110000,
      "transatoCents": 110000,
      "totalVolumeCents": 110000,
      "paymentsCount": 2,
      "failedPaymentsCount": 0,
      "sources": {
        "businessPayments": {
          "volumeCents": 60000,
          "paymentsCount": 1
        },
        "liveStripeCharges": {
          "volumeCents": 50000,
          "paymentsCount": 1
        }
      }
    }
  ],
  "businesses": [],
  "merchants": [],
  "transactions": [
    {
      "id": "stripe_charge_ch_xxx",
      "businessId": 293,
      "businessName": "Eccellenze Italiane",
      "amountCents": 50000,
      "amountEur": 500,
      "currency": "EUR",
      "status": "paid",
      "statusGroup": "successful",
      "type": "stripe_charge",
      "source": "stripe_charge_live",
      "customerEmail": "cliente@mail.it",
      "stripePaymentIntentId": null,
      "stripeChargeId": "ch_xxx",
      "createdAt": "2026-07-20T09:10:00.000Z",
      "created": 1784538600
    }
  ],
  "failedTransactions": [],
  "allTransactions": [],
  "summary": {
    "totalVolumeCents": 110000,
    "paymentsCount": 2,
    "failedPaymentsCount": 0,
    "activeBusinesses": 1,
    "totalBusinesses": 20
  },
  "sources": {
    "businessPayments": 1,
    "couponOrders": 0,
    "liveStripePaymentIntents": 0,
    "liveStripeCharges": 1
  }
}

Regole frontend.

Per il transato mostrare solo res.data.transactions.
Non usare allTransactions per i totali.
Mostrare failedTransactions solo in una tab separata.
PAID maiuscolo non viene considerato riuscito.
Il range date conta: se passi luglio, i pagamenti di giugno non compaiono nel dettaglio.

Stripe Connect

POST/api/stripe/connect/invite

Crea un link onboarding Stripe Connect per una attività.

{
  "businessId": 293,
  "email": "merchant@mail.it",
  "refresh_url": "https://www.davveroopay.it/stripe/connect/refresh",
  "return_url": "https://www.davveroopay.it/stripe/connect/success"
}

Nota dati Stripe.

Non assegnare lo Stripe account principale a un merchant test. Ogni attività deve avere il proprio stripeAccountId, oppure null.

Yousign

POST/api/yousign-webhook

Webhook Yousign per signature request completate. Scarica i PDF firmati e li invia a YOUSIGN_BACKOFFICE_EMAIL.

YOUSIGN_API_KEY=...
YOUSIGN_BASE_URL=https://api.yousign.app/v3
YOUSIGN_WEBHOOK_SECRET=...
YOUSIGN_BACKOFFICE_EMAIL=contratti@davveroo.it

POST/api/yousign-send-signed-document

Invio manuale documento firmato senza webhook.

{
  "signatureRequestId": "..."
}