Convención de Postman — Camaroneras API

Guía para que todo el equipo organice y use Postman de la misma forma.

Workspace

• Usar un workspace propio/editable (Personal o Team "Camaroneras").
• Si aparece "Request to edit" o el botón Save está gris, estás en un workspace de solo lectura → cambiar de workspace.

Estructura de la Collection

Una sola Collection llamada Camaroneras API, con una carpeta por módulo del backend. Solo se agregan carpetas/requests de módulos que ya existen en el backend.

📁 Camaroneras API                    ← Collection (variables y auth aquí)
├── 📁 Health
│   └── GET  health check             {{base_url}}/health
├── 📁 Auth                           (se agrega en su tarea)
├── 📁 Organizations                  (se agrega en su tarea)
├── 📁 Users                          (se agrega en su tarea)
├── 📁 Roles                          (se agrega en su tarea)
├── 📁 Estanques                      (se agrega en su tarea)
├── 📁 Inventario                     (se agrega en su tarea)
└── 📁 Alimentacion                   (se agrega en su tarea)

Variables

Definidas a nivel de Collection (o Environment "Local" si se manejan varios entornos):

Variable	Valor (dev)	Notas
base_url	http://localhost:3000/api/v1	URL base con prefijo. Usar como /...
access_token	(se llena solo)	Se setea por script tras sign-in
refresh_token	(se llena solo)	Se setea por script tras sign-in
org_id	(manual)	ID de la organización en pruebas

Autenticación

• A nivel de Collection → Authorization: Bearer Token = .
• Todos los requests heredan el token automáticamente.
• Los endpoints públicos (Health, sign-in, sign-up) se ponen en No Auth.

Script para guardar el token automáticamente

En el request Sign in → pestaña Scripts → Post-response:

const res = pm.response.json();
pm.collectionVariables.set("access_token", res.data.accessToken);
pm.collectionVariables.set("refresh_token", res.data.refreshToken);

Nomenclatura de requests

• Nombre descriptivo en español: "Crear usuario", "Listar roles", "Asignar permisos".
• El método HTTP lo indica Postman (GET/POST/etc.), no repetirlo en el nombre.

Entornos (cuando aplique)

Environment	base_url
Local	http://localhost:3000/api/v1
Producción	https://api.camaroneras.com/api/v1

Cambiar de entorno con el selector superior derecho, sin tocar los requests.