Kunk API — Documentação

Especificação da API REST do Kunk open source (kunk-api/). Camada de dados, autenticação e módulos opcionais do produto.

Site vs API (importante)

O quê	URL
Estas páginas de documentação (HTML Starlight)	`https://kunksoucannabis.ong.br/referencia-api/…`
API REST (JSON)	`https://{host-da-api}/api/v1/…`

O menu API deste site aponta para /referencia-api/. Chamadas HTTP à API usam sempre o prefixo /api/v1. Não são o mesmo caminho.

Documento	Conteúdo
Catálogo de rotas	Inventário método + path (auth, domínio, items, módulos)
architecture	Visão geral, camadas, princípios
authentication	Sessão (frontend) + Bearer (API)
authorization	RBAC, roles, permissões por collection
items	CRUD genérico `/items/:collection`
query-parameters	`filter`, `sort`, `fields`, `limit`, `meta`
collections	Collections permitidas e notas de domínio
domain-routes	Rotas de negócio (orders, services, auth…)
doc-sign	Termos e assinaturas nativos
files	Upload, download e metadados de arquivos
files-cloud-storage	Drivers local / S3 / GCS + migração + lock
storage-s3-setup	Bucket S3 privado + IAM
storage-gcs-setup	Bucket GCS privado + service account
modules	Módulos opcionais
modules/credentials	`system_api_credentials` + política de secrets
modules/loggi	Cotação, etiqueta, teste Loggi
modules/melhorenvio	Cotação Correios, OAuth, etiqueta
modules/pagarme	Checkout, recipients, webhooks, split
modules/soucannabis_orders	Cliente API externa SC + sync
modules/utalk	WhatsApp / triagem
modules/email	SMTP
modules/geoapify	Geocoding
modules/google_calendar	Agenda
modules/webhooks	Webhooks outbound
errors	Formato de erros e códigos
system-errors	Observabilidade (`system_errors`)
web-vitals	Core Web Vitals
cache	Memory cache operacional
openapi.yaml	Esboço OpenAPI 3.0 (também em `/openapi.yaml` no site)

https://{host}/api/v1

Local (Docker / npm do monorepo):

http://localhost:4250/api/v1

{ "data": {}, "meta": null, "errors": null }

Erro:

{
 "data": null,
 "meta": null,
 "errors": [{ "code": "NOT_FOUND", "message": "…", "details": null }]
}

cd kunk-api && npm test