Percorsi dell'ecosistema Partner (partner track)
Passinstance collabora con ISV di sistemi POS, agenzie digitali, società di consulenza di marketing e rivenditori hardware attraverso i quattro percorsi Passinstance database partner track (TECHNOLOGY, SOLUTION, REFERRAL, RESELLER), regolati da partner status (APPLIED | UNDER_REVIEW | ACCEPTED | INTEGRATING | VERIFIED | ACTIVE | SUSPENDED | TERMINATED | REJECTED):
| Percorso partner track | Profilo partner ideale | Funzionalità principali e modello commerciale | ||
|---|---|---|---|---|
TECHNOLOGY | Piattaforme POS, biglietteria, CRM, prenotazioni ed ERP | Co-progettazione nativa webhook/API, provisioning di ambienti sandbox, inserimento nella directory pubblica (partner visibility: `DRAFT | PRIVATE | PUBLIC`). |
SOLUTION | Agenzie digitali e società di consulenza retail/ospitalità | Gestione di workspace multi-cliente, registrazione delle opportunità commerciali (request payload), onboarding prioritario. | ||
REFERRAL | Consulenti, creator e advisor di settore | Tracciamento dell'attribuzione (SAAS_REFERRAL_COMMISSION) con commissione ricorrente di segnalazione fino al 15% (default: 15.00, 12 mesi). | ||
RESELLER | Rivenditori di pacchetti integrati hardware e software per il retail | Margini di rivendita (RESELLER_MARGIN), componenti aggiuntivi white-label, abilitazione hardware NFC (partner order status). |
Riferimento API per il Portale Partner e la Directory
L'API Partner di Passinstance gestisce la consultazione della directory pubblica, l'onboarding dei partner, la registrazione delle opportunità commerciali (opportunity status), la sottoscrizione dei contratti legali (agreement status) e la contabilità delle commissioni (commission type: PERCENTAGE | FIXED_PER_CUSTOMER | CUSTOM):
| Percorso Endpoint | Metodo | Autenticazione | Descrizione | |||
|---|---|---|---|---|---|---|
/api/v1/partners/directory | GET | Pubblico | Elenca i partner verificati nella directory pubblica con filtri per area geografica e specializzazione. | |||
/api/v1/partners/public/:slug | GET | Pubblico | Recupera il profilo pubblico, le certificazioni e i casi di studio per lo slug di un partner. | |||
/api/v1/partners/apply | POST | Pubblico | Invia una nuova candidatura di partnership (request payload). | |||
/api/v1/partners/:id | GET | Bearer | Recupera i dettagli del record del partner autenticato. | |||
/api/v1/partners/:id/deals | GET / POST | Bearer | Elenca o registra le opportunità clienti (request payload) per vincolarne l'attribuzione. | |||
/api/v1/partners/:id/referrals | GET | Bearer | Elenca le conversioni referral self-service (referral status: `PENDING | ACTIVE | CHURNED | DISQUALIFIED`). |
/api/v1/partners/:id/agreements | GET | Bearer | Elenca gli accordi commerciali del partner (agreement status). | |||
/api/v1/partners/:id/agreements/:agreementId/sign | POST | Bearer | Registra crittograficamente l'accettazione e la firma di un contratto da parte del partner. | |||
/api/v1/partners/:id/commercial-terms | GET | Bearer | Restituisce le percentuali di commissione attive (revenue type) e i termini di pagamento. | |||
/api/v1/partners/:id/commissions | GET | Bearer | Recupera le voci del registro commissioni (ACCRUED, PENDING_APPROVAL, APPROVED, PAID, CANCELLED). |
Invio di una candidatura Partner e registrazione di un'opportunità commerciale
I potenziali partner possono candidarsi a livello programmatico o tramite /become-a-partner utilizzando POST /api/v1/partners/apply (request payload):
{
"name": "Nordic Retail Systems AB",
"slug": "nordic-retail-systems",
"partnerType": "SOLUTION",
"websiteUrl": "https://nordicretailsystems.example.com",
"contactName": "Astrid Lindholm",
"contactEmail": "astrid@nordicretailsystems.example.com",
"description": "Multi-location loyalty and POS integrations across the Nordics.",
"commissionRatePercent": 15,
"commissionType": "PERCENTAGE",
"recurringPayoutMonths": 12
}
Una volta approvata la candidatura e firmato il contratto di partnership (POST /api/v1/partners/:id/agreements/:agreementId/sign), i partner registrano le opportunità clienti tramite POST /api/v1/partners/:id/deals (request payload):
{
"prospectName": "Erik Lindqvist",
"prospectCompany": "Stockholm Roastery Group",
"prospectDomain": "stockholmroastery.example.se",
"prospectEmail": "erik@stockholmroastery.example.se",
"estimatedValue": 12000.0,
"currency": "EUR",
"notes": "Multi-location loyalty + NFC NFC counter integration",
"protectionDays": 90
}
Ciclo di vita di maturazione, approvazione e liquidazione delle commissioni
Quando un cliente segnalato o associato a un'opportunità registrata paga una fattura di abbonamento, il motore di fatturazione traccia i compensi del partner attraverso fasi verificabili di commission status:
-
1
Maturazione (
POST /api/v1/admin/partners/:id/commissions/accrue): calcola la quota di commissione (ACCRUED) in base aicommercial-termsattivi del partner quando una fattura cliente passa aPAID. -
2
Approvazione (
POST /api/v1/admin/partners/:id/commissions/:commissionId/approve): consolida la voce maturata (APPROVED) una volta trascorso l'eventuale periodo di rimborso o storno (commission refund status:NONE | PARTIAL_REFUND | FULL_REFUND). -
3
Liquidazione del pagamento (
POST /api/v1/admin/partners/:id/commissions/:commissionId/settle): registra il riferimento del bonifico di pagamento e aggiorna la voce del registro commissioni aPAID.
Importante: Per garantire la protezione dell'attribuzione sulle vendite enterprise o assistite da agenzia, registri sempre il potenziale cliente tramite
POST /api/v1/partners/:id/dealsprima che il cliente crei il proprio workspace di produzione.
Esplori l'ecosistema dei partner su /partners oppure invii direttamente la Sua candidatura su /become-a-partner.
