Integrações

Ports, sistemas externos e fluxos

Contratos dos adapters documentados em 06-INTEGRATIONS.md. Cada chamada grava integration.connector_calls; LAB usa LabGuarded* + allowlist. Tomadas hexagonais: arquitetura.

Catálogo por sistema

Pronto no legado

easy_cicerone (ERP legado)

↔ outbound · HTTP JSON Slim 3 · api/white_label

Dono: Fale Paco · Frequência: onboarding, aceite, bloqueio · SLA adapter: 30 s cadastro; retry 5× em 5xx/timeout · Auth: token WL (body POST; GET link legado em query — dívida R2)

Operações: POST /cadastro_total_tronco, POST /alterar_status_boqueio, GET /generate_login_link, DIDs/planos. Criação de projetos_clientes: colar ID (MVP) ou PR-LEG-02.

Pronto no legado

SipPulse 4.2 (TelcoPort)

→ outbound · SOAP SubscriberWS / DidWS

Dono: ops telco · Frequência: trial/ativação, bloqueio, quota pré-pago · SLA: 20 s; retry só fault transporte · Auth: UserPrincipal (vault SIPPULSE_SOAP_*)

insertSubscriber, updateSubscriberServices, blockSubscriber/activateSubscriber, insertDid. Sem ResellerWS/addCredit no desenho.

Pronto no legado

sippulse_reports (CdrPort)

← inbound read · MySQL SELECT

Dono: dados CDR · Frequência: job ~5 min (~52k/dia) · SLA: query 30 s; falha → próximo tick · Auth: usuário read-only VPN

Tabela cdrs_report; tarifar duration; duration_block auditoria (D-INT-01).

Contrato meWork

mePay (PaymentPort + FiscalPort)

↔ outbound + webhook inbound (Svix)

Dono: time mePay · Frequência: cobrança no fechamento + NF sob demanda · SLA: 15 s HTTP · Auth: Bearer mpk_…; webhook HMAC (D-INT-08, ADR-013)

Cobrança: POST /v1/invoices/adhoc, POST /v1/invoices/{id}/charges. NFCom: VC1 chama mePay; emissor terceiro atrás do mePay (NFCom API a criar no mePay). Webhook POST /api/v1/webhooks/mepay (invoice.paid, fiscal.issued futuro). Cliente: POST/GET …/fiscal-note.

Supersedido por ADR-013 (2026-11-04). Não é caminho de billing/fiscal do commerce-vc1.

Supersedido ADR-013

SyncNFe / RLGR (histórico legado)

— não integrado no commerce-vc1

Decisão 2026-11-04: VC1 não chama SyncNFe. Referência preservada em 06-INTEGRATIONS.md §5 para migração do ERP legado.

Pronto (MeWork)

meSign (SignaturePort)

↔ outbound + webhook inbound

Dono: MeWork/mesign · Frequência: por proposta aceita · SLA: 60 s create · Auth: Bearer MESIGN_API_KEY

POST /api/v1/envelopes (host meSign: mesign.mework360.com.br) · webhook commerce POST /api/v1/webhooks/paco-assign (HMAC X-Paco-Signature).

Pronto (operação)

meDNS / PowerDNS (DnsPort)

→ outbound · REST LAN dns-master:8443

Dono: meCloud · Frequência: ACME + vanity futuro · SLA: 30 s; mutação 1 tentativa · Auth: X-API-Key escopada zona

PATCH TXT _acme-challenge.vc1.com.br; wildcard bootstrap operador.

A verificar

SMTP / SMS (NotificationPort)

→ outbound

Dono: operador · Frequência: eventos 80/100%, fatura, proposta · SLA: 10 s · LAB: driver log

SMTP meCloud; SMS Disparos se autorizado (D-INT-15).

A definir (E6)

falepaco-api (hub futuro)

↔ eventos · fase 0 hoje

Dono: épico E6 · substitui Provisioning/Telco/CDR adapters · Payment/Fiscal podem permanecer.

Fluxos ponta a ponta

Sequências alinhadas a 03-ARCHITECTURE.md §10. Campos ou paths não especificados nos docs aparecem como “a definir” nos SVGs.

Sequência proposta e ativação — **Proposta → ativação.** PIN público, trial opcional (ERP + SipPulse), aceite, meSign, webhook HMAC, provisionamento definitivo e `subscription.active`.

Sequência CDR e fatura — **CDR → fatura → NFCom.** Import + rating 30/6, fechamento, mePay (cobrança + NFCom via emissor terceiro) e e-mail transacional.

Sequência pagamento mePay — **Pagamento → desbloqueio.** Webhook mePay idempotente, atualização de fatura/pagamento, TelcoPort libera SIP quando bloqueio era por crédito ou inadimplência.

Falhas, retry e idempotência

Política comum ( 06-INTEGRATIONS.md §Convenções):

Retry outbound — HTTP 408/429/5xx e SOAP fault de transporte: 5 tentativas, backoff 30 → 120 → 600 → 1800 → 3600 s. Erro 4xx de negócio: sem retry automático.
Idempotência outbound — chave {use_case}:{aggregate_id}:{cycle_or_event} em header/campo quando o provedor suporta; gravação em connector_calls com hash do request.
Inbox webhooks — integration.inbox_webhooks: dedupe por provider + event_id (ou hash do payload). Retransmissão → HTTP 200 sem reprocessar.
Outbox — evento na mesma transação PG da mutação; OutboxDispatchJob republica até sucesso ou estado failed com alerta.
Estados de erro — mapeamento API: legacy_unavailable, legacy_rejected, lab_write_refused, fiscal_not_authorized, etc. Sem stack trace na resposta (429/5xx sanitizados — D-SEC).
LAB — miss na allowlist → lab_write_refused antes do transporte; métrica + log JSON sem secrets.
Reconciliação — ReconciliationJob 04:00: PG vs ERP/SipPulse/mePay; drift → audit + alerta ops (sem write automático no ERP).

Por que isso importa

Integrações telco e fiscais falham por rede, SOAP instável ou Sefaz lenta. Idempotência + inbox evitam segunda cobrança, segundo subscriber ou NF duplicada quando o provedor reenvia webhook. Connector_calls dá métrica por port (integration.connector_calls{port,status}) para SLO de ops.

Mudanças necessárias no sistema atual

Antes do piloto em produção, o ERP legado precisa de ajustes pequenos — sempre com aprovação do operador, branch no repositório easy_cicerone e PR revisado. Nenhum agente altera produção sozinho.

PR-LEG-01 — obrigatório (gate do 1º PROD) Inventariar todos os jobs/crons que geram fatura de tronco white label no ERP e, em cada um, respeitar a flag projetos_clientes.skip_tronco_billing = 1 para projetos VC1. Sem isso, cliente seria cobrado duas vezes (legado + commerce-vc1).

PR-LEG-01 — inventário completo + coluna skip_tronco_billing (default 0) + teste “zero título novo” no ciclo piloto. Primeiro passo mínimo: cron geracao_faturas_whitelabel_tronco.php. Aprovação operador
PR-LEG-02 — API para criar projetos_clientes no onboarding (hoje só formulário WP). Até lá: operador cria projeto e cola legacy_project_id no Filament. Aprovação operador
PR-LEG-03 — opcional expor AtivacaoTronco via HTTP. Preferência: commerce chama SipPulse direto (TelcoPort), sem depender desse PR. Opcional
PR-LEG-04 — corrigir bug em financeiro/cliente/cobrancas (id hardcoded). O adapter não usa essa rota até o fix. Aprovação operador
PR-LEG-05 — demais crons de billing WL (ex. criarFaturamentoClienteWl.php) com o mesmo filtro skip_tronco_billing, conforme inventário do PR-LEG-01. Aprovação operador
PR-LEG-06 — NFCom no commerce segue mePay (ADR-013); legado ERP/SyncNFe permanece até desligamento. Fora do caminho feliz

Ordem de deploy sugerida: ERP com flag skip → commerce-vc1 → DNS wildcard. Detalhe: 06-INTEGRATIONS.md §10 e _BRIEF.md §5.

ALTER TABLE projetos_clientes
  ADD COLUMN skip_tronco_billing TINYINT(1) NOT NULL DEFAULT 0;

Onboarding VC1 grava skip_tronco_billing = 1. Não reutilizar have_tronco para esse filtro.

Épicos e integrações

Fundação — meDNS, deploy LAB, adapters Fake/LabGuarded.

Atacado — ERP projeto revenda, STFC.

Funil — meSign, ERP cadastro, SipPulse trial.

Tarifação + NF revenda — CDR, mePay cobrança/NFCom, extrato revenda fatura.

Crédito/limites — quota SipPulse, bloqueios, notify.

VC1 fatura cliente — mePay, NF cliente, repasse.

Troca de motor — falepaco-api / falepaco-erp / Kamailio nos mesmos ports.