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.

Não envie peti9_id numérico (400). Use external_id como texto opaco do seu ERP.

Veja também a política de sincronização (flow vs erp).

`PUT …/contacts` — upsert

Scope: contacts:write

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": "[email protected]",
  "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

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

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

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.

Começar

Workspaces

Contatos

Pesquisa de satisfação

Eventos

Inteligência artificial

Referência

Contatos

Contatos

`PUT …/contacts` — upsert

Campos

Códigos HTTP

Warnings

cURL completo

Consultar e apagar

`GET …/contacts/:contact_id`

`DELETE …/contacts/:contact_id`

Auditoria

​Contatos

​PUT …/contacts — upsert

​Campos

​Códigos HTTP

​Warnings

​cURL completo

​Consultar e apagar

​GET …/contacts/:contact_id

​DELETE …/contacts/:contact_id

​Auditoria

Contatos

`PUT …/contacts` — upsert

Campos

Códigos HTTP

Warnings

cURL completo

Consultar e apagar

`GET …/contacts/:contact_id`

`DELETE …/contacts/:contact_id`

Auditoria