LinkZap

Primeiros passos

.md

Para agentes de IA

Se você é uma IA: este é o roteiro inteiro para operar o LinkZap sozinha. Você só precisa pedir uma credencial ao usuário.

1. Peça a credencial

  1. Chave de API (o caminho mais simples). Peça ao usuário: *"Abra o LinkZap › Configurações › Integrações › Conectar uma IA e me passe o bloco que aparecer"*. A chave começa com lz_ e vale como ele: você pode no LinkZap exatamente o que ele pode.
  2. Login (OAuth), se você é um cliente MCP (claude.ai, ChatGPT): conecte https://linkzap.ia.br/mcp. O servidor anuncia a autorização sozinho (401 com WWW-Authenticate), e o usuário entra e escolhe a organização.

Nunca no navegador

A chave dá acesso à conta inteira de quem a criou. Guarde-a só no seu ambiente de servidor e não a repita na conversa além do necessário.

2. Descubra o que dá para fazer

Confira a chave com GET https://linkzap.ia.br/api/v1/me. Depois liste as ações com GET https://linkzap.ia.br/api/v1/actions (ou o catálogo público em https://linkzap.ia.br/actions.json, que dá para ler antes de ter a chave). Cada ação tem um nome área.verbo e GET /api/v1/actions/{nome} devolve o JSON Schema da entrada.

Descobrircurl
curl https://linkzap.ia.br/api/v1/actions?area=contacts -H "Authorization: Bearer lz_SUA_CHAVE"

curl https://linkzap.ia.br/api/v1/actions/tags.create -H "Authorization: Bearer lz_SUA_CHAVE"

3. Execute

Executarcurl
curl -X POST https://linkzap.ia.br/api/v1/actions/tags.create \
  -H "Authorization: Bearer lz_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Cliente VIP", "color": "success" }'
  • Sucesso: 200 com { "data": … }. Recusa: { "error": "…" } em português, com o status: 422 (entrada inválida, com issues), 403 (sem permissão), 404 (não existe).
  • Leia antes de escrever: a maioria das ações pede ids que vêm de uma leitura (contacts.list, pipelines.list, channels.list…).
  • Fluxos e agentes se editam lendo a definição (flows.get, agents.get), mudando e gravando com a MESMA version. Agente só atende depois de agents.publish.
  • Freio: o mesmo da API. Um 429 traz Retry-After.

Por MCP é igual: as ferramentas listActions, describeAction e runAction fazem os três passos, ao lado das operações diretas da API.

O que fica de fora

Apagar a organização, assinar ou cancelar o plano, e a conta pessoal (senha, foto) só pelo painel, por quem é dono deles. Criar a conta também é no site.