72 lines
1.9 KiB
Text
72 lines
1.9 KiB
Text
---
|
|
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.
|