API REST v1 da Encantra

Integre seus sistemas (ERP, CRM, produto, BI, automações) à Encantra. Especificação OpenAPI: openapi.yaml.

Base: https://suporte.inspire4u.com.br/api/v1 · Formato: JSON UTF-8 · Disponível nos planos: Jornada, Apologia e Enterprise.

Autenticação

Crie uma chave em Integrações › API & Webhooks › Chaves de API, escolhendo os escopos mínimos. A chave aparece uma única vez.

curl https://suporte.inspire4u.com.br/api/v1/me -H "Authorization: Bearer enc_live_xxxxxxxx_yyyyyyyy"

Escopo	Permite
*	Tudo
tickets	Ler, abrir e responder tickets
accounts	Ler e criar/atualizar contas
contacts	Ler e criar/atualizar contatos
events	Registrar eventos de uso
knowledge	Publicar/remover documentos de conhecimento

Convenções

• Sucesso: {"data": ..., "meta": {...}}. Listas paginadas por page e per_page (máx. 100) com meta.total.
• Erro: {"error": {"status": 422, "message": "...", "fields": {...}}}.
• 401 chave ausente/inválida · 403 escopo insuficiente · 402 plano/limite · 404 · 422 validação · 429 limite de taxa.
• Limite de taxa: 600 requisições/minuto por chave.
• Datas ISO 8601; dinheiro em centavos (mrr_cents).
• POST /accounts e POST /contacts são upserts (idempotentes por external_id/email).

Endpoints

Método	Caminho	Escopo	Descrição
GET	/me	—	Workspace e chave em uso
GET	/accounts	accounts	Lista contas (external_id, domain, lifecycle_stage, updated_since, page, per_page)
POST	/accounts	accounts	Cria/atualiza por external_id (aceita contacts[])
GET	/accounts/{id}	accounts	Detalhe
PATCH	/accounts/{id}	accounts	Atualização parcial
GET	/contacts	contacts	Lista contatos (email, external_id, account_id)
POST	/contacts	contacts	Cria/atualiza por external_id ou email (vincule com account_id ou account_external_id)
POST	/events	events	Lote de até 1000 eventos de uso (alimenta o health score)
POST	/knowledge	knowledge	Publica/atualiza documento no conhecimento da Lumi
DELETE	/knowledge/{source_id}	knowledge	Remove documento
GET	/tickets	tickets	Lista tickets
POST	/tickets	tickets	Abre ticket
GET	/tickets/{id}	tickets	Detalhe com mensagens públicas
PATCH	/tickets/{id}	tickets	Atualiza status, prioridade, tags, responsável
POST	/tickets/{id}/messages	tickets	Responde (cliente ou agente)

Exemplos

Sincronizar uma conta com seus contatos

curl -X POST https://suporte.inspire4u.com.br/api/v1/accounts \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "external_id": "cust_1042",
    "name": "Padaria Pão Quente",
    "domain": "paoquente.com.br",
    "plan": "Pro",
    "mrr_cents": 29900,
    "renewal_date": "2027-03-01",
    "contacts": [{ "external_id": "u_9", "name": "Joana", "email": "joana@paoquente.com.br", "role": "champion" }]
  }'

Resposta 201 (criada) ou 200 (atualizada) com meta.created.

Registrar uso do produto

curl -X POST https://suporte.inspire4u.com.br/api/v1/events \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"events": [
        {"id": "evt_8812", "customer_external_id": "cust_1042", "user_external_id": "u_9",
         "event": "report_exported", "quantity": 1, "occurred_at": "2026-10-28T09:12:00-03:00"}
      ]}'

Resposta 202: {"data": {"inserted": 1, "skipped": 0, "errors": []}}. Eventos com o mesmo id não são duplicados.

Publicar conhecimento

curl -X POST https://suporte.inspire4u.com.br/api/v1/knowledge \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"source_id": "politica-trocas", "title": "Política de trocas", "visibility": "public",
       "url": "https://loja.com.br/trocas", "body_markdown": "## Prazo\n\nTrocas em até 30 dias..."}'

Abrir um ticket

curl -X POST https://suporte.inspire4u.com.br/api/v1/tickets \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"subject": "Erro ao emitir nota", "body": "Ao emitir a NF aparece erro 500.",
       "contact_email": "joana@paoquente.com.br", "contact_name": "Joana", "priority": "high", "tags": ["nfe"]}'

Webhooks (saída)

Configure em Integrações › API & Webhooks › Webhooks. Cada entrega:

POST https://seu-sistema.com/webhooks/encantra
Content-Type: application/json
X-Encantra-Event: ticket.created
X-Encantra-Signature: t=1761657600,v1=5f2b…

{"id": "…", "event": "ticket.created", "created_at": "2026-10-28T10:20:00-03:00", "data": {"tenant_id": 1, "ticket_id": 42, …}}

Valide: hex(hmac_sha256(segredo, t + "." + corpo_bruto)) == v1 e |agora − t| ≤ 300 s. Responda 2xx em até 15 s; falhas são reenviadas até 5 vezes com espera exponencial.

Eventos: ticket.created, ticket.updated, ticket.status_changed, ticket.assigned, ticket.replied, ticket.solved, ticket.sla_breached, csat.received, chat.started, chat.handoff, account.created, account.updated, account.health_changed, account.stage_changed, contact.created, survey.responded, journey.started, journey.completed, task.overdue, connector.synced, usage.event_received.

// Node.js — verificação
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Conectar seu produto inteiro

Para trazer documentação, catálogo, clientes, uso, contexto ao vivo e ações de uma vez, implemente o protocolo aberto EKSP — veja docs/eksp.