> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pierre.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Open Finance Connection Flow

> Inicia o fluxo de conexão Open Finance via WhatsApp. Para usuários Premium, envia um fluxo interativo com lista de bancos. Para usuários Basic/Pro, envia notificação de acesso limitado. Requer API key para autenticação e assinatura ativa.

<Note>
  Este endpoint inicia o fluxo de conexão Open Finance via WhatsApp com funcionalidades baseadas no plano do usuário.
</Note>

## Descrição

O endpoint `GET /tools/api/get-open-finance-connection-flow` permite que usuários conectem suas contas bancárias através do Open Finance diretamente pelo WhatsApp. A experiência varia conforme o plano:

* **Premium**: Fluxo interativo completo com lista de bancos disponíveis
* **Basic/Pro**: Notificação sobre limitações do plano e sugestão de upgrade

## Autenticação

Este endpoint requer autenticação via Bearer token.

<ParamField header="Authorization" type="string" required>
  Bearer token com a API key do usuário. Formato: `Bearer sk-your-api-key-here`
</ParamField>

## Parâmetros de Query

<ParamField query="s" type="string" required="false">
  Parâmetro interno para indicar requisições via MCP. Use `s=s` para requisições MCP.
</ParamField>

## Resposta

### Sucesso (200)

<ResponseExample>
  ```json Success - Fluxo Enviado theme={null}
  {
    "status": "accepted",
    "message": "WhatsApp flow sent successfully"
  }
  ```
</ResponseExample>

### Erro de Dados Incompletos (400)

<ResponseExample>
  ```json Error theme={null}
  {
    "error": "User phone number is required for WhatsApp operations"
  }
  ```
</ResponseExample>

### Erro de Autenticação (401)

<ResponseExample>
  ```json Error theme={null}
  {
    "error": "Invalid or inactive API key",
    "message": "Please check your API key and try again",
    "type": "invalid_api_key"
  }
  ```
</ResponseExample>

## Campos da Resposta

<ResponseField name="status" type="string" required>
  Status da operação: `accepted` indica que a mensagem foi aceita pelo WhatsApp
</ResponseField>

<ResponseField name="message" type="string" required>
  Mensagem descritiva sobre o status da operação
</ResponseField>

## Exemplos de Uso

### cURL

```bash theme={null}
# Iniciar fluxo de conexão
curl -X GET 'https://www.pierre.finance/tools/api/get-open-finance-connection-flow' \
  -H 'Authorization: Bearer sk-your-api-key-here'
```

### JavaScript

```javascript theme={null}
const API_KEY = 'sk-your-api-key-here';
const BASE_URL = 'https://www.pierre.finance/tools/api';

async function initiateConnectionFlow() {
  const response = await fetch(`${BASE_URL}/get-open-finance-connection-flow`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
}

// Exemplo de uso
initiateConnectionFlow()
  .then(result => console.log('Fluxo iniciado:', result.message))
  .catch(error => console.error('Erro:', error));
```

### Python

```python theme={null}
import requests

API_KEY = 'sk-your-api-key-here'
BASE_URL = 'https://www.pierre.finance/tools/api'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

def initiate_connection_flow():
    response = requests.get(f'{BASE_URL}/get-open-finance-connection-flow',
                          headers=headers)
    return response.json()

# Exemplo de uso
try:
    result = initiate_connection_flow()
    print(f'Fluxo iniciado: {result["message"]}')
except Exception as error:
    print(f'Erro: {error}')
```

## Códigos de Status

* `200`: Sucesso - Fluxo WhatsApp enviado
* `400`: Dados do usuário incompletos (número de telefone não cadastrado)
* `401`: Erro de autenticação ou assinatura
* `500`: Erro interno do servidor

## Experiência por Plano

### Plano Premium

Usuários Premium recebem um fluxo interativo completo via WhatsApp contendo:

* Lista de bancos disponíveis para conexão
* Interface de seleção integrada
* Instruções passo a passo
* Conexão direta com as instituições financeiras

### Planos Basic e Pro

Usuários Basic e Pro recebem uma notificação via WhatsApp informando:

* Que a funcionalidade está disponível apenas no plano Premium
* Benefícios do upgrade para Premium
* Link para fazer upgrade
* Informações de contato para suporte

## Requisitos

### Configuração Necessária

Para usar este endpoint, o usuário precisa ter:

1. Número de telefone cadastrado e verificado
2. WhatsApp Business API configurado para a conta
3. Assinatura ativa (qualquer plano)

### Bancos Suportados (Premium)

O fluxo Premium oferece conexão com os principais bancos brasileiros via Open Finance:

* Nubank
* Itaú
* Bradesco
* Banco do Brasil
* Santander
* Caixa Econômica Federal
* Inter
* E outros participantes do Open Finance

## Casos de Uso

### Onboarding de Usuários

Integre este endpoint no fluxo de onboarding para facilitar a conexão de contas bancárias.

### Reconexão de Contas

Use quando contas precisarem ser reconectadas devido a vencimento de tokens ou mudança de credenciais.

### Adicionar Novas Contas

Permita que usuários adicionem novas contas bancárias a qualquer momento.

### Chatbot de Suporte

Integre em chatbots para permitir que usuários iniciem a conexão através de conversas.

<Note>
  O fluxo é enviado via WhatsApp Business API. O usuário precisa ter um número de telefone válido cadastrado em sua conta Pierre Finance.
</Note>

<Tip>
  Para uma melhor experiência do usuário, certifique-se de que o número de telefone está cadastrado e verificado antes de chamar este endpoint.
</Tip>

<Warning>
  Este endpoint dispara uma mensagem via WhatsApp. Evite chamadas excessivas para não gerar spam para o usuário. Implemente debouncing ou rate limiting no seu código.
</Warning>

## Segurança

### Open Finance

A conexão via Open Finance é segura e regulamentada pelo Banco Central do Brasil:

* Autenticação forte (multi-fator)
* Criptografia end-to-end
* Consentimento explícito do usuário
* Prazo de validade dos acessos
* Auditoria completa de acessos

### Privacidade

* Credenciais bancárias nunca são armazenadas
* Tokens de acesso são temporários e renováveis
* Dados são criptografados em repouso e em trânsito
* Conformidade com LGPD

## Upgrade para Premium

Para acessar o fluxo completo de conexão:

1. Acesse [pierre.finance/plans](https://pierre.finance/plans)
2. Selecione o plano Premium
3. Complete o upgrade
4. Reinicie o fluxo de conexão

Benefícios do Premium incluem:

* ✅ Conexão via Open Finance integrada
* ✅ Até 30 lembretes de pagamento
* ✅ Até 30 alertas de gastos
* ✅ Suporte prioritário
* ✅ Análises avançadas


## OpenAPI

````yaml GET /tools/api/get-open-finance-connection-flow
openapi: 3.1.0
info:
  title: Pierre Finance API
  description: >-
    API para acessar dados financeiros do Pierre Finance, incluindo contas,
    transações, parcelas e sincronização.
  version: v1.0.0
servers:
  - url: https://www.pierre.finance
security: []
tags:
  - name: Authentication
    description: API key management and authentication
  - name: Accounts
    description: Financial accounts management
  - name: Transactions
    description: Financial transactions
  - name: Installments
    description: Credit card installments and purchases
  - name: Bills
    description: Credit card bills and current bill summaries
  - name: Balance
    description: Account balance information
  - name: Closing Dates
    description: Credit card closing date management
  - name: Sync
    description: Account synchronization
  - name: Spending Limits
    description: Personal spending limits and alerts management
  - name: Payment Reminders
    description: Payment reminders management with WhatsApp and Email notifications
  - name: Analytics
    description: Financial analytics and insights
  - name: Memories
    description: User memory management for personalized AI interactions
  - name: Open Finance
    description: Open Finance connection and integration
paths:
  /tools/api/get-open-finance-connection-flow:
    get:
      tags:
        - Open Finance
      description: >-
        Inicia o fluxo de conexão Open Finance via WhatsApp. Para usuários
        Premium, envia um fluxo interativo com lista de bancos. Para usuários
        Basic/Pro, envia notificação de acesso limitado. Requer API key para
        autenticação e assinatura ativa.
      operationId: getOpenFinanceConnectionFlow
      responses:
        '200':
          description: Fluxo iniciado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: accepted
                  message:
                    type: string
                    example: WhatsApp flow sent successfully
        '400':
          description: Dados do usuário incompletos
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: User phone number is required for WhatsApp operations
        '401':
          $ref: '#/components/responses/AuthError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  responses:
    AuthError:
      description: Authentication or subscription error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerError'
  schemas:
    AuthError: {}
    ServerError: {}
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string
      description: 'API key in Bearer token format. Example: Bearer sk-your-api-key-here'

````