CORTEX — connectors (padrão e específicos)

Versão: 0.1.4 · Data: 2026-10-13 · Status: Rascunho · Owner: Plataforma Caminho canônico: cortex-docs/services/CONNECTORS.md Documentos irmãos: cortex-docs/ECOSYSTEM.md (catálogo §4, comunicação §5) · cortex-docs/standards/UNISCALE_ENGINEERING_STANDARDS.md (nomenclatura §7, evento §28)

Este documento fixa o padrão de connector (regras comuns a todos) e descreve os três connectors em construção: academic-connector, crm-connector, payment-connector. Promove a regras endereçáveis o que já está assentado no ECOSYSTEM §4/§5; o desenho interno de cada integração externa fica em aberto (§Fronteiras). Rascunho pendente de revisão — não inventar o que está marcado como em aberto.

1. Mão-dupla, sem banco, tradutor (Obrigatório)

Connector é mão-dupla por construção e sem banco (ECOSYSTEM §4). É tradutor, não dono de dado: o estado de negócio vive nos serviços, nunca no connector. Ele não persiste verdade — converte entre o contrato interno do CORTEX e a API do sistema externo, nos dois sentidos. (Distingue-se de adapter, que só traduz/normaliza formato e não integra — UNISCALE §7.)

2. Consome fila e expõe chamada direta (Obrigatório)

Todo connector tem os dois modos (ECOSYSTEM §4/§5):

• Consome fila — para empurrar fatos do CORTEX ao sistema externo (reage a evento; ex.: mover card, criar matrícula). Conector novo = fila nova no exchange, sem mexer no publicador.
• Expõe chamada direta — para responder consulta na hora (síncrono quando há dependência de resultado; ex.: o ai-sales pergunta algo ao terceiro via connector).

Entrega de fila é at-least-once com consumer idempotente, retry com limite + backoff e DLQ obrigatória (UNISCALE §29.3) — connector que empurra fato a terceiro não pode duplicar a ação por reentrega.

3. Nome por domínio, não por fornecedor (Obrigatório)

O connector é nomeado por domínio / sistema externo (<external-system>-connector, UNISCALE §7), e o contrato dos serviços internos é por domínio, não por fornecedor. Trocar o fornecedor (de CRM, de gateway) é trocar/reconfigurar o connector — não renomear contrato nem mexer em quem o consome (ECOSYSTEM §4). É o que mantém o fornecedor substituível.

Os três connectors

academic-connector — jacad (autoridade acadêmica)

Mão-dupla real com o jacad: lê (cadastro, contrato) e escreve (matrícula). O jacad é a autoridade da verdade acadêmica (homologado MEC — ECOSYSTEM §1/§3): o CORTEX comanda a matrícula pela API de escrita, mas a verdade do contrato resultante continua sendo do jacad. Serve o order-service na receita de matrícula.

crm-connector — bitrix24 (janela de gestão)

Empurra eventos do CORTEX que nascem e movem cards no CRM (hoje bitrix24). O bitrix é janela de gestão/acompanhamento, não dono da trilha do lead (essa é do tracking — ECOSYSTEM §3). Pipes e raias são configurados no institutional; o connector só aplica o movimento que o fato manda. Regras detalhadas em cortex-docs/services/CRM_CONNECTOR.md (como o payment-connector aponta para PAYMENT_SERVICE.md).

payment-connector — um por gateway

Um por gateway, atrás do payment-service (regras: cortex-docs/services/PAYMENT_SERVICE.md §5). O gateway é substituível; o payment-service orquestra e o connector traduz a mecânica do gateway (ECOSYSTEM §6). O primeiro é o dom-pagamentos-connector (Dom Pagamentos).

É o caso mais literal do §1 e do §2 deste documento: o connector é a fronteira nos dois sentidos — as requisições ao gateway (autorizar, capturar, cancelar) saem por ele, o webhook do gateway entra por ele, e a resposta que o gateway espera volta por ele. Ele traduz e repassa; quem decide e persiste é o payment-service. Regras detalhadas em PAYMENT_SERVICE.md §5 e §7.

Fronteiras a definir (não inventar)

• Contrato exato de cada API externa (jacad, bitrix24, cada gateway) — endpoints, autenticação, mapeamento campo a campo: a definir por integração, lendo a API real. Não presumir.
• Mapa de eventos → ações por connector (qual fato move qual card, qual fato dispara matrícula) — depende dos fluxos, ainda não fechados.
• Connectors de canal (whatsapp-connector e futuros) — fora deste doc. Por decisão de arquitetura atual absorvem a governança de canal (entrega, opt-out, ritmo, status, demux); o messaging-service que a centralizaria é recomendado, não adotado (ECOSYSTEM §4/§7). Quem for construir um connector de canal lê a nota de recomendação do ECOSYSTEM §4 — esses controles (opt-out, ritmo por número, dedup, demux) passam a ser responsabilidade do connector, sob risco operacional/legal se ficarem de fora.

CHANGELOG