Visão geral
O Passinstance oferece níveis de subscrição transparentes de capacidade fixa medidos estritamente por Cartões Ativos em Wallet—cartões atualmente instalados e contactáveis nos dispositivos dos clientes. Suportados por Billing API (/api/v1/billing/*) e acessíveis em Definições -> Faturação (/settings/billing/overview, /add-ons, /payment-method, /invoices), os espaços de trabalho podem subscrever em EUR (€) ou USD (\$) em BillingFrequency (Monthly, Yearly com ~20% de poupança anual), adicionar extras modulares e validar códigos promocionais.
Arquitetura de Medição de Subscrições e Add-Ons
Importante: Pode consultar definições e funcionalidades dos planos em direto a qualquer momento em /pricing ou programaticamente via
GET /api/v1/billing/plans. Organizações sem fins lucrativos e instituições de ensino qualificam-se para descontos recorrentes personalizados—consulte Elegibilidade e Benefícios.
Níveis de Subscrição de Capacidade Fixa
| Nível do Plano | Capacidade de Cartões Ativos | Faturação Mensal (EUR / USD) | Faturação Anual (~20% Poupança) | Casos de Uso e Direitos Principais |
|---|---|---|---|---|
| Free | 5 cartões ativos | €0 / \$0 | Gratuito para sempre | Prototipagem em sandbox, design visual de modelos, testes em direto Apple/Google e avaliação da API REST. |
| Starter | 200 cartões ativos | €16 / \$22 /mês | ~20% desconto | Programas de fidelização de localização única, clubes boutique, lojas-piloto e emparelhamento scanner web/móvel. |
| Growth | 2.000 cartões ativos | €120 / \$180 /mês | ~20% desconto | Fidelização retalhista multiloja, séries de eventos recorrentes, fluxos CRM automatizados e webhooks Push/Pull. |
| Scale 10K | 10.000 cartões ativos | €400 / \$700 /mês | ~20% desconto | Cadeias hoteleiras de elevado volume, atrações regionais, funções RBAC personalizadas e pipelines API de alto débito. |
| Enterprise | 10.001+ cartões ativos | Personalizado | Acordo Personalizado | Grupos multimarca, SAML 2.0 SSO, SLAs dedicados, patamares PricingAgreement e portais white-label. |
Subscrições Base, Add-Ons e Códigos Promocionais (Billing API)
O Passinstance separa o plano de subscrição base das subscrições de extras (add-ons) modulares para que possa expandir capacidades específicas (como domínios personalizados marca branca ou blocos adicionais de cartões ativos) sem passar diretamente para um contrato Enterprise completo.
Endpoints Principais de Planos/Add-Ons e Enumerações de Estado
Os registos Subscription monitorizam o estado em subscription status (ACTIVE, INACTIVE, EXPIRED, CANCELLED, SUSPENDED, TRIALING, PAST_DUE, GRACE_PERIOD, RESTRICTED, CANCEL_AT_PERIOD_END, UNPAID, ARCHIVED) e os ciclos em BillingFrequency (Monthly, Yearly):
| Endpoint | Verbo HTTP | Descrição |
|---|---|---|
/api/v1/billing/plans | GET | Devolve planos de subscrição ativos, preços em EUR/USD, BillingFrequency e funcionalidades incluídas. |
/api/v1/billing/subscription | GET | Devolve a subscrição ativa (subscription status), ciclo de faturação e currentPeriodEnd. |
/api/v1/billing/overview | GET | Combina plano base, subscrições add-on, contadores de consumo em tempo real e pré-visualização da próxima fatura. |
/api/v1/billing/addons | GET | Lista add-ons disponíveis em self-service (pacotes de capacidade, extras de domínio personalizado). |
/api/v1/billing/add-on-subscriptions | GET / POST | Lista add-ons ativos ou associa uma subscrição recorrente (request payload). |
/api/v1/billing/add-on-service-requests | POST | Submete um pedido de configuração assistida (request payload) para DNS marca branca ou certificados. |
/api/v1/billing/promotions/validate | POST | Valida um código promocional (request payload) para um plano e moeda específicos. |
Consultar Resumo Consolidado de Faturação
GET /api/v1/billing/overview HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Payload de Resposta (200 OK)
{
"subscription": {
"id": "sub_019331b2-7e10-7a44-9b00-112233445566",
"planId": "growth_yearly",
"planName": "Growth",
"status": "ACTIVE",
"interval": "Yearly",
"currency": "EUR",
"unitAmount": 115200,
"currentPeriodStart": "2026-01-15T00:00:00.000Z",
"currentPeriodEnd": "2027-01-15T00:00:00.000Z",
"cancelAtPeriodEnd": false
},
"addOnSubscriptions": [
{
"id": "addsub_019331c0-1122-7d33-8f44-556677889900",
"addonKey": "white_label_domain",
"name": "Custom Vanity Domain & Branded Email",
"status": "ACTIVE",
"unitAmount": 2900,
"interval": "Monthly"
}
],
"capacity": {
"baseActivePassLimit": 2000,
"addOnActivePassLimit": 0,
"effectiveActivePassLimit": 2000,
"currentActivePasses": 1420,
"utilizationPercentage": 71.0
}
}
Validar um Código Promocional (POST /api/v1/billing/promotions/validate)
Valide se um código promocional se aplica ao nível e frequência escolhidos através de request payload ({ code, planId?, billingInterval?: 'monthly' | 'annual', currency?: 'EUR' | 'USD' }), devolvendo IPromotionEligibilityDecision (e regras de acumulação sob promotion policy: PRESERVE | FORFEIT | PRORATE):
POST /api/v1/billing/promotions/validate HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"code": "LAUNCH2026",
"planId": "growth_monthly",
"billingInterval": "monthly",
"currency": "EUR"
}
{
"isEligible": true,
"promotionId": "promo_019331ff-2b30-7c11-9a00-112233445566",
"promotionName": "2026 Launch Offer",
"publicLabel": "25% off first 6 months",
"code": "LAUNCH2026",
"discountType": "PERCENTAGE",
"discountPercent": 25,
"durationType": "REPEATING",
"durationMonths": 6
}
Documentação Relacionada
-
Compreenda como o consumo de cartões ativos é medido em Cartões Ativos e Limites de Utilização.
-
Pré-visualize o prorrateio e atualize ou cancele planos em Alterações de Plano e Cancelamento.
