> ## 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.

# Contatos

> Criar, atualizar, consultar e apagar contatos via API externa

# Contatos

Identifique o contato com **`external_id`**, **`document`** ou **`phone`** (pelo menos um). Ordem de busca: `external_id` → `document` → `phone` (telefone normalizado BR).

Na criação, `name` e `phone` são obrigatórios.

<Warning>
  Não envie `peti9_id` numérico (**400**). Use `external_id` como texto opaco do seu ERP.
</Warning>

Veja também a [política de sincronização](/flow/api-reference/sync-policy) (`flow` vs `erp`).

## `PUT …/contacts` — upsert

Scope: `contacts:write`

```http theme={null}
PUT https://api.connectvets.com.br/flow/v1/external/workspaces/{workspace_id}/contacts
Authorization: Bearer flow_live_<secret>
Content-Type: application/json

{
  "external_id": "erp-cust-8821",
  "document": "12345678901",
  "phone": "+5511999999999",
  "name": "Maria",
  "email": "maria@example.com",
  "address": "Rua Exemplo, 100",
  "source": "ERP"
}
```

### Campos

| Campo                                           | Tipo   | Criar                  | Atualizar                            | Limpar (`null`)       |
| ----------------------------------------------- | ------ | ---------------------- | ------------------------------------ | --------------------- |
| `external_id`                                   | string | Opcional               | Define/atualiza                      | Limpa coluna anulável |
| `document`                                      | string | Opcional               | Define/atualiza                      | Limpa                 |
| `phone`                                         | string | Obrigatório na criação | Normalizado BR; **409** se duplicado | —                     |
| `name`                                          | string | Obrigatório na criação | Conforme política flow/erp           | —                     |
| `email`, `address`, `source`, `profile_pic_url` | string | Opcional               | Conforme política                    | Limpa                 |

### Códigos HTTP

| Código | Significado                               |
| ------ | ----------------------------------------- |
| 200    | Contato atualizado                        |
| 201    | Contato criado (ou restaurado)            |
| 400    | Dados inválidos ou campo legado rejeitado |
| 401    | Token ausente ou inválido                 |
| 403    | Sem permissão, workspace ou billing       |
| 409    | Telefone ou `external_id` duplicado       |

### Warnings

Resposta **2xx** significa que o contato foi gravado. Se houver `warnings`, nome ou telefone do payload podem não ter sido aplicados (política Flow):

* `name_not_applied_user_edited_in_flow`
* `phone_not_applied_user_edited_in_flow`

### cURL completo

```bash theme={null}
export FLOW_BASE_URL="https://api.connectvets.com.br/flow/v1"
export TOKEN="flow_live_<cole_aqui>"
export WORKSPACE_ID="$(curl -sS "$FLOW_BASE_URL/external/me" -H "Authorization: Bearer $TOKEN" | jq -r .workspace_id)"

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"}'
```

## Consultar e apagar

### `GET …/contacts/:contact_id`

Scope: `contacts:read` — devolve uma projeção limitada do contato (sem pets, `peti9_id`, etc.).

```http theme={null}
GET https://api.connectvets.com.br/flow/v1/external/workspaces/{workspace_id}/contacts/{contact_id}
Authorization: Bearer flow_live_<secret>
```

### `DELETE …/contacts/:contact_id`

Scope: `contacts:delete` — soft-delete; responde **204** mesmo se o contato já estiver apagado (idempotente).

```http theme={null}
DELETE https://api.connectvets.com.br/flow/v1/external/workspaces/{workspace_id}/contacts/{contact_id}
Authorization: Bearer flow_live_<secret>
```

## Auditoria

Cada PUT/DELETE externo bem-sucedido gera auditoria (`contact_external_api_audit_logs`, retenção **90 dias**). Admins veem o histórico no modal do contato no CRM.