Conceitos Principais

Produto

Um Produto representa dados padronizados de uma instituição financeira com um conjunto específico de atributos. Exemplos: Contas Transações Investimentos Identidade Cartões de Crédito

Conector

Um Conector representa uma integração com uma instituição financeira específica. Cada conector tem um id único e um type:

Item

Um Item é a representação de uma conexão ativa entre um usuário e uma instituição financeira via um Conector específico. É o ponto de entrada para acessar todos os dados coletados daquele usuário naquela instituição.

API Key

Credencial de servidor com acesso total à API. Expira em 2 horas. Obtida via POST /auth com CLIENT_ID e CLIENT_SECRET. Nunca expor no frontend.

Connect Token

Credencial de cliente com escopo limitado. Expira em 30 minutos. Usada exclusivamente no Connect Widget. Criada pelo servidor via POST /connect_token usando a API Key.

Fluxo de Autenticação

Criar API Key

Autentique com CLIENT_ID e CLIENT_SECRET para obter uma API Key. Esta etapa deve ser feita exclusivamente no servidor.

curl -X POST https://api.kainow.app/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "SEU_CLIENT_ID",
    "clientSecret": "SEU_CLIENT_SECRET"
  }'Copiar

// Resposta 200 OK
{
  "apiKey": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJj..."
}

Usar a API Key

Passe a API Key no cabeçalho X-API-KEY em todas as requisições server-side:

X-API-KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Copiar

Criar Connect Token

O Connect Token tem escopo limitado e é seguro para usar no frontend. Validade de 30 minutos. Recomendado: 1 token por conexão.

curl -X POST https://api.kainow.app/v2/connect_token \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: SUA_API_KEY" \
  -d '{
    "options": {
      "webhookUrl": "https://meuapp.com/webhook",
      "clientUserId": "user_id_do_seu_sistema",
      "avoidDuplicates": true
    }
  }'Copiar

Opções do Connect Token

Listar Conectores

Filtros disponíveis

# Listar conectores sandbox
curl "https://api.kainow.app/v2/connectors?sandbox=true" \
  -H "X-API-KEY: SUA_API_KEY"Copiar

Conectores Sandbox

Para testes, use os conectores sandbox abaixo. Eles simulam todos os fluxos possíveis — MFA, erros, QR code, Open Finance.

Endpoints

Campos do Item

Como manter referência do Item

• Callback onSuccess do Widget: retorna item.id imediatamente após conexão
• Webhooks item/created: entrega o itemId e clientUserId de forma confiável
• Campo clientUserId: vincule o Item ao seu usuário passando esse campo no Connect Token

Auto-sincronização

Uma vez criado, o Item é sincronizado automaticamente pela plataforma no intervalo configurado (6h, 8h, 12h ou 24h). Você não precisa disparar updates manuais — apenas ouça os webhooks item/updated.

Status do Item

States de Execução (executionStatus)

Estados Transitórios

Estados Finais de Sucesso

Estados Finais de Erro

Retenção de Dados

Endpoints

curl "https://api.kainow.app/v2/accounts?itemId=SEU_ITEM_ID" \
  -H "X-API-KEY: SUA_API_KEY"Copiar

Tipos de Conta

Campos Principais

Endpoints

Paginação por Cursor

Use o campo next da resposta para paginar. Não use número de página.

let next = ''
const transactions = []

do {
  const res = await fetch(
    `https://api.kainow.app/v2/transactions${next}?accountId=ACCOUNT_ID`,
    { headers: { 'X-API-KEY': apiKey } }
  )
  const page = await res.json()
  transactions.push(...page.results)
  next = page.next  // null na última página
} while (next !== null)Copiar

Campos Principais

Delta Sync (Transações Novas)

Para buscar apenas transações novas após uma sincronização, use o webhook transactions/created que fornece o link direto via createdTransactionsLink.

Endpoints

Tipos de Investimento

Campos Principais

Endpoints

Campos Principais

Endpoints

Campos Retornados

Fluxo do Pix Automático

Endpoints

Webhooks do Pix Automático

Exemplo de Payload

{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "endToEndId": "E37943755202506111319U0da92d1b7e",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "automatic_pix_payment/completed"
}

Fluxo

Webhooks

Integração Básica

<!-- Incluir o script do widget -->
<script src="https://cdn.kainow.app/connect/v3/kainow-connect.js"></script>

<script>
  const connect = new KainowConnect({
    connectToken: 'SEU_CONNECT_TOKEN',
    
    // Callbacks
    onSuccess: ({ item }) => {
      console.log('Conectado! itemId:', item.id)
      salvarItemId(item.id)  // persista no seu backend
    },
    onError: ({ message, data }) => {
      console.error('Erro:', message, data?.item?.executionStatus)
    },
    onClose: () => console.log('Widget fechado'),
    onOpen:  () => console.log('Widget aberto')
  })
  
  connect.init()  // abre o modal
</script>Copiar

Configurações Disponíveis

Eventos (onEvent)

Como Configurar

Forneça um webhookUrl HTTPS em um desses momentos:

• Ao criar um Connect Token: options.webhookUrl
• Ao criar um Item: campo webhookUrl
• Ao criar uma Solicitação de Pagamento: campo webhookUrl
• Via endpoint POST /webhooks para registrar globalmente

Eventos de Item

Eventos de Transação

Eventos de Pagamento

Payload Padrão

{
  "event": "item/updated",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "a5c763cb-0952-457b-9936-630f79c5b016",
  "triggeredBy": "SYNC",
  "clientUserId": "seu-user-id"
}

Retentativas

IPs para Whitelist

52.67.145.81Copiar

Credenciais de Teste

Cenários de Teste

MFA — Cenários

Autenticação

Conectores

Items

Dados Financeiros

Pagamentos

Webhooks

Erros de Autenticação

Erros de Item

executionStatus — Referência Completa