Primeros Pasos

Aprende los conceptos básicos de la API de Reten — URL base, headers comunes, paginación y manejo de errores.

¿Qué es la API de Reten?

La API de Reten es una API REST para la plataforma SaaS multi-tenant Reten. Permite gestionar actividades de campo asignadas a comercios (negocios y tiendas), hacer seguimiento de resultados y configurar proveedores de despacho.

Capacidades principales:

Gestión de Actividades — Crear, despachar y hacer seguimiento de tareas para comercios
Seguimiento de Resultados — Enviar y consultar los resultados de ejecución de tareas
Gestión de Comercios y Operadores — Operaciones CRUD sobre comercios, operadores y rutas
Aislamiento Multi-Tenant — Cada tenant opera en un entorno completamente aislado

URL Base

La API de Reten está disponible en múltiples entornos. Usa la URL base correspondiente según tu etapa de integración:

Entorno	URL Base
Producción	`https://api.reten.ai/api`
Staging	`https://api-staging.reten.ai/api`
Desarrollo	`https://api-development.reten.ai/api`
Local	`http://localhost:3000/api`

Todos los ejemplos de código en esta documentación usan la URL de producción. Reemplaza https://api.reten.ai/api con la URL del entorno correspondiente cuando trabajes en staging o desarrollo.

Headers Comunes

Header	Requerido	Descripción
`Authorization`	Sí (auth JWT)	`Bearer <access_token>`
`x-api-key`	Sí (auth API Key)	`rtn_sk_<key>` — alternativa al Bearer token
`x-tenant-id`	Sí (auth JWT, rutas con scope de tenant)	UUID del tenant activo. No necesario con auth por API Key
`x-project-id`	Sí (rutas project-scoped); opcional (rutas project-optional)	UUID del proyecto activo. No necesario con una clave de proyecto — ver Autenticación → Contexto de Proyecto
`Content-Type`	Sí (para cuerpos de solicitud)	`application/json`

Paginación

Los endpoints de listado soportan paginación mediante parámetros de consulta:

Parámetro	Tipo	Valor por defecto	Descripción
`page`	number	1	Número de página (indexado desde 1)
`per_page`	number	25	Elementos por página (máximo `100`)

La respuesta incluye metadatos de paginación:

{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 150,
    "total_pages": 6,
    "has_next": true,
    "has_previous": false
  }
}

Respuestas de Error

Los errores siguen un formato consistente:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Campo	Tipo	Descripción
`statusCode`	number	Código de estado HTTP
`message`	string \| string[]	Descripción del problema
`error`	string	Nombre del error HTTP
`code`	string	Presente solo en los errores sobre los que un cliente tiene que ramificar. Es un valor estable en `UPPER_SNAKE`: ramifica por `code`, nunca por el texto de `message`, que puede cambiar. Hoy el único es `DEFAULT_ROOT_CONFIRMATION_REQUIRED` (ver Publicar Config)

Códigos de Estado Comunes

Código	Descripción
`200`	Éxito
`201`	Creado
`204`	Sin Contenido (operaciones de desactivación y eliminación)
`400`	Solicitud incorrecta (errores de validación)
`401`	No autorizado (token ausente o inválido)
`403`	Prohibido (permisos insuficientes o tenant incorrecto)
`404`	No Encontrado
`409`	Conflicto (clave de idempotencia duplicada, violación de restricción única)

Siguientes Pasos

Autenticación — Aprende a autenticarte con API keys o JWT
Roles y Permisos — Entiende la jerarquía de roles y el control de permisos
Integración Tareas — Comienza a integrar con el módulo de actividades de tipo tarea