Modelo para parceiros

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.

Para empresas que oferecem o VD CRM dentro do próprio sistema e atendem vários clientes finais. Cada cliente final é uma operação: dados, números, WABA e envios ficam isolados nela.

Chaves de conta (vdk_acct_live_… / vdk_acct_test_…) são criadas só pelo owner da conta, em Configurações → API → Chaves de conta, nos planos Agência e Enterprise. Escopos:

operations:manage — Criar, listar, atualizar e arquivar operações
keys:manage — Emitir e revogar chaves por operação
embed:create — Criar sessões de embed em qualquer operação da conta
members:manage — Criar e atualizar usuários e perfis por operação
connect:create — Gerar links de conexão de número

Regras: a chave de conta nunca acessa outra conta. Toda chamada que mexe em dados leva a operação no caminho (/operations/{id}/…) e o servidor confere que ela pertence à conta antes de executar. Uma chave ou sessão de operação nunca enxerga outra operação, mesmo que seu sistema erre nas regras dele. Uma chave de conta de teste só emite chaves de operação de teste. Todas as chamadas aparecem nos registros da API.

GET	/operations	Listar (filtro ?external_id=)
POST	/operations	Criar (respeita o limite do plano)
GET	/operations/{id}	Obter
PATCH	/operations/{id}	Atualizar nome, cor, ícone, CNPJ, external_id
POST	/operations/{id}/archive	Arquivar
POST	/operations/{id}/restore	Restaurar
GET	/operations/{id}/keys	Listar chaves da operação
POST	/operations/{id}/keys	Emitir chave da operação
DELETE	/operations/{id}/keys/{keyId}	Revogar chave
POST	/operations/{id}/embed/sessions	Sessão de embed
POST	/operations/{id}/connect-sessions	Link de conexão de número
GET	/operations/{id}/members	Membros com acesso
POST	/operations/{id}/members	Convidar (admin ou atendente)
PATCH	/operations/{id}/members/{userId}	Mudar perfil
DELETE	/operations/{id}/members/{userId}	Remover acesso do atendente a esta operação

Fluxo completo

# Chave de conta (só no seu servidor)
export VDCRM_ACCOUNT_KEY=vdk_acct_live_…

# 1) Criar a operação do cliente final, ligada ao seu cadastro
curl -X POST https://crm.vdgestaobranding.com/api/v1/operations \
  -H "Authorization: Bearer $VDCRM_ACCOUNT_KEY" -H "Idempotency-Key: cliente-42" \
  -H "Content-Type: application/json" \
  -d '{"name":"Loja do Cliente 42","external_id":"cliente-42"}'
# → { "id": "OP_ID", "external_id": "cliente-42", ... }

# 2) Link de conexão do número (uso único, 30 min)
curl -X POST https://crm.vdgestaobranding.com/api/v1/operations/OP_ID/connect-sessions -H "Authorization: Bearer $VDCRM_ACCOUNT_KEY"
# → { "url": "https://crm.vdgestaobranding.com/conectar/…" }  (webhook phone_number.connected ao concluir)

# 3a) Chave só desta operação (para o back-end do cliente final)
curl -X POST https://crm.vdgestaobranding.com/api/v1/operations/OP_ID/keys -H "Authorization: Bearer $VDCRM_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cliente 42","scopes":["inbox:read","inbox:write","contacts:write","webhooks:manage"]}'
# → { "key": "vdk_live_…" }  (exibida uma única vez)

# 3b) Ou uma sessão de embed por usuário final
curl -X POST https://crm.vdgestaobranding.com/api/v1/operations/OP_ID/embed/sessions -H "Authorization: Bearer $VDCRM_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id":"u-7","name":"Ana","phone_number_refs":["PHONE_ID"],"modules":["inbox"],"permissions":["inbox:read","inbox:reply"]}'

# 4) Webhooks por operação: use a chave da operação (escopo webhooks:manage)
curl -X POST https://crm.vdgestaobranding.com/api/v1/webhooks -H "Authorization: Bearer vdk_live_…" -H "Content-Type: application/json" \
  -d '{"url":"https://seu-sistema.com/vdcrm/42","events":["message.received","phone_number.connected"]}'