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

# Início rápido

> Primeira integração com a API externa do Flow em quatro passos

# Início rápido — Flow

Quatro passos para a primeira integração funcionar.

## 1. Crie uma API key

No Flow CRM: **Integrações → Acesso à API → Gerenciar chaves**.

Escolha os scopes necessários, por exemplo:

* `contacts:write`
* `satisfaction:write`
* `mcp:read`

Copie o token `flow_live_…` na hora — ele só aparece uma vez. Guarde em um cofre de segredos.

## 2. Descubra o workspace

```bash theme={null}
export FLOW_BASE_URL="https://api-sandbox.connectvets.com.br/flow/v1"
export TOKEN="flow_live_<cole_aqui>"

curl -sS "$FLOW_BASE_URL/external/me" \
  -H "Authorization: Bearer $TOKEN"
```

A resposta inclui `workspace_id`. Guarde-o para as demais rotas (ou resolva dinamicamente com o mesmo `GET`).

## 3. Upsert de contato

```bash theme={null}
export WORKSPACE_ID="<uuid>"

curl -sS -X PUT "$FLOW_BASE_URL/external/workspaces/$WORKSPACE_ID/contacts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"erp-1","document":"12345678901","name":"João","phone":"+5511987654321"}'
```

## 4. Pesquisa, webhooks ou MCP

* Pesquisa: [`POST …/satisfaction-surveys`](/flow/api-reference/satisfaction-surveys)
* Webhooks: configure em Integrações → Webhooks ([guia](/flow/webhooks))
* Agentes de IA: [MCP](/flow/mcp)

<Tip>
  Importante: não use a URL do front-end (CRM) nas integrações. Use o gateway (`/flow/v1`). Workspace com billing inativo bloqueia a API (403).
</Tip>