Documento 004 · APIs e Contratos · v1.0 Enterprise

Especificação de APIs e Contratos de Serviços

Uma arquitetura de APIs moderna, segura, escalável e preparada para integrações com web, mobile, Lovable, IA, parceiros, marketplace, SDKs e webhooks.

Objetivo

APIs para todos os consumidores

Cada capacidade da plataforma é exposta por API, consumível por qualquer cliente autorizado.

Frontend Web

Aplicativo Mobile

Lovable

Parceiros

Marketplace

APIs públicas

SDKs

Webhooks

Automações

Filosofia

Princípios da camada de APIs

Fundamentos que regem toda a superfície de integração da K10AI.

API First

Toda funcionalidade da K10AI é acessível por API.

Frontend fino

Nunca existirá lógica exclusiva no frontend — ele apenas consome APIs.

Versionamento

Endpoints antigos entram em deprecation antes de qualquer remoção.

Segurança por padrão

HTTPS, JWT, OAuth 2.1, escopos e auditoria em toda operação crítica.

Arquitetura

Gateway único, serviços independentes

Todo tráfego passa por um API Gateway que roteia para serviços especializados sobre Database, AI Kernel e Storage.

API Gateway · /api/v1

Auth Service

Organization Service

Workspace Service

Project Service

AI Service

Course Service

Ebook Service

Landing Service

Marketing Service

Automation Service

Billing Service

Analytics Service

Notification Service

Marketplace Service

Admin Service

Database

AI Kernel

Storage

Padrão REST

Contratos previsíveis e versionados

Todas as APIs usam métodos REST sob /api/v1, com versionamento e depreciação controlada.

Métodos & Versão

GETPOSTPUTPATCHDELETE

v1 · v2 · v3
Deprecation antes de remoção
GET /api/v1/projects

Resposta de sucesso

{
  "success": true,
  "message": "Project created successfully",
  "data": {},
  "meta": {},
  "requestId": "",
  "timestamp": ""
}

Resposta de erro

{
  "success": false,
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "Project not found"
  },
  "requestId": "",
  "timestamp": ""
}

Catálogo de Endpoints

Cada domínio com seus contratos

Os principais recursos da plataforma e seus endpoints REST versionados.

Auth API

POST/auth/register
POST/auth/login
POST/auth/logout
POST/auth/refresh
POST/auth/forgot-password
POST/auth/reset-password
POST/auth/magic-link
POST/auth/mfa

Users API

GET/users
GET/users/{id}
POST/users
PATCH/users/{id}
DELETE/users/{id}

Organizations & Workspaces API

GET/organizations
POST/organizations
PATCH/organizations/{id}
GET/workspaces
POST/workspaces
PATCH/workspaces/{id}

Projects API

GET/projects
POST/projects
PATCH/projects/{id}
DELETE/projects/{id}
POST/projects/{id}/archive
POST/projects/{id}/duplicate

AI API

POST/ai/chat
POST/ai/chat/{conversationId}
GET/ai/history
GET/ai/memory
PATCH/ai/memory
POST/ai/model
POST/ai/agent

Prompt API

GET/prompts
POST/prompts
PATCH/prompts/{id}
DELETE/prompts/{id}
POST/prompts/{id}/favorite
POST/prompts/{id}/publish

Courses API

GET/courses
POST/courses
PATCH/courses/{id}
DELETE/courses/{id}
POST/courses/{id}/publish
POST/courses/{id}/export

Ebook & Landing API

GET/ebooks
POST/ebooks
POST/ebooks/{id}/export
GET/landing-pages
POST/landing-pages
POST/landing-pages/{id}/publish

Media API

POST/images/generate
POST/images/upscale
POST/videos/generate
POST/videos/render
POST/voice/generate
POST/voice/transcribe

Marketing API

POST/marketing/{channel}/generate
POST/marketing/{channel}/draft
POST/marketing/{channel}/schedule
POST/marketing/{channel}/publish
GET/marketing/{channel}/history

Billing API

GET/plans
POST/subscriptions
GET/payments
GET/credits
POST/coupon
GET/invoice

Admin & Analytics API

GET/admin/users
GET/admin/audit
PATCH/admin/settings
GET/dashboard
GET/revenue
GET/ai-usage

Marketing API

Um contrato por canal

Cada canal expõe endpoints para gerar conteúdo, salvar rascunho, agendar, publicar e consultar histórico.

Instagram

Facebook

TikTok

Google Ads

Meta Ads

Email Marketing

Webhooks

Eventos são emitidos com identificador, timestamp, assinatura de validação, payload padronizado e reenvio em caso de falha.

project.createdproject.updatedcourse.createdcourse.publishedlanding.publishedebook.exportedpayment.approvedsubscription.createdsubscription.renewedcredits.updatedai.request.completedautomation.finished

Rate Limit

Starter60 req/min

Pro300 req/min

Business1000 req/min

EnterpriseConfigurável

Paginação & Filtros

{
  "data": [],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 350,
    "totalPages": 18
  }
}

?status=published?sort=createdAt?order=desc?page=1

Segurança

Proteção em todas as camadas

Requisitos obrigatórios de segurança em toda a superfície de APIs.

HTTPS obrigatório

JWT para autenticação

Refresh Token

OAuth 2.1 para terceiros

Escopos de permissão por recurso

Rate limiting

Validação de payload

Auditoria de operações críticas

SDKs Oficiais

SDKs encapsulam autenticação, tratamento de erros e o consumo das APIs.

JavaScript / TypeScript
Python
PHP
Flutter
.NET (C#)

Integrações Planejadas

OpenAIAnthropicGoogle GeminiMistral AIGroqStripeMercado PagoHotmartKiwifyEduzzWordPressGoogle DriveDropboxOneDriveGoogle CalendarGoogle AnalyticsMetaLinkedInTikTokYouTubeSlackDiscordZapierMaken8n

Padrão de Erros

Códigos consistentes

Erros padronizados facilitam o tratamento por clientes e SDKs.

AUTH_001Credenciais inválidas

AUTH_002Sessão expirada

USER_001Usuário não encontrado

PROJECT_001Projeto inexistente

AI_001Modelo indisponível

AI_002Limite de créditos excedido

BILLING_001Pagamento recusado

STORAGE_001Arquivo inválido

SYSTEM_001Erro interno

Critérios de Aprovação

Nenhuma API pronta sem estes itens

A definição de pronto para qualquer API da K10AI.

Documentação OpenAPI/Swagger

Autenticação

Autorização

Tratamento padronizado de erros

Logs

Testes automatizados

Controle de versão

Limites de uso

Métricas de desempenho

A camada de integração da sua operação de IA

Este documento define os contratos oficiais de APIs da K10AI. As implementações seguem OpenAPI/Swagger, autenticação, versionamento e testes automatizados.