NOVIQ Cloud API

API REST para envio e recebimento de WhatsApp, IA conversacional com memória e automação de fluxos. Tudo sob a mesma chave, com quota por plano.

Base URL: https://api.noviqcloud.online
Formato: JSON (envie Content-Type: application/json)
Status da plataforma: status.noviqcloud.online

Autenticação

Toda requisição autenticada leva sua chave de API — formato nvq_live_... — em um destes headers:

x-api-key: nvq_live_SUACHAVE
# ou
Authorization: Bearer nvq_live_SUACHAVE

A chave identifica seu tenant e carrega escopos (ex.: whatsapp:send, ai:chat). Chamadas sem o escopo necessário retornam 403. Nunca exponha a chave em código front-end. Para trocar a chave, solicite a revogação e emissão de uma nova.

Limites e quotas

Limite	Valor	Ao exceder
Rate limit (por chave)	120 requisições/minuto	`429 rate limit exceeded` + header `Retry-After`
Quota mensal (por conta)	conforme o plano	`429 monthly quota exceeded`

Toda resposta autenticada devolve os headers:

X-RateLimit-Limit: 120        X-Quota-Limit: 10000
X-RateLimit-Remaining: 119    X-Quota-Used: 231
X-RateLimit-Reset: 42

Monitore X-Quota-Used ou consulte GET /v1/usage. A quota renova no dia 1º de cada mês (horário de Brasília).

Planos

Plano	Requisições/mês	Preço
Starter	10.000	Grátis
Business	100.000	R$ 99/mês
Enterprise	Sob medida (sem limite fixo)	Sob consulta

Erros

Código	Significado
`400`	Corpo inválido ou campo obrigatório ausente — a mensagem indica o campo
`401`	Chave ausente, inválida, expirada ou revogada
`403`	Chave válida sem o escopo necessário
`404`	Recurso não encontrado
`429`	Rate limit ou quota mensal excedidos
`5xx`	Erro interno ou serviço upstream indisponível — repita com backoff

{ "error": "rate limit exceeded", "limitPerMinute": 120, "retryAfterSeconds": 42 }
{ "error": "monthly quota exceeded", "plan": "starter", "quotaLimit": 10000, "quotaUsed": 10000 }

GET/v1/me

Retorna o tenant e os escopos da chave usada. Útil para validar integração.

curl -H "x-api-key: $NOVIQ_KEY" https://api.noviqcloud.online/v1/me

GET/v1/usage

Consumo do mês corrente: plano, quota, breakdown por endpoint e série diária. Não conta na quota.

curl -H "x-api-key: $NOVIQ_KEY" https://api.noviqcloud.online/v1/usage

{
  "tenant": { "slug": "minhaempresa" },
  "period": { "start": "2026-07-01T00:00:00.000Z", "end": "2026-08-01T00:00:00.000Z" },
  "plan": "starter",
  "quota": { "limit": 10000, "used": 231, "remaining": 9769 },
  "rateLimit": { "perMinute": 120 },
  "byEndpoint": [ { "method": "POST", "path": "/v1/whatsapp/send-text", "requests": 180 } ],
  "daily": [ { "day": "2026-07-01", "requests": 42 } ]
}

GET/v1/catalogpúblico

Lista módulos, escopos e endpoints disponíveis. Não exige chave.

GET/v1/integrations/config

Endpoints e caminhos de webhook configurados para a sua conta (URL do webhook de automação, alvo de webhook do WhatsApp etc.).

POST/v1/whatsapp/send-textescopo whatsapp:send

Campo	Tipo	Descrição
`instance`	string, obrigatório	Nome da sua instância WhatsApp (fornecido no onboarding)
`number`	string, obrigatório	Destinatário com DDI, ex. `5511999998888`
`text`	string, obrigatório	Mensagem (até 4096 caracteres)

curl -X POST https://api.noviqcloud.online/v1/whatsapp/send-text \
  -H "x-api-key: $NOVIQ_KEY" -H "Content-Type: application/json" \
  -d '{ "instance": "minhaempresa", "number": "5511999998888", "text": "Pedido #123 confirmado!" }'

POST/v1/whatsapp/send-mediaescopo whatsapp:send

Campo	Tipo	Descrição
`instance`	string, obrigatório	Nome da instância
`number`	string, obrigatório	Destinatário com DDI
`media`	string, obrigatório	URL pública ou base64 do arquivo
`mediatype`	string	`image` (padrão), `video`, `document` ou `audio`
`caption`	string	Legenda (exceto áudio)
`fileName`, `mimetype`	string	Opcionais, recomendados para `document`

curl -X POST https://api.noviqcloud.online/v1/whatsapp/send-media \
  -H "x-api-key: $NOVIQ_KEY" -H "Content-Type: application/json" \
  -d '{ "instance": "minhaempresa", "number": "5511999998888",
        "media": "https://exemplo.com/boleto.pdf", "mediatype": "document",
        "fileName": "boleto.pdf", "caption": "Segue seu boleto" }'

POST/v1/ai/chatescopo ai:chat

Conversa com a IA Noviq, com memória por conta e histórico por conversa.

Campo	Tipo	Descrição
`message`	string, obrigatório	Mensagem do usuário (até 8000 caracteres)
`conversation_id`	string	Continua uma conversa existente; omita para iniciar outra
`system`	string	Persona/sistema de IA (padrão: `geral`)
`use_memory`	boolean	Usa memórias da conta (padrão `true`)

curl -X POST https://api.noviqcloud.online/v1/ai/chat \
  -H "x-api-key: $NOVIQ_KEY" -H "Content-Type: application/json" \
  -d '{ "message": "Qual o status do pedido 123?", "system": "atendimento" }'

Demais endpoints de IA

Endpoint	Escopo	Descrição
GET`/v1/ai/status`	ai:chat	Saúde do serviço de IA e modelos disponíveis
GET`/v1/ai/conversations`	ai:chat	Lista conversas da conta
GET`/v1/ai/conversations/{id}`	ai:chat	Mensagens de uma conversa
GET`/v1/ai/memories`	ai:memory:read	Lista memórias da conta
POST`/v1/ai/memories`	ai:memory:write	Grava uma memória
POST`/v1/ai/treinar`	ai:train	Treina a IA com conteúdo da sua operação
GET`/v1/ai/logs`	ai:logs:read	Log de requisições de IA

POST/v1/automation/webhooks/{path}escopo automation:trigger

Dispara um fluxo de automação da sua conta. O corpo JSON é entregue ao fluxo como payload. O {path} da sua conta aparece em /v1/integrations/config.

curl -X POST https://api.noviqcloud.online/v1/automation/webhooks/meu-fluxo \
  -H "x-api-key: $NOVIQ_KEY" -H "Content-Type: application/json" \
  -d '{ "evento": "pedido_criado", "pedidoId": 123 }'

Usuários e chaves

Endpoint	Escopo	Descrição
GET`/v1/users`	users:read	Lista usuários da conta
POST`/v1/users`	users:write	Cria usuário — `{ "email", "fullName" }`
GET`/v1/users/{userId}/api-keys`	users:read	Lista chaves emitidas para um usuário
POST`/v1/users/{userId}/api-keys`	users:keys	Emite chave com escopos reduzidos para um usuário

A chave completa só aparece na resposta de criação — armazene com segurança.

NOVIQ Cloud · status · suporte: contato via seu gerente de conta · v0.2.0