Conectores

Os conectores sincronizam dados das ferramentas em que suas ventures já rodam — processadores de pagamento, bancos, provedores de nuvem, plataformas de anúncios, APIs de IA — para que receita e custos fluam automaticamente para o Kordox e se tornem lucro real, por venture.

Tudo o que um conector puxa é somente leitura. O Kordox nunca movimenta dinheiro, altera configurações nem escreve nada de volta na conta conectada.

Como os conectores funcionam

O fluxo é o mesmo para todos os provedores:

1. Adicionar — abra uma venture → aba Conectores (ou Finanças → Fontes de dados), clique em Conectar fonte e escolha um provedor.
2. Autorizar — seja por OAuth em um clique (você aprova o acesso de leitura na própria tela do provedor) ou colando uma chave / token de API que você cria no painel do provedor. O painel mostra os passos exatos e leva direto à página certa.
3. Verificar — o Kordox checa a credencial na hora e avisa se algum escopo ou permissão está faltando.
4. Sincronização inicial — o primeiro puxão roda automaticamente e preenche o histórico recente.
5. Manter atualizado — o Kordox re-sincroniza em intervalos regulares (a cada ~6 horas); você também pode Sincronizar manualmente a qualquer momento.
6. Atribuir — as transações sincronizadas são roteadas para a venture a que pertencem (veja Atribuindo dinheiro às ventures).

Limitado a uma venture

Os conectores são limitados a uma venture, então cada venture só vê suas próprias contas conectadas e seus próprios dados. Custos de infraestrutura e de IA podem então ser divididos entre as ventures por atribuição.

Segurança — como as credenciais são tratadas

• Somente leitura por natureza. Todo conector pede apenas escopos de leitura (faturamento, cobranças, pedidos, relatórios de custo). Nada do que o Kordox guarda pode gastar, reembolsar ou reconfigurar sua conta.
• Criptografadas em repouso. Chaves de API e tokens OAuth são criptografados antes de serem armazenados e nunca são devolvidos ao navegador depois que você os salva.
• Menor privilégio. Onde um provedor oferece credenciais com escopo (chaves restritas do Stripe, tokens com escopo da Cloudflare, políticas IAM da AWS), o guia pede a permissão mais estreita que funciona — listada por conector abaixo.
• Revogue a qualquer momento. Desconectar remove o acesso do Kordox e para a sincronização. Os dados já sincronizados permanecem no seu livro-razão.

Conectores disponíveis

Categoria	Provedores	Conectar via
Receita	Stripe, Shopify, PayPal, Square	OAuth (Stripe/Shopify) ou chave de API
Caixa / banco	Plaid (saldos alimentam o fôlego de caixa)	Chave de API + token do Link
Custo de infraestrutura	Cloudflare, AWS Billing, GCP Billing	Chave de API ou OAuth (GCP)
Gasto com anúncios	Meta Ads, Google Ads	OAuth
IA & tokens	Anthropic (Claude), OpenAI	Chave de API de admin
E-mail	Encaminhe/Cco + responda de um registro	Não é um conector — veja E-mail

Sincronização, status & atualidade

• Agendamento. O Kordox re-sincroniza os conectores ativos automaticamente a cada ~6 horas.
• Sincronização manual. Dispare uma atualização a qualquer momento na linha de um conector (ou Sincronizar tudo de uma categoria). A sincronização manual apenas roda o mesmo puxão mais cedo.
• Status. Cada conector mostra a hora da última sincronização, o valor e a contagem de transações dos últimos 30 dias e a porcentagem atribuída.
• Requer atenção. Um conector com falha aparece no topo com o erro exato e um atalho Verificar / Sincronizar / Configurar. Erros transitórios do provedor são repetidos automaticamente e se resolvem sozinhos na próxima sincronização agendada.
• Histórico. O botão Histórico mostra as execuções de sincronização recentes e seus resultados.

O que cada conector precisa

Stripe — pagamentos

Sincroniza pagamentos, repasses, reembolsos e taxas no P&L por venture. Somente leitura.

• Permissões: uma chave de API restrita com leitura em Balance, Charges, Refunds, Subscriptions. (Adicione escrita em Checkout Sessions apenas se você ativar o faturamento de clientes — está desligado por padrão e não é necessário para a sincronização.)
• Passos: Stripe → Developers → API keys → crie uma chave restrita com os escopos acima → cole-a → Adicionar conta. O dinheiro é liquidado na sua conta Stripe; a chave não pode movimentá-lo.

Shopify — pedidos

Sincroniza os pedidos e reembolsos da sua loja como receita. Somente leitura.

• Permissões (OAuth): read_orders, read_products.
• Passos: digite seu domínio mystore.myshopify.com → Conectar via Shopify → aprove o acesso de leitura → você volta para cá e os pedidos sincronizam como receita.
• Você vai precisar de: uma conta de equipe com permissão para instalar apps.

PayPal — pagamentos

Sincroniza as transações do PayPal como receita.

• Permissões: um app REST do PayPal — seu Client ID + Secret (a Transaction Search é somente leitura).
• Passos: developer.paypal.com → Apps & Credentials → abra/crie um app REST → copie o Client ID + Secret → cole os dois → escolha Live (ou Sandbox) → salve.

Square — pagamentos

Sincroniza pagamentos e reembolsos do Square como receita.

• Permissões: um access token do Square (PAYMENTS_READ).
• Passos: developer.squareup.com → seu app → Credentials → copie o access token → cole-o, opcionalmente adicione um Location ID para limitar a um só local → escolha o ambiente → salve.

Plaid — saldos bancários

Conecta os saldos bancários para que o fôlego de caixa se baseie no caixa real.

• Permissões: Client ID + Secret do Plaid e um item access token do Plaid Link (produto Balance).
• Passos: copie o Client ID + Secret no painel do Plaid → use o Plaid Link para conectar o banco e obter um access token → cole os três → escolha o ambiente (production/sandbox) → salve.

Cloudflare — custo de infraestrutura

Acompanha o uso e os custos de faturamento da Cloudflare.

• Permissões: um token de API personalizado com uma única permissão — Account → Billing → Read, limitado à sua conta.
• Passos: Painel → Meu perfil → Tokens de API → Criar token (Billing Read) → copie-o → cole-o, junto com seu Account ID (barra lateral direita da Visão geral de qualquer domínio) → salve. O Kordox verifica na hora.

AWS Billing — custo de infraestrutura

Puxa o custo e uso da AWS para o P&L da venture certa.

• Permissões: um usuário/chave IAM com permissão para chamar ce:GetCostAndUsage (AWS Cost Explorer). A política gerenciada AWSBillingReadOnlyAccess cobre isso.
• Passos: IAM → anexe a política a um usuário → crie uma access key → cole o access key ID + secret → opcionalmente defina uma região (padrão us-east-1) → salve.

GCP Billing — custo de infraestrutura

Puxa os gastos do Google Cloud para que os custos de infraestrutura caiam no P&L da venture certa — por projeto GCP, por serviço, por dia.

• Conectar (um clique): escolha Conectar com sua conta Google e entre com a identidade dona do seu GCP. O Kordox detecta automaticamente sua conta de faturamento e a exportação do BigQuery — a maioria das configurações não exige digitar nada.
• Permissões (OAuth): cloud-billing.readonly + bigquery.readonly.
• O único passo manual no GCP: os dados de custo vêm da exportação para BigQuery do Cloud Billing, que só pode ser habilitada no console — Faturamento → Exportação de faturamento → Standard usage cost → escolha um projeto + dataset. Se ainda não estiver ativa, o checklist do conector leva você direto até lá. Os primeiros dados chegam ~24h após habilitar (sem preenchimento retroativo do histórico).
• Avançado (sem OAuth): cole uma chave JSON de conta de serviço com Billing Account Viewer + leitura do BigQuery — útil para contas de máquina.
• Mudou algo no GCP? Use Detectar novamente do Google no cartão para refazer a detecção automática e escolher a conta de faturamento certa.

Meta Ads — gasto com anúncios

Importa os gastos com anúncios da Meta (Facebook/Instagram) como custo para que margens e CAC sejam reais.

• Permissões (OAuth): ads_read.
• Passos: Conectar via OAuth → aprove o acesso de leitura → escolha a conta de anúncios a sincronizar → o gasto é importado como despesas.

Google Ads — gasto com anúncios

Importa os gastos do Google Ads como custo para margem e CAC reais.

• Permissões (OAuth): acesso de leitura aos seus dados do Google Ads; você vai confirmar o customer ID.
• Passos: Conectar via OAuth → aprove o acesso de leitura → selecione a conta / confirme o customer ID → o gasto é importado como despesas.

Anthropic (Claude) — IA & tokens

Acompanha o gasto da sua API do Claude e do workspace como custo de IA, por workspace — para que a conta de IA de cada venture seja real.

• Permissões: um papel de admin da organização e uma Admin API key (sk-ant-admin…). Uma chave de API comum não consegue ler o uso da organização. O Kordox lê apenas o relatório de custos diário.
• Passos: console.anthropic.com → Settings → Admin keys (não a página comum de chaves de API) → crie uma chave Admin → cole-a aqui.
• Atribuição: cada workspace do Claude mapeia para uma venture, exatamente como os projetos do GCP.

OpenAI — IA & tokens

Acompanha o gasto da sua API da OpenAI como custo de IA, por projeto.

• Permissões: um papel de owner/admin da organização e uma Admin API key (sk-admin…). O Kordox lê apenas os custos diários.
• Passos: platform.openai.com → Settings → Organization → Admin keys → crie uma chave admin → cole-a aqui.
• Atribuição: cada projeto da OpenAI mapeia para uma venture.

Atribuindo dinheiro às ventures

O Kordox roteia cada transação sincronizada para a venture a que ela pertence, para que o P&L por venture seja real em vez de "seja lá de que conta veio". Ambos os mecanismos são retroativos — o Kordox re-atribui o histórico existente quando você salva e re-sincroniza.

Mapeamento de origem — para provedores com sub-entidades bem definidas. Custos do GCP mapeiam por projeto de nuvem, a Cloudflare por conta, Claude/OpenAI por workspace/projeto. Edite em Finanças → Custos de nuvem → Atribuição.

Regras de atribuição — para provedores sem sub-entidades bem definidas (descritores do Stripe, memorandos bancários). Uma regra diz "a descrição contém X → venture Y": qualquer transação cuja descrição contenha esse texto (sem diferenciar maiúsculas de minúsculas) cai naquela venture; a primeira regra que corresponde vence. Edite em Finanças → Explorador de dinheiro → Regras de atribuição, depois Salvar & re-sincronizar.

Explorador de dinheiro

Finanças → Explorador de dinheiro fatia todo o dinheiro sincronizado — receita, infraestrutura, anúncios, IA, taxas — por categoria, provedor, origem, serviço, venture ou tipo, ao longo de qualquer período. Alterne entre Entradas, Saídas e Líquido, e exporte a visão atual como uma planilha Excel, um relatório PDF com a sua marca ou um CSV.

Solução de problemas

• "Requer atenção" com um erro de sincronização. Abra o texto do erro — agora ele inclui o status HTTP do provedor. 401/403 significa que a chave/token não tem um escopo obrigatório (recrie-a com as permissões listadas acima). Erros transitórios 5xx/de limite de taxa são repetidos automaticamente e somem na próxima sincronização agendada.
• Conectado, mas sem dados. Alguns provedores têm atraso: a exportação para BigQuery do GCP entrega os primeiros dados ~24h depois de você habilitá-la; os relatórios de custo de IA atrasam ~1–2 dias. Aguarde um ciclo e depois Sincronize.
• Custos na venture errada. Configure a atribuição e Salve & re-sincronize — isso re-atribui o histórico, não só os dados novos.
• A verificação falha na hora. A credencial está errada ou sem um escopo; o painel diz o que está faltando. Recrie a chave e cole-a de novo.