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 y mensajes 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
`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)
`limit`	number	20	Elementos por página

La respuesta incluye metadatos de paginación:

{
  "data": [],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Respuestas de Error

Los errores siguen un formato consistente:

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

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