Status: Approved · v2 · SPEC-API-OVERVIEW-001

depends_on: SPEC-DOMAIN-BASE-001, SPEC-ARCH-SECURITY-001

used_by: IS-ZERO-00.2, IS-MVP-15.1

Padrões gerais da API

Contrato transversal para todos os módulos REST do RaizFC.

Princípios e padrões

• Base path /api/v1; JSON UTF-8; chaves em camelCase.
• Toda resposta usa ApiResponse<T> com ok, data|error e meta contendo requestId e timestamp.
• IDs são strings opacas; datas são ISO-8601 UTC; dinheiro é inteiro em centavos com moeda BRL.
• Listas usam page e pageSize no MVP; default 20, máximo 100; metadados ficam em meta.pagination.
• Endpoints públicos usam DTOs públicos específicos; entidades internas, memberships, saldos e dados privados nunca vazam.
• Erros de domínio são estáveis e acionáveis; stack traces e detalhes internos não são retornados.
• Alterações sensíveis usam Idempotency-Key, confirmação recente quando necessário e audit log.
• Uploads usam fluxo presigned; o backend valida propósito, MIME, tamanho e ownership antes de confirmar o asset.

Endpoints

Método	Rota	Acesso	Request	Response	Regras principais
GET	/health	Público	—	HealthResponse	Status, versão e dependências essenciais.
POST	/uploads/presign	Autenticado	CreateUploadIntentRequest	CreateUploadIntentResponse	Retorna URL curta e asset pending.
POST	/uploads/:assetId/confirm	Autenticado	ConfirmUploadRequest	ConfirmUploadResponse	Confirma após verificar objeto e propósito.
GET	/assets/:assetId	Público/privado conforme asset	—	AssetResponse	Somente metadados autorizados.

Autenticação e autorização

• JWT access token via Authorization: Bearer nos endpoints protegidos.
• Refresh token rotacionado; logout invalida sessão correspondente.
• Guards de permissão sempre no backend; UI apenas orienta.
• OptionalAuthGuard pode enriquecer páginas públicas sem bloquear anônimos.

Erros de domínio

Código	HTTP	Quando ocorre	Ação esperada no cliente
VALIDATION_ERROR	422	Payload ou query inválidos	Mapear fieldErrors no formulário.
UNAUTHORIZED	401	Token ausente/inválido	Abrir login contextual.
PERMISSION_REQUIRED	403	Sem permission key	Explicar acesso e não repetir automaticamente.
NOT_FOUND	404	Recurso canônico não encontrado	Exibir estado 404; seguir redirect quando fornecido.
CONFLICT	409	Estado mudou ou ação duplicada	Recarregar contexto e informar conflito.
RATE_LIMITED	429	Limite excedido	Respeitar retryAfterSeconds.
INTERNAL_ERROR	500	Falha inesperada	Exibir requestId para suporte.

Idempotência e concorrência

• Idempotency-Key obrigatório em pagamentos, transferências, consumo de créditos, publicação paga, geração de fixtures e ações críticas explicitadas nas specs.
• Mesma chave + mesmo payload retorna resultado original; mesma chave + payload diferente retorna IDEMPOTENCY_CONFLICT.
• Operações usam optimistic concurrency/version quando colisão de edição for relevante.

Auditoria e efeitos colaterais

• Request ID é gerado/propagado em toda requisição.
• Audit log é separado de log técnico.
• Notificações e eventos derivados só acontecem após persistência consistente.

Exemplos

success

{
  "ok": true,
  "data": {
    "resource": {
      "id": "team_001"
    }
  },
  "meta": {
    "requestId": "req_001",
    "timestamp": "2026-07-12T18:00:00.000Z"
  }
}

validation

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Revise os campos informados.",
    "fieldErrors": [
      {
        "field": "name",
        "code": "TOO_SHORT",
        "message": "Informe ao menos 3 caracteres."
      }
    ]
  },
  "meta": {
    "requestId": "req_002",
    "timestamp": "2026-07-12T18:00:00.000Z"
  }
}

Mocks

• MockClient implementa a mesma interface do ApiClient e retorna o mesmo envelope.
• Cenários default, empty, error e rich; erros podem ser selecionados por rota.
• Network errors são convertidos em falha de client, não erro de domínio falso.

Testes obrigatórios

• Contract tests do envelope e serialização.
• Guards 401/403.
• Paginação e limite máximo.
• Sanitização de erros.
• Idempotência.
• Upload purpose/ownership.

Critérios de aceite

• Todos os endpoints obedecem envelope e tipos base.
• Nenhum endpoint público retorna DTO interno.
• Request ID aparece em sucesso e erro.
• Dinheiro nunca é float.
• Uploads e ações sensíveis são auditáveis.

Machine summary

spec: SPEC-API-OVERVIEW-001
api_group: Padrões gerais da API
base_path: /api/v1
response_envelope: ApiResponse<T>
ids: string
dates: ISO-8601
money: integer_cents