Área técnica
APIs e contratos
Superfície HTTP do commerce-vc1 em api.vc1.com.br (e api.lab.vc1.com.br): BFF da SPA, tokens de revenda, webhooks inbound e health. OpenAPI público: a definir (protótipo REV-28). Canônico: 03-ARCHITECTURE.md §4–6, 08-SECURITY-LGPD.md.
Ver tela protótipo REV-28 (tokens e webhooks outbound)
Autenticação e versionamento
| Consumidor | Mecanismo | Host |
|---|
| SPA revenda / cliente | Sanctum cookie stateful (host-only do slug) | {slug}.vc1.com.br |
| Staff | Sessão Filament + 2FA (TOTP padrão) | admin.vc1.com.br (Filament, não REST público) |
| Proposta pública | PIN 6 dígitos → cookie de acesso | {slug}.vc1.com.br/p/{code} |
| Integração revenda | Bearer identity.api_tokens (abilities/scopes) | api.vc1.com.br |
| Webhooks meSign / mePay | HMAC corpo bruto (meSign confirmado; mePay a verificar) | api.vc1.com.br/api/v1/webhooks/* |
- Versionamento — prefixo
/api/v1/ na URL; breaking change → v2 (política detalhada a definir).
- CORS — allowlist dos hosts ativos; origem
* proibida. Token nunca na query string nas chamadas originadas pelo commerce (R2).
- Cross-tenant — recurso de outro tenant → HTTP 404 (não 403), inclusive em LAB (D-SEC).
Rate limits (documentados)
| Superfície | Limite | Fonte |
|---|
| Proposta pública (PIN) | 10 tentativas/h por IP+slug; lockout 5 falhas → 15 min | 08-SECURITY (padrão sales) |
| API Bearer revenda | a definir | — |
| Webhooks inbound | Sem CORS; validação HMAC antes do use case | 03-ARCHITECTURE §4.3 |
| Respostas 429 | Sem stack trace / exception na payload | 08-SECURITY |
Catálogo por painel / consumidor
Rotas abaixo são as citadas no blueprint ou herdadas do doador sales-mework360. Demais recursos REST (clientes, faturas, DIDs, kanban…) seguem o mesmo prefixo — contrato OpenAPI a definir (épico E5+ / D-RM-05).
Público / branding (sem login)
| Método | Path | Notas |
|---|
GET | /api/v1/tenancy/branding | Cache Redis 60 s; logo, cores, slug — sem dados fiscais |
| CEP/CNPJ públicos (doador): paths a confirmar no fork |
SPA revenda + cliente (Sanctum)
| Método | Path | Notas |
|---|
POST | /api/v1/auth/login | Reuso doador; tenant via Host |
GET | /api/v1/auth/me | Usuário + roles |
POST | /api/v1/proposals | Criar proposta (wizard) |
POST | a definir (ex. …/proposals/{id}/accept) | Aceite pós-PIN; dispara meSign — path exato não fixado no MD |
GET | /api/v1/proposals/kanban | Reuso doador (adaptar colunas brief) |
Painel cliente /app/*, financeiro, números, portabilidade: a definir (E4/E5) |
API token revenda (api.vc1.com.br)
Scopes padrão propostos: customers:read, invoices:read, dids:read — protótipo REV-28 também cita proposals:write. Gestão de tokens na UI revenda (E5+).
| Método | Path | Notas |
|---|
GET | /api/v1/customers/{uuid} | Exemplo cross-tenant test (404) |
| CRUD clientes, faturas, extratos, DIDs: a definir |
Operações / plataforma
| Método | Path | Notas |
|---|
GET | /up | Liveness (Laravel) |
GET | /api/v1/health | Health app (monitoramento) |
GET | /api/v1/health/ready | PG + Redis + disco watermark CDR; não testa SipPulse |
GET | /metrics | Prometheus (padrão proposto, rede interna) |
Webhooks inbound (provedores → commerce)
| Path | Provedor | Eventos mínimos | Auth |
|---|
POST /api/v1/webhooks/paco-assign | meSign | envelope.completed, envelope.archived | X-Paco-Signature: sha256=… |
POST /api/v1/webhooks/mepay | mePay | charge.paid, charge.failed, charge.refunded, charge.chargeback | HMAC a verificar (D-INT-18) |
Processamento via integration.inbox_webhooks antes do use case; dedupe idempotente (03-ARCHITECTURE §8).
Eventos / webhooks outbound (commerce → revenda)
Pós-MVP (E5+): revenda registra URL no painel — ver REV-28 e roadmap integration.outbound_webhooks.
| Evento (exemplos) | Quando | Status spec |
|---|
proposal.accepted | Cliente aceita proposta | Protótipo; payload a definir |
customer.blocked | Bloqueio crédito/limite/inadimplência | Protótipo; payload a definir |
| Catálogo completo (fatura emitida, pagamento, NF autorizada): a definir — alinhar a outbox/event catalog E6 |
APIs externas consumidas (ports)
Não são rotas do commerce-vc1; contratos em integrações.
| Port | Alvo (amostra) |
|---|
| ProvisioningPort | POST …/api/white_label/cadastro_total_tronco (base URL PROD a verificar) |
| TelcoPort | SOAP SipPulse SubscriberWS / DidWS |
| FiscalPort | mePay REST — solicitação NFCom 62 (emissor terceiro atrás do mePay); webhooks fiscal.issued / fiscal.failed (a criar) |
| SignaturePort | POST /api/v1/envelopes (meSign externo) |
| PaymentPort | mePay REST — /v1/invoices/adhoc, charges, webhook invoice.paid |
| DnsPort | PowerDNS /api/v1/servers/localhost/zones (LAN) |
📡
Por que isso importa
Separar auth por Host evita que integradores tratem a API como “monolito multi-tenant por header”. Webhooks inbound com HMAC e inbox fecham o loop meSign/mePay sem jobs ad hoc. O catálogo explícito do que já está no MD vs “a definir” orienta contratos com TI cliente e parceiros antes do OpenAPI público.
06-INTEGRATIONS.md · Diagramas de sequência