---
type: template
name: contrato-api
description: Template canônico para especificação de contratos de API e schemas Zod
updatedAt: "2026-09-02"
---

<!--
DESTINO CANÔNICO NO PROJETO:
- Rota Dinâmica de IA (Pilar 5): servido dinamicamente pelo backend em /llm.md ou <modulo-caminho>llm.md
- Wiki de Desenvolvimento (Pilar 4): ../../wiki/dev/<modulo-id>/contratos/{servico}.contrato.md
-->

# Contrato de API — [Nome do Serviço / Endpoint]

- **Módulo:** `<modulo-id>`
- **Base URL:** `<modulo-caminho>api/v1/`
- **Autenticação:** Bearer Token JWT (Header `Authorization: Bearer <token>`)

---

## Tabela de Endpoints

| Método | Endpoint | Descrição | Permissão Requerida |
| :--- | :--- | :--- | :--- |
| `GET` | `/recurso` | Listar recursos com paginação | Leitura |
| `POST` | `/recurso` | Criar novo registro | Escrita |
| `GET` | `/recurso/:id` | Obter detalhes por ID | Leitura |
| `PUT` | `/recurso/:id` | Atualizar registro completo | Escrita |
| `DELETE` | `/recurso/:id` | Excluir logicamente o registro | Admin |

---

## Detalhamento: `POST /recurso`

### Request Body (Schema Zod: `zRecursoCriar`)
```typescript
import { z } from "zod";

export const zRecursoCriar = z.object({
  nome: z.string().min(3).max(100),
  tipo: z.enum(["TIPO_A", "TIPO_B"]),
  ativo: z.boolean().default(true),
});

export type RecursoCriar = z.infer<typeof zRecursoCriar>;
```

### Exemplo de Payload (JSON)
```json
{
  "nome": "Monitoramento Trimestral",
  "tipo": "TIPO_A",
  "ativo": true
}
```

### Resposta de Sucesso (`201 Created`)
```json
{
  "id": "uuid-v4-gerado",
  "nome": "Monitoramento Trimestral",
  "tipo": "TIPO_A",
  "ativo": true,
  "criadoEm": "2026-09-02T10:00:00Z"
}
```

### Respostas de Erro
- `400 Bad Request`: Payload não satisfaz o schema Zod (retorna array `erros: [{ campo, mensagem }]`).
- `401 Unauthorized`: Token ausente ou expirado.
- `403 Forbidden`: Usuário sem perfil de acesso para esta operação.