Documentação Técnica

Visão geral

A API é REST, autenticada por JWT, com versionamento em /v1/ e respostas em JSON. Os dados são isolados por tenant (Row Level Security): você só enxerga o que pertence ao seu tenant.

Desenvolvida e operada por Cia Guinle Ltda. (CNPJ 50.651.683/0001-15).

Quick start

1 — Autenticar

curl -X POST https://api.complianceos.com.br/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "cco@sua-empresa.com.br", "password": "SuaSenha@2026" }'

# 200
{ "data": { "accessToken": "eyJhbGciOi...", "expiresIn": 900 } }

2 — Criar uma entidade (informe cnpj com 14 dígitos ou cpf com 11)

curl -X POST https://api.complianceos.com.br/v1/entities \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Comércio Ltda", "entityType": "FORNECEDOR", "cnpj": "12345678000195" }'

# 201
{ "data": { "id": "6c978981-...", "riskLevel": "UNKNOWN", "kycStatus": "PENDING" } }

3 — Executar um checklist

# 1. iniciar a execução
POST /v1/checklists/run        { "checklistId": "<template>", "entityId": "<entidade>" }
# 2. salvar respostas parciais (repita quantas vezes precisar)
PATCH /v1/checklists/run/:id   { "answers": [ { "itemId": "pld_cdd_001", "answer": true } ] }
# 3. concluir — dispara o cálculo de risco em background
POST /v1/checklists/run/:id/complete

Autenticação

Envie o token de acesso no cabeçalho Authorization: Bearer <accessToken>. O token é um JWT (HS256) e expira em 15 minutos. O login também define um cookie refreshToken (httpOnly, 7 dias) usado em POST /v1/auth/refresh para obter um novo token de acesso.

Se a conta tiver MFA, o login responde MFA_REQUIRED; reenvie com "mfaCode": "123456" (TOTP de 6 dígitos).

POST/v1/auth/login

Body: email, password, mfaCode (opcional), captchaToken (Turnstile, quando o captcha está ativo). Limite de 10 tentativas por minuto.

POST/v1/auth/refresh

Renova o token de acesso a partir do cookie refreshToken.

POST/v1/auth/logout

Revoga os refresh tokens do usuário.

GET/v1/auth/me

Perfil do usuário autenticado (papel, tenant, plano).

POST/v1/auth/mfa/setup

Inicia a configuração de MFA; devolve segredo e QR code.

POST/v1/auth/mfa/confirm

Confirma com código TOTP e devolve códigos de recuperação.

DELETE/v1/auth/mfa

Desativa o MFA. Body: password.

POST/v1/auth/forgot-password

Body: email, captchaToken (quando o captcha está ativo). Envia por e-mail um link de redefinição válido por 1 hora e de uso único; a resposta é a mesma exista ou não a conta. Limite de 5 por minuto.

POST/v1/auth/reset-password

Body: token, newPassword (mínimo 8 caracteres).

POST/v1/auth/accept-invite

Aceita um convite de usuário (recebido por e-mail). Body: token, name, password (mínimo 8 caracteres).

Formato de erros

Os erros seguem o padrão Problem Details (RFC 7807).

{
  "type": "https://complianceos.com.br/errors/FORBIDDEN",
  "title": "Acesso negado",
  "status": 403,
  "detail": "Esta ação requer um dos seguintes papéis: ADMIN, COMPLIANCE_OFFICER",
  "instance": "/v1/entities/6c978981-...",
  "requestId": "2926b033-c08e-47b5-8fba-f1b948daf9c4",
  "timestamp": "2026-09-21T16:25:21.883Z"
}

HTTP	Código	Quando ocorre
400	`VALIDATION_ERROR`	Corpo ou parâmetros inválidos (schema).
401	`UNAUTHORIZED`	Token ausente, expirado ou inválido.
401	`MFA_REQUIRED`	Conta com MFA: reenvie o login com mfaCode.
400	`CAPTCHA_REQUIRED / CAPTCHA_INVALID`	Login ou recuperação de senha sem token Turnstile válido (quando o captcha está ativo).
503	`CAPTCHA_UNAVAILABLE`	A verificação anti-robô não pôde ser validada; tente novamente.
403	`FORBIDDEN`	Papel sem permissão, ou regra de segregação de funções.
403	`MODULE_NOT_ENABLED`	O plano efetivo do tenant não inclui o recurso.
404	`NOT_FOUND`	Recurso inexistente ou de outro tenant.
409	`CONFLICT`	Recurso duplicado (ex.: CNPJ já cadastrado).
422	`BUSINESS_RULE_VIOLATION`	Regra de negócio violada.
429	`RATE_LIMIT_EXCEEDED`	Limite de requisições atingido.

Paginação

Listagens usam limit e offset. Entidades devolvem meta com total e hasMore; casos de alerta e execuções de checklist devolvem total no nível raiz.

GET /v1/entities?limit=25&offset=50&sort=created_at:desc&riskLevel=HIGH&search=acme

{ "data": [ ... ], "meta": { "total": 142, "limit": 25, "offset": 50, "hasMore": true } }

Rate limit

Cada tenant pode fazer até 1.000 requisições por minuto (contagem por tenant, ou por IP em chamadas sem token). Ao exceder, a API responde 429.

Entidades

GET/v1/entities

Filtros: riskLevel, status, entityType, search, sort, limit, offset.

Acesso: Todos os papéis

POST/v1/entities

Body: name, entityType (CLIENTE | FORNECEDOR | PARCEIRO | COLABORADOR), cnpj ou cpf, sector.

Acesso: ADMIN, COMPLIANCE_OFFICER, ANALYST

GET/v1/entities/:id

Acesso: Todos os papéis

PATCH/v1/entities/:id

Body: name, sector, status (ACTIVE | INACTIVE | BLOCKED), blockedReason.

Acesso: ADMIN, COMPLIANCE_OFFICER, ANALYST

DELETE/v1/entities/:id

Inativação lógica (soft delete).

Acesso: ADMIN, COMPLIANCE_OFFICER

POST/v1/entities/:id/approve-risk

Aprova a avaliação de risco. Quem fez a última alteração de risco não pode aprová-la (segregação de funções).

Acesso: ADMIN, COMPLIANCE_OFFICER

POST/v1/entities/:id/sync

Sincroniza dados cadastrais (KYB).

Acesso: ADMIN, COMPLIANCE_OFFICER

POST/v1/entities/:id/due-diligence

Inicia due diligence automatizada.

Acesso: ADMIN, COMPLIANCE_OFFICER, ANALYST

Checklists

GET/v1/checklists

Templates ativos (sistema + tenant). Parâmetro: status.

Acesso: Todos os papéis

GET/v1/checklists/:id

Template completo, com os itens (BOOLEAN, SCALE, MULTIPLE_CHOICE, TEXT).

Acesso: Todos os papéis

GET/v1/checklists/runs

Execuções. Filtros: entityId, status (IN_PROGRESS | COMPLETED | CANCELLED), limit, offset.

Acesso: Todos os papéis

POST/v1/checklists/run

Inicia uma execução. Body: checklistId, entityId.

GET/v1/checklists/run/:id

Execução com as respostas salvas.

PATCH/v1/checklists/run/:id

Salva respostas parciais: { answers: [{ itemId, answer, note? }] }. Só enquanto IN_PROGRESS.

POST/v1/checklists/run/:id/complete

Conclui e dispara o cálculo de risco da entidade em background.

Acesso: ADMIN, COMPLIANCE_OFFICER

Casos de alerta

Requer o recurso CASE_MANAGEMENT (plano Professional ou superior).

GET/v1/alert-cases

Filtros: status, severity, source, assignedTo, entityId, limit, offset.

POST/v1/alert-cases

Body: source, severity, title, description, entityId?, evidence?.

Acesso: ADMIN, COMPLIANCE_OFFICER, ANALYST

GET/v1/alert-cases/:id

PATCH/v1/alert-cases/:id

Muda status ou responsável. Encerrar exige resolutionNote e usuário diferente de quem criou o caso.

Acesso: ADMIN, COMPLIANCE_OFFICER, ANALYST

POST/v1/alert-cases/export

Relatório em PDF dos casos filtrados.

Acesso: ADMIN, COMPLIANCE_OFFICER, AUDITOR

Fluxo de status: OPEN → UNDER_REVIEW → ESCALATED e encerramento em CLOSED_FALSE_POSITIVE ou CLOSED_CONFIRMED. Casos encerrados não reabrem.

Documentos

POST/v1/documents/generate

Geração assíncrona. Body: docType, entityId?, params. Responde 202 com jobId.

GET/v1/documents/jobs/:jobId

Status da geração.

GET/v1/documents

Lista documentos do tenant (docType, limit).

GET/v1/documents/:id/download

URL pré-assinada válida por 15 minutos. O documento precisa estar READY.

POST/v1/documents/:id/sign

Assina o documento.

Audit trail

Cada evento guarda ator, módulo, ação, resultado e um hash SHA-256 que inclui o hash do evento anterior. A tabela é append-only: triggers do banco impedem alteração e exclusão.

GET/v1/audit/events

Filtros: from, to, module, action, actorId, resourceId, result, limit. Retorna em ordem cronológica. A consulta também é auditada.

GET/v1/audit/verify

Recalcula a cadeia de hashes do tenant e devolve { valid, violations }.

Acesso: ADMIN, AUDITOR

POST/v1/audit/entities/:id/certificate

Solicita o certificado de compliance da entidade (assíncrono, 202).

Usuários

GET/v1/users

Acesso: ADMIN

POST/v1/users/invite

Body: email, name, role (COMPLIANCE_OFFICER | ANALYST | AUDITOR | READONLY).

Acesso: ADMIN

PATCH/v1/users/:id

Papel e status só podem ser alterados por ADMIN.

Acesso: ADMIN (outros) / próprio usuário

DELETE/v1/users/:id

Desativa o usuário (não é possível desativar a si mesmo).

Acesso: ADMIN

Dashboard

GET/v1/dashboard/summary

Entidades por nível de risco, checklists, documentos, alertas, atividades recentes e entidades críticas.

Acesso: Todos os papéis

GET/v1/dashboard/stream

Server-Sent Events com atualizações do resumo em tempo real.

Notificações e webhooks

GET/v1/notifications

Parâmetros: unread=true, limit.

PATCH/v1/notifications/:id/read

PATCH/v1/notifications/:id/dismiss

POST/v1/notifications/mark-all-read

GET/v1/webhooks

POST/v1/webhooks

Body: url (https), description?, events (padrão ["*"]). O segredo de assinatura é devolvido na criação.

Acesso: ADMIN

DELETE/v1/webhooks/:id

Acesso: ADMIN

Configurações

GET/v1/settings

Dados do tenant: nome, CNPJ, plano, status, domínio autorizado e e-mail de cobrança.

Acesso: Todos os papéis

PATCH/v1/settings

Body: name, authorizedDomain.

Acesso: ADMIN

Assinatura

Valores monetários dos planos e cobranças são expressos em centavos (BRL).

GET/v1/billing/plans

Catálogo de planos (público).

GET/v1/billing/subscription

GET/v1/billing/payments

POST/v1/billing/checkout

Body: plan (STARTER | PROFESSIONAL), billingType (PIX | BOLETO), cpfCnpj, name, email.

Acesso: ADMIN

POST/v1/billing/subscription/cancel

Acesso: ADMIN

Inteligência

Requer o recurso INTELLIGENCE (plano Starter ou superior).

GET/v1/intelligence/ubo/:entityId?taxId=

Beneficiários finais (UBO).

GET/v1/intelligence/sanctions/:entityId

Screening de sanções.

GET/v1/intelligence/report/:entityId

Relatório consolidado.

Enriquecimento de dados

Requer o recurso DATA_ENRICHMENT (plano Professional ou superior). Cada categoria expõe o mesmo par de rotas sob /v1/<categoria>: ambiental, cadastral, credito, fiscal, processos, rural, regularidade, sancoes, internacional, sociodemografico, trabalhista e veicular.

GET/v1/<categoria>/produtos

Catálogo de produtos de consulta da categoria (slug, nome e custo).

POST/v1/<categoria>/consultar

Body: produtoSlug, documento. Cada consulta é registrada no audit trail.

As respostas dessas categorias ainda são simuladas (mock); a integração real com o provedor está em migração. Somente a consulta societária (/v1/intelligence/ubo) usa dados reais.

Plataforma (super admin)

Rotas do administrador da plataforma (papel SUPER_ADMIN, hospedado no tenant interno "Plataforma"), para cadastrar organizações clientes e definir planos, inclusive planos sob medida. Em produção exigem MFA ativo (claim mfa do token). Todas as ações são registradas no audit trail da plataforma.

O primeiro SUPER_ADMIN é criado por linha de comando (não há endpoint): SUPER_ADMIN_EMAIL=… SUPER_ADMIN_PASSWORD=… pnpm --filter @compliance-os/api db:create-super-admin.

GET/v1/platform/tenants

Organizações com plano, uso (usuários/entidades) e status. Filtros: search, status.

Acesso: SUPER_ADMIN

POST/v1/platform/tenants

Body: name, cnpj (14 dígitos), planCode, admin { name, email }, billingEmail?, planExpiresAt?, contractNotes?. Devolve o convite do primeiro administrador (o link não é enviado por e-mail).

Acesso: SUPER_ADMIN

GET/v1/platform/tenants/:id

Acesso: SUPER_ADMIN

PATCH/v1/platform/tenants/:id

name, billingEmail, status (ACTIVE | SUSPENDED | CANCELLED), planCode, planManaged, planExpiresAt, contractNotes. Suspender bloqueia novos logins.

Acesso: SUPER_ADMIN

POST/v1/platform/tenants/:id/invite-admin

Gera convite para outro administrador da organização.

Acesso: SUPER_ADMIN

GET/v1/platform/plans

Catálogo (sistema + sob medida), com quantas organizações usam cada plano.

Acesso: SUPER_ADMIN

POST/v1/platform/plans

Cria plano sob medida: label, description, monthlyValueCents, features (INTELLIGENCE | CASE_MANAGEMENT | DATA_ENRICHMENT), maxEntities, maxUsers (vazio = sem limite).

Acesso: SUPER_ADMIN

PATCH/v1/platform/plans/:code

Edita plano sob medida. Planos de sistema só permitem active.

Acesso: SUPER_ADMIN

GET/v1/platform/audit

Eventos de auditoria das ações de plataforma.

Acesso: SUPER_ADMIN

Plano por contrato: ao atribuir um plano pelo painel, o tenant passa a usá-lo independente de assinatura no Asaas (planManaged), até planExpiresAt se informado. Depois disso, ou com planManaged: false, o acesso volta a seguir a assinatura. Limites de usuários/entidades do plano são aplicados na criação (HTTP 422 ao atingir).

Papéis e permissões

Papel	Perfil	Acesso
`SUPER_ADMIN`	Administrador da plataforma	Organizações e planos (/v1/platform). Não opera dados de um tenant
`ADMIN`	Administrador do tenant	Todas as ações, inclusive usuários, webhooks, configurações e assinatura
`COMPLIANCE_OFFICER`	Compliance Officer	Entidades, checklists (inclui concluir), alertas, documentos, exportações e audit trail
`ANALYST`	Analista	Cria/edita entidades, executa checklists, trata casos de alerta
`AUDITOR`	Auditor	Somente leitura + audit trail, verificação de integridade e download de documentos
`READONLY`	Visualização	Dashboard e entidades (documentos mascarados)

A autorização é decidida por papel; o ADMIN sempre é autorizado. Permissões granulares adicionais podem ser concedidas por usuário.

Planos e módulos

O acesso a recursos premium depende do plano efetivo do tenant (assinatura ativa, ou em atraso dentro da carência).

Plano	Inclui	Recursos liberados
`FREE`	Cadastro de entidades e checklists	—
`STARTER`	Free + screening de sanções	INTELLIGENCE
`PROFESSIONAL`	Starter + gestão de casos e enriquecimento de dados	INTELLIGENCE, CASE_MANAGEMENT, DATA_ENRICHMENT
`ENTERPRISE`	Professional, sob contrato	INTELLIGENCE, CASE_MANAGEMENT, DATA_ENRICHMENT

Precisa de ajuda com a integração?

Nossa equipe apoia integrações complexas e customizações.

Falar com um especialista