API do CRM da Vensy: contatos, empresas e negócios

Use a API do CRM para manter sistemas externos sincronizados com o workspace Vensy. O workspace é sempre derivado da API key: não envie tenantId no path, query ou payload.

Recurso do plano

Os endpoints exigem que a API do CRM esteja habilitada para o workspace, além do scope correspondente na chave.

Base URL

https://vensy.com.br/api/v1/integrations/crm

Recursos

Recurso	Operações
Contatos	listar, obter, criar, atualizar, arquivar e restaurar
Tags e campos	substituir tags ou campos personalizados de um contato
Empresas	listar, obter, criar, atualizar, arquivar e restaurar
Negócios	listar, obter, criar, atualizar, ganhar, perder e reabrir
Configuração	consultar pipelines, etapas, tags e definições de campos

Endpoints

Método	Caminho
`GET`, `POST`	`/contacts`
`GET`, `PATCH`, `DELETE`	`/contacts/{id}`
`POST`	`/contacts/{id}/restore`
`PUT`	`/contacts/{id}/tags`
`PUT`	`/contacts/{id}/custom-fields`
`GET`, `POST`	`/companies`
`GET`, `PATCH`, `DELETE`	`/companies/{id}`
`POST`	`/companies/{id}/restore`
`PUT`	`/companies/{id}/custom-fields`
`GET`, `POST`	`/deals`
`GET`, `PATCH`	`/deals/{id}`
`POST`	`/deals/{id}/won`, `/deals/{id}/lost`, `/deals/{id}/reopen`
`GET`	`/configuration`

Criar um contato

Toda escrita exige Idempotency-Key com 8 a 128 caracteres. Repetir a mesma chave e o mesmo payload devolve o resultado original; reutilizá-la com outro payload produz conflito.

curl -X POST https://vensy.com.br/api/v1/integrations/crm/contacts \
  -H "Authorization: Bearer vsk_live_SUA_CHAVE" \
  -H "Idempotency-Key: erp-contact-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneE164": "+5511999999999",
    "customName": "Maria Souza",
    "email": "maria@example.com",
    "ownerEmail": "vendedor@empresa.com",
    "tagIds": ["tag_id"],
    "customFields": { "customer_code": "ERP-42" }
  }'

ownerEmail deve pertencer a um membro ativo do workspace. Quando informado, o servidor resolve a membership sem expor IDs internos.

Coleções retornam { data, pagination: { nextCursor } }. Reenvie o cursor opaco sem interpretá-lo. Os filtros comuns são cursor, limit (1–100), q, archived e updatedAfter; contatos também aceitam phoneE164, email e tagId.

curl --get https://vensy.com.br/api/v1/integrations/crm/contacts \
  -H "Authorization: Bearer vsk_live_SUA_CHAVE" \
  --data-urlencode "email=cliente@empresa.com"

Comportamento importante

DELETE faz arquivamento lógico; use /restore para restaurar.
GET /deals exige pipelineId.
A tela do CRM organiza negócios. Criar um contato também materializa o negócio inicial para que ele apareça no board.
Alterar pipelineStageId no contato não move um card existente; mova-o com PATCH /deals/{id}.
Atualizações e transições de negócio resolvem a versão atual internamente; a integração não envia expectedVersion.

Erros

Os casos mais comuns são API_KEY_INVALID (401), API_KEY_SCOPE_REQUIRED (403), ENTITLEMENT_CRM_API_DISABLED (403), validação (400), recurso não encontrado (404) e conflito de idempotência ou versão (409). Consulte o catálogo de erros.

Para importar o contrato completo em ferramentas de desenvolvimento, use o OpenAPI JSON.

API do CRM