Referência de API

Endpoints internos de app.kroz.co: autenticação, pagamentos, conciliação e auditoria.

Base URL: https://app.kroz.co
Versionamento: v0 (piloto interno): sem prefix /v1 ainda
Formato: JSON (Content-Type: application/json)

Autenticação

Todas as rotas abaixo exigem sessão, exceto /api/auth e /api/baas-webhook.

Ver Autenticação.

Envelope de erro padrão

{
  "ok": false,
  "error": "VALIDATION_ERROR",
  "message": "Descrição legível",
  "details": { }
}

Índice de endpoints (18 rotas)

Auth

GET /api/auth

Verifica sessão. Ver Autenticação.

POST /api/auth

Login. Body: { "code": "...", "redirect": "/rateio" }

Contratos e plataforma

GET /api/platform-contracts

Query:

* Relaxado com KROZ_DEMO_MODE=true

Com reference: 200:

{
  "ok": true,
  "tenant": { "slug": "incorp-piloto", "fiscal_regime": "CPC_47_POC" },
  "contract": { "reference": "PS-0421", "metadata": { "unidade": "1804" } },
  "matrix": {
    "version": 1,
    "spe_percent": 72,
    "landbank_percent": 18,
    "sales_percent": 10,
    "receivers": [ "..." ]
  },
  "spe": { "legal_name": "Incorp SPE Jardim Oeste" }
}

404: Contrato não encontrado.

Usado por Pagadoria → Carregar matriz.

Pagamentos

POST /api/pagadoria-payment

Ver Adaptadores BaaS: Pagadoria.

POST /api/payments/create-with-split

Ver Adaptadores BaaS: Split payment.

GET /api/payment-operations

Query: limit, tenantId, status, contractId

200:

{
  "ok": true,
  "dryRun": false,
  "count": 5,
  "operations": [ "..." ]
}

Sem Supabase: { "ok": true, "dryRun": true, "operations": [], "message": "Supabase não configurado." }

GET /api/payments/get?id=pay_...

Proxy read-only para consulta no BaaS.

Recebedores e clientes

POST /api/receivers/create-subaccount

Ver Adaptadores BaaS: Subcontas.

POST /api/customers/create

Cria pagador. Real: confirmation: "CRIAR CLIENTE".

GET /api/cnpj-lookup?cnpj=00000000000000

200: dados BrasilAPI (name, companyType, taxProfile)

400: Informe um CNPJ com 14 dígitos.
404: CNPJ não encontrado na base consultada.

Usado pela Oficina de Recebedores → Consultar.

Conciliação

GET /api/reconciliation-suggestions

Query:

200:

{
  "ok": true,
  "count": 2,
  "suggestions": [
    {
      "id": "uuid",
      "status": "pendente_aprovacao",
      "agentOutput": { "confidence": "alta", "justificativa": "..." },
      "financialResult": { "..." }
    }
  ]
}

Wallet IDs mascarados na response.

POST /api/reconciliation-approve

curl -s -X POST https://app.kroz.co/api/reconciliation-approve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.kroz.co" \
  -H "X-Idempotency-Key: conc-$(uuidgen)" \
  -d '{
    "suggestionId": "uuid",
    "decision": "aprovar",
    "approvedBy": "diretor@incorp.com.br",
    "notes": "Multa conforme contrato"
  }'

200 aprovar:

{
  "ok": true,
  "decision": "aprovar",
  "paymentStatus": "recebido",
  "message": "Sugestão aprovada atomicamente. Split pode ser aplicado manualmente no BaaS conforme splitSugerido."
}

409: Sugestão já processada com status '...'.

Não chama o BaaS automaticamente: execução manual pós-aprovação. Ver Conciliação.

Rule Engine

POST /api/rules-dry-run

Ver Rule Engine.

Auditoria

GET /api/audit-events

Query: limit, source, action, status

200: { "ok": true, "events": [ ... ] }

POST /api/audit-event

Body (mínimo):

{
  "action": "click_export",
  "source": "ui",
  "status": "received",
  "reference": "PS-0421",
  "amount": 50000,
  "metadata": { }
}

400: Campo obrigatorio: action.

Relatórios

GET /api/captabilidade-report

Query: format=json|csv, tenantId, limit (default 200)

JSON 200: summary.tvp, summary.adimplenciaPercent, operations[]

CSV: Content-Type: text/csv → kroz-captabilidade.csv

Usado por Pagadoria → Exportar captabilidade CSV.

Health

GET /api/config-health

200:

{
  "ok": true,
  "status": "ok",
  "checks": [ "..." ],
  "missingRequired": [],
  "warnings": [],
  "environment": "production",
  "demoMode": false,
  "platform": { "configured": true }
}

Status: ok | attention | missing_required

Webhooks (inbound)

POST /api/baas-webhook

Ver Webhooks.

SDK interno (browser)

assets/js/platform-api.js:

KrozPlatform.getAuthToken()
KrozPlatform.getContract(reference, tenant)
KrozPlatform.createPagadoriaPayment(body, idempotencyKey)
KrozPlatform.listPaymentOperations(params)
KrozPlatform.listReconciliationSuggestions(params)
KrozPlatform.approveReconciliationSuggestion(body, idempotencyKey)
KrozPlatform.getCaptabilidadeReport(format)

Confirmações para execução real

Todas as escritas reais exigem X-Idempotency-Key.

OpenAPI

A especificação OpenAPI completa está disponível para parceiros integrados sob demanda. Entre em contato em contato@kroz.co para acesso ao schema e ambiente de sandbox.

Relacionado

• Autenticação
• Webhooks
• Adaptadores BaaS
• Rule Engine