Conectores e credenciais

Um conector e o parceiro (Cielo, Konduto, ClearSale). Uma conta de conector e o cadastro da sua organizacao nesse parceiro, com as chaves. Fluxos citam a conta, nunca a chave: trocar a chave da Konduto atualiza todos os fluxos que usam a conta, sem republicar nada.

Pagina Plugins

No painel, Plugins (menu Roteamento) e o catalogo de parceiros com o status de cada um no ambiente escolhido no topo (sandbox ou producao). Os cartoes sao agrupados por tipo - adquirentes, subadquirentes, gateways, antifraude, Pix, cofre de cartoes e atualizacao de cartoes - e mostram as capacidades em linguagem de negocio: cartao, Pix, boleto, split, link de pagamento, 3DS, antifraude, tokenizacao, validacao de cartao e estorno. A busca e os filtros (tipo, status e capacidade) ficam na URL, entao um recorte pode ser compartilhado por link.

EM BREVE e o parceiro com available: false no catalogo (status coming_soon ou disabled). Ele aparece para planejamento, com as capacidades previstas e o link da documentacao do parceiro, mas sem formulario de chaves: a API recusa criar conta para ele (422) e os nos do construtor de fluxos o mostram como "(em breve)", sem deixar escolher.

No detalhe de cada plugin ficam:

• as contas do ambiente, com saude, ultimo teste, interruptor de habilitar, Testar conexao, edicao das chaves (campo em branco mantem o valor atual) e remocao;
• Usado nos fluxos: os fluxos publicados que citam alguma conta do plugin, com link para cada um, e as etapas em que ele pode entrar (no Rotear para adquirente, Antifraude, Validacao de cartao, Autenticacao 3DS e o link de pagamento da fatura avulsa, conforme as capacidades);
• em cada conta, a secao Recursos, que liga e desliga o que a conta usa do plugin - ver Recursos por conta.

Plugins e fluxos usam a mesma conta

Nao existe "conta do fluxo" separada da "conta do plugin": as duas telas leem e gravam a mesma conta de conector (/v1/connector-accounts).

• Cadastrar as chaves dentro de um no do construtor (botao Cadastrar chaves ou Nova conta) cria a conta que aparece em Plugins.
• Cadastrar em Plugins deixa a conta pronta para ser escolhida nos nos.
• Desabilitar em Plugins aparece no no como "(desabilitada)" e tira a conta do roteamento na hora.
• Editar a chave num lugar vale para o outro e para todos os fluxos que usam a conta, sem republicar.

Catalogo

curl http://localhost:3333/v1/connectors?capability=antifraud_assessment \
  -H "Authorization: Bearer $MINSTREL_API_KEY"

Cada item traz capabilities, credentialsSchema (os campos que a conta precisa) e status: available, coming_soon (integracao em construcao) ou disabled. O painel monta o formulario de chaves a partir do credentialsSchema - conector novo nao exige mudanca no painel.

Os demais parceiros do catalogo aparecem como coming_soon (EM BREVE no painel).

Na Cielo, sopClientId e sopClientSecret sao as credenciais do Silent Order Post, geradas no site da Cielo (Gestao API E-commerce, Microsservicos, Silent Order Post). Sao opcionais: a conta autoriza sem elas, mas so tokeniza o cartao no navegador do portador com elas. Veja Checkout transparente.

Cadastrar uma conta

curl -X POST http://localhost:3333/v1/connector-accounts \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorSlug": "konduto",
    "name": "Konduto - principal",
    "credentials": { "privateKey": "T..." },
    "verify": true
  }'

• As chaves sao validadas contra o credentialsSchema e gravadas cifradas (AES-256-GCM, vinculadas ao id da conta).
• Com verify: true, o Minstrel testa as chaves no parceiro antes de gravar; se o parceiro recusar, nada e salvo.
• A API nunca devolve a chave. Cada campo vem como { "configured": true, "secret": true, "hint": "••••••••" }; campos que nao sao segredo (ex.: Client ID) aparecem mascarados, o suficiente para reconhecer a conta.
• Na edicao (PATCH), campo omitido ou vazio mantem o valor atual: so o que for enviado e trocado.

Testar a conexao

Antes de salvar, com as chaves digitadas:

curl -X POST http://localhost:3333/v1/connectors/konduto/verify \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "credentials": { "privateKey": "T..." } }'

Ou de uma conta ja salva: POST /v1/connector-accounts/{id}/verify, que tambem atualiza a saude exibida no painel. A resposta separa tres situacoes, porque pedem acoes diferentes:

O teste e leve: nao cria pedido, nao gera cobranca e nao consome analise. Ha limite de 20 testes por minuto por organizacao.

Recursos por conta

O catalogo diz o que o plugin sabe fazer (capabilities). O que a conta pode fazer e menos: depende de contrato com o parceiro e da escolha de quem opera. Em Plugins, abra o conector, a conta e a secao Recursos: cada recurso mostra tres coisas.

Na Cielo:

No Minstrel Sandbox a validacao de cartao vem ligada, para testar o no Validacao de cartao sem contrato nem custo, e o resultado e simulado.

Por que existe a diferenca entre "o plugin sabe" e "a conta pode": ligar o Zero Auth numa conta sem o servico habilitado na Cielo geraria so respostas unavailable, e ligar sem querer um servico com custo seria surpresa na fatura do adquirente. Por isso o que depende de contrato nasce desligado.

Pela API, a conta traz config (os interruptores, com os padroes aplicados), effectiveCapabilities (as capacidades que a conta pode usar agora) e features (a matriz acima):

{
  "id": "ca_01HQ...",
  "connectorSlug": "cielo",
  "config": { "zeroAuthEnabled": true, "zeroAuthOnSave": false, "onAuthorizationExpiry": "notify" },
  "effectiveCapabilities": [
    "tokenize",
    "authorize",
    "capture",
    "void",
    "refund",
    "inquiry",
    "zero_dollar_auth"
  ],
  "features": [
    {
      "key": "zeroAuthEnabled",
      "title": "Validacao de cartao (Zero Auth)",
      "capability": "zero_dollar_auth",
      "availability": "available",
      "enabled": true,
      "requiresContract": true
    },
    {
      "key": "splitEnabled",
      "title": "Split de pagamento",
      "capability": "split",
      "availability": "coming_soon",
      "enabled": false,
      "requiresContract": true
    }
  ]
}

availability e available, coming_soon ou not_supported (o recurso pede uma capacidade que o conector nao tem). effectiveCapabilities e a lista que importa para o roteador e para o construtor de fluxos: uma conta com o Zero Auth desligado nao tem zero_dollar_auth ali e nao aparece no no Validacao de cartao.

Para mudar, PATCH /v1/connector-accounts/{id} com config. A atualizacao e parcial: so o que for enviado muda, e o resto continua como esta. null volta a chave ao padrao.

curl -X PATCH http://localhost:3333/v1/connector-accounts/ca_01HQ... \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "zeroAuthEnabled": true, "onAuthorizationExpiry": "void" } }'

Respondem 422: chave que o conector nao conhece, valor fora do tipo ou da lista, recurso Em breve e recurso que depende de outro desligado (ligar Validar ao salvar cartao sem a Validacao de cartao). Desligar a validacao de cartao desliga tambem o Validar ao salvar cartao.

Particularidades de cada parceiro

Konduto. O ambiente e definido pela chave, nao pela URL: chave privada de teste comeca com T, de producao com P. O teste avisa quando a chave nao combina com o ambiente da conta. O score (0 a 1) vira 0 a 100; recomendacao NONE (pedido nao analisado) segue para revisao.

ClearSale. Usa os hosts global-api.clear.sale (producao) e sandbox-global-api.clear.sale (sandbox). A decisao vem por status; pedido ainda nao classificado (NVO) e consultado de novo ate o prazo do no, e analise manual (AMA) segue para revisao. ERR (erro de integracao) sai pela porta error.

Cielo. Autoriza com CardToken da propria Cielo e marca credencial armazenada (CardOnFile) em toda cobranca com cartao salvo - as bandeiras recusam MIT sem essa marcacao. O codigo de retorno do emissor volta cru e e classificado pela tabela ABECS. O Zero Auth (validacao de cartao sem cobranca) cobre Visa, Mastercard e Elo, e exige o servico habilitado na Cielo - e um recurso da conta, desligado por padrao (ver Recursos por conta). A pre-autorizacao vence em 7 dias na Mastercard e em 15 nas demais bandeiras.

Uso em fluxos

GET /v1/connector-accounts traz, em cada conta, usedByFlows: os fluxos publicados cuja versao em vigor cita a conta. E o mesmo dado que a pagina Plugins usa para mostrar "usado em N fluxos" e a lista Usado nos fluxos. Rascunho nao conta: o uso vale a partir da publicacao.

{
  "id": "ca_01HQ...",
  "name": "Sandbox principal",
  "enabled": true,
  "usedByFlows": [{ "id": "flw_01HQ...", "name": "Roteamento por faixa de ticket" }]
}

As contas sao por ambiente. A listagem ja vem filtrada pelo ambiente da credencial, e as rotas por id (GET, PATCH, DELETE e o teste de conexao) respondem 404 para conta do outro ambiente: com a credencial de producao nao se le nem se altera conta de sandbox.

Remover ou desligar

DELETE /v1/connector-accounts/{id} e recusado (409) quando a conta esta em um fluxo publicado, com a lista dos fluxos em meta.flows. Para tirar um parceiro do ar na hora, desabilite a conta (PATCH com enabled: false): o roteador deixa de escolhe-la e as outras contas do no assumem os pagamentos novos. Cartao salvo nela nao muda de adquirente, porque o token so vale onde foi gerado: a cobranca falha dizendo que a conta esta desabilitada ate que ela seja reabilitada. Se ela for a unica opcao do no de roteamento, as transacoes desse caminho falham por falta de conector disponivel. Na pagina Plugins, o painel ja avisa antes de tentar: conta em fluxo publicado tem a remocao bloqueada e oferece desabilitar no lugar.