Contatos

URL base da API
https://crm.vdgestaobranding.com/api/v1

A documentação fica em developers.vdgestaobranding.com, mas todas as chamadas vão para crm.vdgestaobranding.com/api/v1.

GET/contacts
contacts:read

Listar e buscar contatos

  • q — Busca por nome, telefone ou e-mail.
  • tag — Somente contatos com esta tag.
  • wa_id — Telefone exato.
  • opted_out — true/false.
  • limit — Itens por página (1–100, padrão 25).
  • cursor — Valor de next_cursor da página anterior.
curl -X GET "https://crm.vdgestaobranding.com/api/v1/contacts" \
  -H "Authorization: Bearer $VDCRM_API_KEY"
Resposta 200
{
  "data": [
    {
      "id": "c1d2…",
      "wa_id": "5511999998888",
      "name": "Maria Silva",
      "phone": "+5511999998888",
      "email": "maria@exemplo.com",
      "tags": [
        "vip"
      ],
      "custom_fields": {
        "cidade": "São Paulo"
      },
      "opt_in": true,
      "opt_in_source": "Formulário do site",
      "opted_out_at": null,
      "created_at": "2026-11-03T15:00:00Z"
    }
  ],
  "next_cursor": "WyIyMDI2…"
}
POST/contacts
contacts:write
Idempotency-Key

Criar contato

Para marcar opt_in é obrigatório informar opt_in_source (origem do consentimento).

curl -X POST "https://crm.vdgestaobranding.com/api/v1/contacts" \
  -H "Authorization: Bearer $VDCRM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "5511999998888",
  "name": "Maria Silva",
  "email": "maria@exemplo.com",
  "tags": [
    "vip"
  ],
  "custom_fields": {
    "cidade": "São Paulo"
  },
  "opt_in": true,
  "opt_in_source": "Formulário do site"
}'
Resposta 201
{
  "id": "c1d2…",
  "wa_id": "5511999998888",
  "name": "Maria Silva",
  "phone": "+5511999998888",
  "email": "maria@exemplo.com",
  "tags": [
    "vip"
  ],
  "custom_fields": {
    "cidade": "São Paulo"
  },
  "opt_in": true,
  "opt_in_source": "Formulário do site",
  "opted_out_at": null,
  "created_at": "2026-11-03T15:00:00Z"
}
POST/contacts/batch
contacts:write
Idempotency-Key

Criar/atualizar em lote

Até 1.000 contatos por chamada. Retorna um relatório por linha.

curl -X POST "https://crm.vdgestaobranding.com/api/v1/contacts/batch" \
  -H "Authorization: Bearer $VDCRM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "upsert": true,
  "contacts": [
    {
      "phone": "5511999998888",
      "name": "Maria"
    },
    {
      "phone": "123"
    }
  ]
}'
Resposta 200
{
  "created": 1,
  "updated": 0,
  "errors": 1,
  "results": [
    {
      "index": 0,
      "status": "created",
      "id": "c1d2…"
    },
    {
      "index": 1,
      "status": "error",
      "error": "Telefone inválido…"
    }
  ]
}
GET/contacts/{id}
contacts:read

Obter contato

curl -X GET "https://crm.vdgestaobranding.com/api/v1/contacts/{id}" \
  -H "Authorization: Bearer $VDCRM_API_KEY"
Resposta 200
{
  "id": "c1d2…",
  "wa_id": "5511999998888",
  "name": "Maria Silva",
  "phone": "+5511999998888",
  "email": "maria@exemplo.com",
  "tags": [
    "vip"
  ],
  "custom_fields": {
    "cidade": "São Paulo"
  },
  "opt_in": true,
  "opt_in_source": "Formulário do site",
  "opted_out_at": null,
  "created_at": "2026-11-03T15:00:00Z"
}
PATCH/contacts/{id}
contacts:write

Atualizar contato

custom_fields é mesclado com os campos existentes.

curl -X PATCH "https://crm.vdgestaobranding.com/api/v1/contacts/{id}" \
  -H "Authorization: Bearer $VDCRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Maria S.",
  "custom_fields": {
    "plano": "ouro"
  }
}'
Resposta 200
{
  "id": "c1d2…",
  "wa_id": "5511999998888",
  "name": "Maria Silva",
  "phone": "+5511999998888",
  "email": "maria@exemplo.com",
  "tags": [
    "vip"
  ],
  "custom_fields": {
    "cidade": "São Paulo"
  },
  "opt_in": true,
  "opt_in_source": "Formulário do site",
  "opted_out_at": null,
  "created_at": "2026-11-03T15:00:00Z"
}
DELETE/contacts/{id}
contacts:write

Excluir contato

curl -X DELETE "https://crm.vdgestaobranding.com/api/v1/contacts/{id}" \
  -H "Authorization: Bearer $VDCRM_API_KEY"
POST/contacts/{id}/tags
contacts:write

Adicionar/remover tags

curl -X POST "https://crm.vdgestaobranding.com/api/v1/contacts/{id}/tags" \
  -H "Authorization: Bearer $VDCRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "add": [
    "cliente"
  ],
  "remove": [
    "lead"
  ]
}'
Resposta 200
{
  "id": "c1d2…",
  "wa_id": "5511999998888",
  "name": "Maria Silva",
  "phone": "+5511999998888",
  "email": "maria@exemplo.com",
  "tags": [
    "vip"
  ],
  "custom_fields": {
    "cidade": "São Paulo"
  },
  "opt_in": true,
  "opt_in_source": "Formulário do site",
  "opted_out_at": null,
  "created_at": "2026-11-03T15:00:00Z"
}
POST/contacts/{id}/opt-out
contacts:write

Registrar opt-out

O contato deixa de receber campanhas e modelos.

curl -X POST "https://crm.vdgestaobranding.com/api/v1/contacts/{id}/opt-out" \
  -H "Authorization: Bearer $VDCRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "source": "Pediu pelo SAC"
}'
Resposta 200
{
  "id": "c1d2…",
  "wa_id": "5511999998888",
  "name": "Maria Silva",
  "phone": "+5511999998888",
  "email": "maria@exemplo.com",
  "tags": [
    "vip"
  ],
  "custom_fields": {
    "cidade": "São Paulo"
  },
  "opt_in": false,
  "opt_in_source": "Formulário do site",
  "opted_out_at": "2026-11-03T15:10:00Z",
  "created_at": "2026-11-03T15:00:00Z"
}
POST/contacts/{id}/opt-in
contacts:write

Registrar opt-in

curl -X POST "https://crm.vdgestaobranding.com/api/v1/contacts/{id}/opt-in" \
  -H "Authorization: Bearer $VDCRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "source": "Checkbox no checkout"
}'
Resposta 200
{
  "id": "c1d2…",
  "wa_id": "5511999998888",
  "name": "Maria Silva",
  "phone": "+5511999998888",
  "email": "maria@exemplo.com",
  "tags": [
    "vip"
  ],
  "custom_fields": {
    "cidade": "São Paulo"
  },
  "opt_in": true,
  "opt_in_source": "Formulário do site",
  "opted_out_at": null,
  "created_at": "2026-11-03T15:00:00Z"
}