Chaves de API

Visão geral

Chaves de API fornecem aos seus sistemas externos acesso programático e seguro à plataforma ZappWay. Com uma chave de API, você pode automatizar as interações dos agentes, gerenciar armazenamentos de dados, consultar dados de contatos, recuperar registros de conversas e muito mais, tudo sem tocar manualmente no painel. Para acessar chaves de API:

ZappWay Dashboard
└── Sidebar Menu → Settings → API Keys
    ├── Active Keys (list, copy, revoke)
    └── Create API Key

Casos de uso comuns:

Incorporação da IA do ZappWay em seu próprio aplicativo personalizado ou aplicativo móvel
Sincronizando seus bancos de dados internos com datastores ZappWay automaticamente
Exportação de leads e registros de conversas para seu CRM em tempo real
Acionar consultas de agentes a partir de seus próprios fluxos de trabalho de back-end

Gerenciando chaves de API

Gerando uma nova chave

ZappWay gera chaves de API aleatórias e criptograficamente seguras. Para criar um:

Navigate to Settings → API Keys
Click Create API Key
Optionally give the key a descriptive label (e.g., “CRM Integration”, “Mobile App”, “Zapier Webhook”)
The key is displayed immediately in the list
Click the copy icon to save it to your clipboard

Trate sua chave de API como uma senha. Ela concede acesso programático total à sua organização ZappWay. Nunca exponha-o em código do lado do cliente, repositórios públicos, JavaScript do navegador ou qualquer ambiente acessível aos usuários finais. Armazene-o com segurança usando variáveis de ambiente ou um gerenciador de segredos.

Visualizando chaves existentes

A página Chaves de API lista todas as chaves ativas associadas à sua organização. Por segurança, o valor completo da chave é mostrado apenas uma vez — imediatamente após a criação. Depois disso, apenas os últimos caracteres ficam visíveis para fins de identificação. Se você perder uma chave, não poderá recuperá-la. Você deve revogá-lo e gerar um novo.

Revogando uma chave

Para invalidar permanentemente uma chave de API:

Navigate to Settings → API Keys
Click the trash icon next to the key you want to revoke
Confirm the deletion in the dialog

O que acontece após a revogação:

A chave para de funcionar imediatamente
Qualquer serviço ou integração que use essa chave começará a falhar com erros 401 Unauthorized
A revogação é permanente e não pode ser desfeita

Se você suspeitar que uma chave foi comprometida, revogue-a imediatamente e gere uma substituição. Atualize todas as integrações usando a chave antiga antes que a nova seja implantada.

Autenticação

Todas as solicitações de API para ZappWay devem incluir sua chave de API no cabeçalho Authorization usando o formato de token de portador:

Authorization: Bearer YOUR_API_KEY

Exemplo de solicitação usando curl:

curl -X GET https://app.zappway.ai/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Exemplo de solicitação usando JavaScript (Node.js): CÓDIGO_BLOCO_3 Exemplo de solicitação usando Python:

import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['ZAPPWAY_API_KEY']}",
    "Content-Type": "application/json"
}

response = requests.get("https://app.zappway.ai/api/v1/agents", headers=headers)
data = response.json()

##URL base Todos os endpoints da API estão disponíveis no seguinte URL base:

https://app.zappway.ai/api

Endpoints versionados (recomendados para integrações de produção):

https://app.zappway.ai/api/v1

Módulos de API

A API REST do ZappWay é organizada em módulos, cada um correspondendo a um recurso principal da plataforma. Explore a documentação de referência completa para cada um:

AI Agents

Crie, atualize, consulte e gerencie seus agentes AI Employee de maneira programática. Controle os prompts do sistema, seleção de modelo e configuração de comportamento.

Datastores

Gerencie seus repositórios de conhecimento. Faça upload de arquivos, atualize documentos e controle as informações às quais seus agentes têm acesso.

Datasources

Conecte sites, arquivos e serviços externos aos seus datastores. Acione a reindexação e gerencie configurações de origem.

Conversations & Logs

Envie mensagens para seus agentes, recupere o histórico de conversas e monitore eventos de intervenção humana via API.

Casos de uso comuns

Integração de bate-papo (aplicativo personalizado)

Incorpore o mecanismo de IA do ZappWay em seu próprio aplicativo web, aplicativo móvel ou ferramenta interna. Use o endpoint de consulta do agente para enviar mensagens do usuário e receber respostas de IA sem a IU do ZappWay.

POST https://app.zappway.ai/api/v1/agents/{agentId}/query
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "query": "What is your return policy?",
  "conversationId": "optional-session-id-for-continuity"
}

Datastore Sync (atualizações de conhecimento automatizadas)

Mantenha a base de conhecimento do seu agente de IA atualizada, atualizando documentos de forma programática sempre que seus dados internos forem alterados - de seu CMS, banco de dados ou qualquer pipeline de conteúdo.

POST https://app.zappway.ai/api/v1/datastores/{datastoreId}/upsert
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "documents": [
    {
      "id": "doc-123",
      "text": "Updated product description...",
      "metadata": { "source": "cms", "updated_at": "2025-01-15" }
    }
  ]
}

Exportação de leads (automação de CRM)

Extraia registros de conversas e dados de contato capturados por seus agentes e envie-os diretamente para seu CRM, plataforma de email marketing ou data warehouse.

GET https://app.zappway.ai/api/v1/agents/{agentId}/conversations?limit=50&after=2025-01-01
Authorization: Bearer YOUR_API_KEY

Formato de resposta

Todas as respostas da API retornam JSON. Uma resposta padrão bem-sucedida segue esta estrutura:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 143
  }
}

As respostas de erro incluem uma mensagem descritiva:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key."
  }
}

Códigos de status HTTP

Código	Significado
`200 OK`	Solicitação bem-sucedida
`201 Created`	Recurso criado com sucesso
`400 Bad Request`	Parâmetros inválidos — verifique o corpo da sua solicitação
`401 Unauthorized`	Chave de API ausente ou inválida
`403 Forbidden`	Chave válida, mas permissões insuficientes
`404 Not Found`	O recurso solicitado não existe
`429 Too Many Requests`	Limite de taxa excedido — abrandar pedidos
`500 Internal Server Error`	Erro no servidor – entre em contato com o suporte se persistir

Limites de taxa

As solicitações de API estão sujeitas a limitação de taxa para garantir a estabilidade da plataforma para todos os usuários.

Plano	Limite de taxa
Grátis	60 solicitações/minuto
Pró	300 solicitações/minuto
Empresa	Personalizado — configurado por contrato

Quando um limite de taxa é excedido, a API retorna 429 Too Many Requests com um cabeçalho Retry-After indicando quantos segundos esperar antes de tentar novamente. Práticas recomendadas para evitar limitação de taxas:

Agrupe várias operações em solicitações únicas onde a API oferece suporte
Implementar espera exponencial em respostas 429
Armazena respostas em cache localmente quando os mesmos dados são solicitados repetidamente

Melhores práticas de segurança

1. Use variáveis de ambiente Nunca codifique chaves de API em seu código-fonte. Armazene-os como variáveis de ambiente e carregue-os em tempo de execução.

# .env file (never commit this to version control)
ZAPPWAY_API_KEY=your_key_here

2. Restringir o uso da chave por serviço Crie uma chave de API separada para cada integração ou serviço (por exemplo, uma para sincronização de CRM, outra para seu aplicativo móvel). Dessa forma, se uma chave for comprometida, você poderá revogá-la sem afetar outras integrações. 3. Gire as chaves periodicamente Alterne as chaves de API a cada 90 dias como uma prática de higiene de segurança. Gere uma nova chave, atualize suas integrações e revogue a chave antiga somente após confirmar que a nova funciona. 4. Monitore o uso não autorizado Verifique regularmente os registros da API em busca de atividades inesperadas: volumes de solicitações incomuns, solicitações de endereços IP inesperados ou erros em endpoints que você não está usando. Contate support@zappway.ai se detectar comportamento suspeito. 5. Nunca exponha chaves no código de front-end As chaves de API devem ser usadas apenas no lado do servidor. Se o seu caso de uso exigir interação de IA do lado do cliente, faça solicitações de proxy por meio de seu próprio servidor back-end que mantém a chave com segurança.

Solução de problemas

Problema: `401 Unauthorized` Erro

Sintomas:

Todas as solicitações de API retornam 401 independentemente do endpoint

Soluções:

Verifique se a chave está sendo enviada no formato de cabeçalho correto: Authorization: Bearer YOUR_KEY
Verifique se há espaços extras ou quebras de linha ao redor do valor-chave
Confirme se a chave não foi revogada — verifique a página Chaves de API no seu painel
Gere uma nova chave e teste-a diretamente para descartar uma chave corrompida

Problema: `403 Forbidden` Erro

Sintomas:

A solicitação é autenticada, mas retorna 403 em endpoints específicos

Soluções:

Verifique se a função da sua conta tem permissão para executar a ação (por exemplo, apenas administradores podem excluir agentes via API)
Confirme se o recurso pertence à mesma organização que sua chave de API
Verifique se o endpoint requer um nível de plano específico – alguns endpoints são apenas Pro ou Enterprise

Problema: `429 Too Many Requests`

Sintomas:

As solicitações começam a falhar durante trabalhos de automação de alto volume

Soluções:

Implemente a espera exponencial – espere e tente novamente após o tempo especificado no cabeçalho Retry-After
Reduza a frequência de solicitações por meio de operações em lote
Verifique se sua integração tem um loop que está fazendo solicitações rápidas e não intencionais
Atualize seu plano para limites de taxa mais altos se seu caso de uso exigir legitimamente mais rendimento

Problema: a chave parou de funcionar depois de funcionar anteriormente

Sintomas:

Uma integração que estava funcionando começa a retornar erros 401

Soluções:

Verifique a página Chaves de API — a chave pode ter sido revogada por outro administrador em sua organização
Verifique se ninguém girou a chave como parte de um procedimento de segurança
Gere uma nova chave e atualize a integração afetada
Entre em contato com support@zappway.ai se precisar de ajuda para identificar quem revogou a chave

Referência completa da API

Para documentação detalhada sobre cada endpoint, incluindo parâmetros, corpos de solicitação e exemplos de respostas:

Referência da API

Veja a referência completa da API com exemplos interativos para cada endpoint.

Apoiar

Precisa de ajuda com integração de API? Entre em contato com o suporte ZappWay:

E-mail: support@zappway.ai
Linha de assunto: Incluir “API” para roteamento mais rápido

Forneça estes detalhes ao relatar problemas:

O endpoint que você está chamando (método + URL)
O código de status HTTP e a mensagem de erro retornados
Uma versão higienizada da sua solicitação (remova a chave API antes de compartilhar)
Sua linguagem de programação e cliente/biblioteca HTTP

Última atualização: março de 2026 Plataforma: Painel ZappWay — Chaves de API

Getting Started

Workspace

ZappFlux Automation

Chaves de API

Chaves de API

Visão geral

Gerenciando chaves de API

Gerando uma nova chave

Visualizando chaves existentes

Revogando uma chave

Autenticação

Módulos de API

AI Agents

Datastores

Datasources

Conversations & Logs

Casos de uso comuns

Integração de bate-papo (aplicativo personalizado)

Datastore Sync (atualizações de conhecimento automatizadas)

Exportação de leads (automação de CRM)

Formato de resposta

Códigos de status HTTP

Limites de taxa

Melhores práticas de segurança

Solução de problemas

Problema: `401 Unauthorized` Erro

Problema: `403 Forbidden` Erro

Problema: `429 Too Many Requests`

Problema: a chave parou de funcionar depois de funcionar anteriormente

Referência completa da API

Referência da API

Apoiar

​Chaves de API

​Visão geral

​Gerenciando chaves de API

​Gerando uma nova chave

​Visualizando chaves existentes

​Revogando uma chave

​Autenticação

​Módulos de API

AI Agents

Datastores

Datasources

Conversations & Logs

​Casos de uso comuns

​Integração de bate-papo (aplicativo personalizado)

​Datastore Sync (atualizações de conhecimento automatizadas)

​Exportação de leads (automação de CRM)

​Formato de resposta

​Códigos de status HTTP

​Limites de taxa

​Melhores práticas de segurança

​Solução de problemas

​Problema: 401 Unauthorized Erro

​Problema: 403 Forbidden Erro

​Problema: 429 Too Many Requests

​Problema: a chave parou de funcionar depois de funcionar anteriormente

​Referência completa da API

Referência da API

​Apoiar

Chaves de API

Visão geral

Gerenciando chaves de API

Gerando uma nova chave

Visualizando chaves existentes

Revogando uma chave

Autenticação

Módulos de API

Casos de uso comuns

Integração de bate-papo (aplicativo personalizado)

Datastore Sync (atualizações de conhecimento automatizadas)

Exportação de leads (automação de CRM)

Formato de resposta

Códigos de status HTTP

Limites de taxa

Melhores práticas de segurança

Solução de problemas

Problema: `401 Unauthorized` Erro

Problema: `403 Forbidden` Erro

Problema: `429 Too Many Requests`

Problema: a chave parou de funcionar depois de funcionar anteriormente

Referência completa da API

Apoiar