gensAPI

Início rápido

Comece com uma consulta de leitura. Esta página só oferece exemplos: não recebe sua chave nem executa chamadas autenticadas no navegador.

1. Crie uma chave no CRM#

Entre no CRM com o usuário proprietário da clínica.
Abra Configurações → API → Criar API Key.
Escolha o preset Somente leitura e uma validade adequada ao teste.
Salve a chave em um cofre de segredos. Ela aparece uma única vez.

Nunca cole a chave em chat, ticket, e-mail, código versionado ou bloco de notas sem proteção.

2. Carregue a chave no PowerShell#

Execute no seu computador confiável ou servidor. O prompt oculto evita deixar a chave literal no histórico de comandos. A variável dura apenas nessa sessão; não use um terminal com gravação de sessão.

powershell

$chaveProtegida = Read-Host "API Key da clínica" -AsSecureString
$env:GENS_CLINIC_API_KEY = [System.Net.NetworkCredential]::new("", $chaveProtegida).Password
$chaveProtegida.Dispose()
$headers = @{ Authorization = "Bearer $env:GENS_CLINIC_API_KEY" }

3. Faça uma consulta de leitura#

powershell

$pagina = Invoke-RestMethod -Method Get -Headers $headers -Uri "https://api.crm.agenciagens.com.br/v1/contacts?limit=5"
$pagina.data.Count

Esperado: JSON com até cinco contatos da clínica e next_cursor na raiz. Uma lista vazia é um resultado válido. O exemplo mostra só a quantidade para não registrar dados pessoais no terminal.

Sem chave, a resposta esperada é 401 invalid_api_key; isso prova recusa de acesso anônimo, não confirma que todas as funções estão operacionais. Para 401, 403 ou outros erros, consulte o guia de recuperação.

Consultar vendas pelo telefone#

contact_id é UUID, não telefone. A busca pesquisa também nome e e-mail, então confira o campo phone e todas as páginas. Use telefone completo com país e DDD. Não invente dígitos se a informação estiver incompleta.

powershell

$telefone = "5511999999999" # Exemplo fictício: substitua pelo telefone autorizado.
$telefoneNormalizado = $telefone -replace "\D", ""
$busca = [uri]::EscapeDataString($telefoneNormalizado)
$correspondencias = @{}
$cursor = $null
$paginasLidas = 0

do {
  $uri = "https://api.crm.agenciagens.com.br/v1/contacts?search=$busca&limit=100"
  if ($cursor) { $uri += "&cursor=$([uri]::EscapeDataString($cursor))" }
  $pagina = Invoke-RestMethod -Method Get -Uri $uri -Headers $headers
  foreach ($contato in $pagina.data) {
    if (($contato.phone -replace "\D", "") -eq $telefoneNormalizado) {
      $correspondencias[$contato.id] = $contato
    }
  }
  $cursor = $pagina.next_cursor
  $paginasLidas++
  # Evita uma varredura ilimitada: não prosseguir com uma busca incompleta.
  if ($cursor -and $paginasLidas -ge 20) {
    throw "Busca extensa; refine os dados e peça revisão humana."
  }
} while ($cursor)

if ($correspondencias.Count -ne 1) {
  throw "Não há exatamente um contato com esse telefone. Confirme no CRM."
}

$contactId = @($correspondencias.Keys)[0]
$vendas = Invoke-RestMethod -Method Get -Headers $headers -Uri "https://api.crm.agenciagens.com.br/v1/contacts/$contactId/sales?limit=50"
$vendas.data.Count

O resultado de vendas também é paginado: continue pelo next_cursor para ler as demais páginas. Guarde o UUID confirmado junto à identificação da integração/clínica. Não reutilize IDs entre clínicas.

Registrar uma venda real#

Esta etapa altera dados. Só execute com autorização, contato confirmado e chave com contacts:read e contacts:write. Não faça uma venda fictícia em produção. A ação entra no histórico e faturamento e pode gerar conversão na Meta conforme a configuração.

Consulte a versão atual e prepare uma operação lógica:

powershell

$contatoAtual = Invoke-RestMethod -Method Get -Headers $headers -Uri "https://api.crm.agenciagens.com.br/v1/contacts/$contactId"
$chaveDaOperacao = [guid]::NewGuid().ToString()
$corpoDaVenda = @{
  service_name = "Serviço efetivamente vendido"
  value = "350.00"
  expected_updated_at = $contatoAtual.data.updated_at
} | ConvertTo-Json
$headersDaVenda = @{
  Authorization = "Bearer $env:GENS_CLINIC_API_KEY"
  "Idempotency-Key" = $chaveDaOperacao
}

Depois de confirmar valor, serviço e contato, envie:

powershell

$recibo = Invoke-RestMethod -Method Post -Uri "https://api.crm.agenciagens.com.br/v1/contacts/$contactId/sales" -Headers $headersDaVenda -ContentType "application/json" -Body $corpoDaVenda

Sem sold_at, a data é o momento do registro. O recibo contém o ID da venda; consulte as vendas para conferir. Em retry, repita somente o envio, preservando chave e corpo; não gere outro UUID. Nunca use PATCH lifetime_value para simular uma venda. Veja idempotência.

Node.js no servidor#

Carregue a variável por um cofre ou ambiente protegido antes de iniciar o processo.

javascript

const apiKey = process.env.GENS_CLINIC_API_KEY;
if (!apiKey) throw new Error("Configure a API Key no ambiente do servidor.");
const response = await fetch("https://api.crm.agenciagens.com.br/v1/contacts?limit=5", {
  headers: { Authorization: `Bearer ${apiKey}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}; confira o guia de erros.`);
const pagina = await response.json();
// Processe pagina.data sem registrar dados pessoais em logs.

Encerrar o teste#

Se a chave foi criada apenas para esse teste, revogue-a em Configurações → API. Não revogue uma chave usada por outra integração. Limpe o segredo desta sessão:

powershell

$headers.Clear()
if ($headersDaVenda) { $headersDaVenda.Clear() }
Remove-Item Env:GENS_CLINIC_API_KEY -ErrorAction SilentlyContinue

A revogação deve fazer novas consultas com aquela chave retornarem 401. Limpar a variável local, sozinho, não revoga a credencial.