Modalidades do Ecossistema de Parceiros (partner track)
O Passinstance colabora com ISVs de POS, agências digitais, consultoras de marketing e revendedores de hardware através das quatro modalidades partner track no Passinstance database (TECHNOLOGY, SOLUTION, REFERRAL, RESELLER), regidas por partner status (APPLIED | UNDER_REVIEW | ACCEPTED | INTEGRATING | VERIFIED | ACTIVE | SUSPENDED | TERMINATED | REJECTED):
| Modalidade partner track | Perfil Ideal de Parceiro | Capacidades Nucleares e Modelo Comercial | ||
|---|---|---|---|---|
TECHNOLOGY | Plataformas POS, bilhética, CRM, reservas e ERP | Coengenharia nativa de webhooks/API, aprovisionamento sandbox e listagem pública no diretório (partner visibility: `DRAFT | PRIVATE | PUBLIC`). |
SOLUTION | Agências digitais e consultoras retalho/hotelaria | Gestão de espaços multicliente, registo de oportunidades (request payload) e integração prioritária. | ||
REFERRAL | Consultores, criadores e especialistas setoriais | Rastreio de atribuição (SAAS_REFERRAL_COMMISSION) com até 15% de comissão recorrente por referenciação (default: 15.00, 12 meses). | ||
RESELLER | Revendedores integrados de hardware e software | Margens de revendedor (RESELLER_MARGIN), extras white-label e ativação de hardware NFC (partner order status). |
Referência da API do Portal e Diretório de Parceiros
A API de Parceiros do Passinstance gere a descoberta no diretório público, integração de parceiros, registo de negócios (opportunity status), assinatura legal de acordos (agreement status) e contabilidade de comissões (commission type: PERCENTAGE | FIXED_PER_CUSTOMER | CUSTOM):
| Caminho do Endpoint | Método | Autenticação | Descrição | |||
|---|---|---|---|---|---|---|
/api/v1/partners/directory | GET | Pública | Lista parceiros verificados no diretório público com filtros por região e especialidade. | |||
/api/v1/partners/public/:slug | GET | Pública | Obtém perfil público, certificações e casos de estudo de um parceiro pelo slug. | |||
/api/v1/partners/apply | POST | Pública | Submete nova candidatura a parceria (request payload). | |||
/api/v1/partners/:id | GET | Bearer | Obtém detalhes autenticados do registo do parceiro. | |||
/api/v1/partners/:id/deals | GET / POST | Bearer | Lista ou regista oportunidades de clientes (request payload) para assegurar atribuição. | |||
/api/v1/partners/:id/referrals | GET | Bearer | Lista conversões de referenciação self-service (referral status: `PENDING | ACTIVE | CHURNED | DISQUALIFIED`). |
/api/v1/partners/:id/agreements | GET | Bearer | Lista acordos comerciais de parceiro (agreement status). | |||
/api/v1/partners/:id/agreements/:agreementId/sign | POST | Bearer | Regista criptograficamente a aceitação e assinatura do parceiro num acordo. | |||
/api/v1/partners/:id/commercial-terms | GET | Bearer | Devolve taxas de comissão ativas (revenue type) e condições de pagamento. | |||
/api/v1/partners/:id/commissions | GET | Bearer | Obtém movimentos do livro-razão de comissões (ACCRUED, PENDING_APPROVAL, APPROVED, PAID, CANCELLED). |
Submeter uma Candidatura de Parceiro e Registar uma Oportunidade
Os candidatos a parceiros podem submeter o pedido programaticamente ou através de /become-a-partner via 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
}
Após aprovação e assinatura do acordo (POST /api/v1/partners/:id/agreements/:agreementId/sign), os parceiros registam oportunidades comerciais via 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 de Vida de Apuramento, Aprovação e Liquidação de Comissões
Quando um cliente referenciado ou associado a uma oportunidade paga uma fatura de subscrição, o motor de faturação regista os ganhos através das etapas auditáveis commission status:
-
1
Apuramento (
POST /api/v1/admin/partners/:id/commissions/accrue): Calcula a comissão devida (ACCRUED) segundo as condiçõescommercial-termsativas quando a fatura passa paraPAID. -
2
Aprovação (
POST /api/v1/admin/partners/:id/commissions/:commissionId/approve): Bloqueia o lançamento apurado (APPROVED) após terminar o período de eventual reembolso ou estorno (commission refund status:NONE | PARTIAL_REFUND | FULL_REFUND). -
3
Liquidação (
POST /api/v1/admin/partners/:id/commissions/:commissionId/settle): Regista a referência da transferência de pagamento e altera o lançamento paraPAID.
Importante: Para garantir proteção de atribuição em vendas empresariais ou assistidas por agência, registe sempre o potencial cliente via
POST /api/v1/partners/:id/dealsantes de o cliente criar o seu espaço de produção.
Explore o ecossistema em /partners ou apresente diretamente a sua candidatura em /become-a-partner.
