API Reference - Visão Geral

Documentação completa da API do ArqSystem.

Introdução

O ArqSystem expõe uma API baseada em tRPC que fornece type-safe endpoints para todas as operações do sistema.

Características

• Type-Safety: TypeScript end-to-end
• tRPC: Comunicação cliente-servidor type-safe
• Validação: Zod schemas para todos os inputs
• Autenticação: NextAuth.js com JWT
• Autorização: CASL para controle de acesso

Base URL

http://localhost:4000/api/trpc

Produção:

https://your-domain.com/api/trpc

Autenticação

Login

POST /auth.login

Request:
{
  "email": "user@example.com",
  "password": "password123"
}

Response:
{
  "user": {
    "id": "user-uuid",
    "name": "João Silva",
    "email": "user@example.com",
    "role": "USER"
  },
  "token": "jwt-token-here"
}

Uso do Token

Inclua o token JWT no header de todas as requisições protegidas:

Headers:
{
  "Authorization": "Bearer jwt-token-here"
}

Routers Disponíveis

document

Operações CRUD com documentos.

Endpoints:

• document.list - Listar documentos com filtros
• document.getById - Buscar documento por ID
• document.create - Criar novo documento
• document.update - Atualizar documento
• document.delete - Excluir documento (soft delete)
• document.reindexSearch - Reindexar busca (admin)
• document.getSearchSuggestions - Sugestões de busca

Ver documentação completa

upload

Gerenciamento de arquivos PDF e processamento.

Endpoints:

• upload.requestUploadUrl - Requisitar URL para upload
• upload.confirmUpload - Confirmar upload realizado
• upload.getPdfPages - Buscar páginas de um PDF
• upload.getFilesTree - Árvore hierárquica de arquivos
• upload.getAvailableForAttachment - Arquivos disponíveis para anexar
• upload.deleteFile - Deletar arquivo (super user)

Ver documentação completa

documentType

Gerenciamento de tipos de documento.

Endpoints:

• documentType.getAll - Listar todos os tipos
• documentType.create - Criar novo tipo (admin)
• documentType.update - Atualizar tipo (admin)
• documentType.delete - Deletar tipo (admin)

linkedBody / linkedBodyLevel

Gerenciamento de órgãos vinculados e níveis.

Endpoints linkedBody:

• linkedBody.getAll - Listar todos os órgãos
• linkedBody.getByLevel - Filtrar por nível
• linkedBody.create - Criar órgão (admin)
• linkedBody.update - Atualizar órgão (admin)
• linkedBody.delete - Deletar órgão (admin)

Endpoints linkedBodyLevel:

• linkedBodyLevel.getAll - Listar níveis
• linkedBodyLevel.create - Criar nível (admin)
• linkedBodyLevel.update - Atualizar nível (admin)
• linkedBodyLevel.delete - Deletar nível (admin)

globalFieldConfiguration

Gerenciamento de configuração de campos dinâmicos.

Endpoints:

• globalFieldConfiguration.getAll - Listar campos
• globalFieldConfiguration.create - Criar campo (admin)
• globalFieldConfiguration.update - Atualizar campo (admin)
• globalFieldConfiguration.delete - Deletar campo (admin)

fieldSettings

Configurações de campos por usuário.

Endpoints:

• fieldSettings.getAll - Campos do usuário
• fieldSettings.updateFieldConfiguration - Atualizar config
• fieldSettings.bulkUpdate - Atualização em lote

Tipos de Resposta

Sucesso

{
  "result": {
    "data": {
      // Dados da resposta
    }
  }
}

Erro

{
  "error": {
    "code": "NOT_FOUND",  // Código do erro
    "message": "Documento não encontrado",
    "data": {
      "httpStatus": 404,
      "path": "document.getById"
    }
  }
}

Códigos de Erro

Código	HTTP Status	Descrição
UNAUTHORIZED	401	Não autenticado
FORBIDDEN	403	Sem permissão
NOT_FOUND	404	Recurso não encontrado
BAD_REQUEST	400	Requisição inválida
CONFLICT	409	Conflito (ex: duplicata)
INTERNAL_SERVER_ERROR	500	Erro interno

Validação de Input

Todos os endpoints validam input usando Zod:

// Exemplo: Criar documento
const createDocumentInputSchema = z.looseObject({
  title: z.string().min(1, "Título é obrigatório"),
  documentTypeId: z.string().optional(),
  accessLevel: z.string().optional(),
  attachmentFileIds: z.array(z.string()).optional()
});

Erro de validação:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Validation error",
    "data": {
      "zodError": {
        "fieldErrors": {
          "title": ["Título é obrigatório"]
        }
      }
    }
  }
}

Paginação

Endpoints que retornam listas suportam paginação:

document.list({
  page: 1,      // Página atual (1-indexed)
  limit: 10,    // Itens por página
  search: "",   // Termo de busca (opcional)
  // ... outros filtros
})

Response:
{
  "documents": [...],
  "total": 150,
  "page": 1,
  "limit": 10,
  "totalPages": 15
}

Filtros

Documentos

document.list({
  search: "relatório",
  documentTypeId: "uuid",
  accessLevel: "Público",
  insertionDateStart: "2026-01-01",
  insertionDateEnd: "2026-01-31",
  page: 1,
  limit: 10
})

Órgãos Vinculados

linkedBody.getByLevel({
  levelId: "uuid"  // Opcional
})

Ordenação

Alguns endpoints suportam ordenação:

document.list({
  sortBy: "createdAt",     // Campo
  sortOrder: "desc"        // asc ou desc
})

Rate Limiting

Atual: Sem rate limiting

Recomendado (futuro):

• 100 requisições/minuto por IP
• 1000 requisições/hora por usuário autenticado

CORS

Desenvolvimento:

Access-Control-Allow-Origin: http://localhost:3000

Produção:

Access-Control-Allow-Origin: https://your-domain.com

Websockets (Futuro)

Planejado para notificações em tempo real:

• Upload de PDF concluído
• Processamento de páginas finalizado
• Documento compartilhado
• Comentários em documentos

Versionamento

Atual: v1 (sem prefixo na URL)

Futuro: Versionamento semântico

/api/v2/trpc

Client TypeScript

Instalação

npm install @trpc/client @trpc/react-query

Configuração

import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '@arq-system/api';

export const trpc = createTRPCReact<AppRouter>();

// Provider
<trpc.Provider client={trpcClient} queryClient={queryClient}>
  <App />
</trpc.Provider>

Uso

// Queries
const { data: documents } = trpc.document.list.useQuery({
  page: 1,
  limit: 10
});

// Mutations
const createDocument = trpc.document.create.useMutation({
  onSuccess: () => {
    toast.success("Documento criado!");
  }
});

await createDocument.mutateAsync({
  title: "Novo Documento",
  // ... outros campos
});

Exemplos de Requisições

cURL

# GET request
curl -X GET "http://localhost:4000/api/trpc/document.list?input=%7B%22page%22%3A1%2C%22limit%22%3A10%7D" \
  -H "Authorization: Bearer jwt-token"

# POST request
curl -X POST "http://localhost:4000/api/trpc/document.create" \
  -H "Authorization: Bearer jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"title":"Novo Documento","accessLevel":"Público"}'

JavaScript/Fetch

// GET
const response = await fetch(
  'http://localhost:4000/api/trpc/document.list?input={"page":1,"limit":10}',
  {
    headers: {
      'Authorization': 'Bearer jwt-token'
    }
  }
);
const data = await response.json();

// POST
const response = await fetch(
  'http://localhost:4000/api/trpc/document.create',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer jwt-token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Novo Documento',
      accessLevel: 'Público'
    })
  }
);

Referências

• tRPC Documentation
• Zod Documentation
• NextAuth.js
• CASL Documentation

Próximas Seções

• API de Documentos - CRUD completo de documentos
• API de Upload - Upload e gerenciamento de arquivos
• API de Busca - Sistema de busca Sonic
• API de Campos - Gerenciamento de campos dinâmicos