Documentacion API REST

Integra AuditWaste con tu ERP, POS o cualquier sistema de gestion. Todos los endpoints devuelven JSON y usan autenticacion por API Key.

URL base: https://auditwaste.com

1. Autenticacion

Todas las llamadas a la API requieren autenticacion via header Authorization.

Formato del header

Authorization: Bearer aw_live_tu_clave_aqui

Obtener tu API Key

Accede a tu dashboard en Configuracion > API Keys.
Haz clic en “Generar nueva clave”.
Copia la clave — solo se muestra una vez.
Incluye la clave en cada peticion como header Authorization: Bearer aw_live_...

Seguridad: Las API keys dan acceso completo a tu establecimiento. Nunca las expongas en codigo frontend, repositorios publicos o logs. Usa variables de entorno en tu servidor.

Tipos de clave

Prefijo	Entorno	Uso
aw_live_	Produccion	Datos reales, integraciones de produccion
aw_test_	Test	Desarrollo e integracion, datos de prueba

2. Registros de Merma

Crear y consultar registros de desperdicio alimentario.

POST/api/v1/records

Crear un registro individual de merma.

Campos requeridos

Campo	Tipo	Descripcion
food_category	string	Categoria: meat, fish, fruit_veg, dairy, bakery, prepared_meals, cereals, beverages, others
weight_kg	number	Peso en kilogramos (>0)
destino_id	uuid	ID del destino de la merma

Campos opcionales

Campo	Tipo	Descripcion
causa_id	uuid	ID de la causa de merma
product_name	string	Nombre del producto
waste_stage	string	Etapa: receiving, storage, preparation, service, post_service
shift_id	uuid	ID del turno activo
notes	string	Observaciones (max 500 caracteres)
photo_url	string	URL de foto del registro

Ejemplo de peticion (cURL)

curl -X POST https://auditwaste.com/api/v1/records \
  -H "Authorization: Bearer aw_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "food_category": "meat",
    "weight_kg": 2.5,
    "destino_id": "uuid-del-destino",
    "causa_id": "uuid-de-la-causa",
    "product_name": "Solomillo de ternera",
    "waste_stage": "preparation",
    "notes": "Recortes no aprovechables"
  }'

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "id": "uuid-del-registro",
    "establishment_id": "uuid-establecimiento",
    "food_category": "meat",
    "weight_kg": 2.5,
    "record_hash": "sha256...",
    "created_at": "2026-04-03T10:30:00Z"
  },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

POST/api/v1/records/batch

Crear hasta 500 registros en una sola llamada. Ideal para integraciones con ERP o importaciones masivas.

Campos requeridos

Campo	Tipo	Descripcion
records	array	Array de registros (max 500). Cada uno con los mismos campos que POST /api/v1/records.

Ejemplo de peticion (cURL)

curl -X POST https://auditwaste.com/api/v1/records/batch \
  -H "Authorization: Bearer aw_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "food_category": "fish", "weight_kg": 1.2, "destino_id": "uuid-1" },
      { "food_category": "dairy", "weight_kg": 0.8, "destino_id": "uuid-2" }
    ]
  }'

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "inserted": 2,
    "failed": 0,
    "errors": []
  },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

Maximo 500 registros por llamada. Los registros que fallen la validacion se reportan individualmente en el array errors.

GET/api/v1/records

Consultar registros de merma con filtros opcionales.

Campos opcionales

Campo	Tipo	Descripcion
from	string (ISO date)	Fecha inicio (default: hace 30 dias)
to	string (ISO date)	Fecha fin (default: hoy)
food_category	string	Filtrar por categoria
limit	number	Registros por pagina (default: 50, max: 200)
offset	number	Offset para paginacion

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/records?from=2026-03-01&to=2026-03-31&food_category=meat&limit=50" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "food_category": "meat",
      "weight_kg": 2.5,
      "product_name": "Solomillo",
      "created_at": "2026-03-15T10:30:00Z"
    }
  ],
  "meta": {
    "pagination": { "limit": 50, "offset": 0, "total": 127 }
  },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

3. Webhooks Entrantes

Recibe datos desde tu ERP, POS o sistema de gestion.

POST/api/v1/webhooks/inbound

Endpoint para recibir eventos desde sistemas externos (ERP, POS). Convierte automaticamente los datos al formato de AuditWaste.

Campos requeridos

Campo	Tipo	Descripcion
event	string	Tipo de evento: waste.created, waste.updated, inventory.loss
payload	object	Datos del evento segun el tipo

Ejemplo de peticion (cURL)

curl -X POST https://auditwaste.com/api/v1/webhooks/inbound \
  -H "Authorization: Bearer aw_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "waste.created",
    "payload": {
      "food_category": "prepared_meals",
      "weight_kg": 3.0,
      "destino_id": "uuid-destino",
      "source": "erp_sap"
    }
  }'

Ejemplo de respuesta

{
  "success": true,
  "data": { "event_id": "uuid-evento", "status": "processed" },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

4. Catalogos (Lectura)

Consulta los catalogos de tu establecimiento: causas, destinos, productos y establecimientos.

GET/api/v1/causas

Lista todas las causas de merma activas del establecimiento.

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/causas" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": "uuid", "nombre": "Caducidad", "icono": "calendar_today", "activo": true },
    { "id": "uuid", "nombre": "Sobreproduccion", "icono": "trending_up", "activo": true }
  ],
  "timestamp": "2026-04-03T10:30:00.123Z"
}

GET/api/v1/destinos

Lista todos los destinos de merma del establecimiento.

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/destinos" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": "uuid", "nombre": "Uso interno", "orden": 1, "es_recuperacion": true },
    { "id": "uuid", "nombre": "Donacion", "orden": 2, "es_recuperacion": true },
    { "id": "uuid", "nombre": "Basura", "orden": 6, "es_recuperacion": false }
  ],
  "timestamp": "2026-04-03T10:30:00.123Z"
}

GET/api/v1/establishments

Lista los establecimientos accesibles con tu API key.

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/establishments" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": "uuid", "name": "Restaurante Central", "cif": "B12345678" }
  ],
  "timestamp": "2026-04-03T10:30:00.123Z"
}

GET/api/v1/products

Lista los productos del catalogo del establecimiento.

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/products" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": "uuid", "name": "Solomillo de ternera", "food_category": "meat", "ean": "8412345678901" }
  ],
  "timestamp": "2026-04-03T10:30:00.123Z"
}

5. Analytics

Consulta datos analiticos y benchmarking sectorial.

GET/api/v1/analytics

Metricas de merma del establecimiento: totales, por categoria, por destino, tendencias.

Campos opcionales

Campo	Tipo	Descripcion
from	string (ISO date)	Fecha inicio
to	string (ISO date)	Fecha fin
group_by	string	Agrupar por: day, week, month

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/analytics?from=2026-03-01&to=2026-03-31&group_by=week" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "total_kg": 245.8,
    "total_records": 87,
    "by_category": { "meat": 45.2, "fish": 32.1, "dairy": 18.5 },
    "by_destino": { "uso_interno": 120.3, "donacion": 45.2, "basura": 80.3 },
    "trend": [
      { "period": "2026-W10", "total_kg": 62.3 },
      { "period": "2026-W11", "total_kg": 58.1 }
    ]
  },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

GET/api/v1/benchmarking

Comparativa anonima con otros establecimientos de tu sector.

Campos opcionales

Campo	Tipo	Descripcion
sector	string	Sector: horeca, industrial, retail, distribucion, colectividades

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/benchmarking?sector=horeca" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "your_avg_kg_per_day": 8.2,
    "sector_avg_kg_per_day": 12.5,
    "percentile": 72,
    "sector": "horeca",
    "sample_size": 150
  },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

Requiere plan Enterprise. Los datos de benchmarking son anonimos y agregados.

6. Turnos

Gestion de turnos de trabajo para segmentar registros por turno.

GET/api/v1/shifts

Lista los turnos configurados del establecimiento.

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/shifts" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": "uuid", "name": "Manana", "start_time": "07:00", "end_time": "15:00" },
    { "id": "uuid", "name": "Tarde", "start_time": "15:00", "end_time": "23:00" }
  ],
  "timestamp": "2026-04-03T10:30:00.123Z"
}

POST/api/v1/shifts

Crear un nuevo turno.

Campos requeridos

Campo	Tipo	Descripcion
name	string	Nombre del turno
start_time	string (HH:MM)	Hora de inicio
end_time	string (HH:MM)	Hora de fin

Ejemplo de peticion (cURL)

curl -X POST https://auditwaste.com/api/v1/shifts \
  -H "Authorization: Bearer aw_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Noche",
    "start_time": "23:00",
    "end_time": "07:00"
  }'

Ejemplo de respuesta

{
  "success": true,
  "data": { "id": "uuid-turno", "name": "Noche", "start_time": "23:00", "end_time": "07:00" },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

7. Limites de Rate

Todas las llamadas a la API estan sujetas a limites de tasa para garantizar la estabilidad del servicio.

Endpoint	Limite	Ventana
Endpoints generales	10 peticiones	Por minuto, por API key
POST /api/v1/records	30 peticiones	Por minuto, por API key
POST /api/v1/records/batch	500 registros	Por llamada (max tamanio batch)
GET /api/v1/analytics	10 peticiones	Por hora, por API key

Headers de respuesta: Todas las respuestas incluyen los headers X-RateLimit-Limit, X-RateLimit-Remaining y Retry-After (cuando se excede el limite).

8. Errores

La API usa codigos HTTP estandar. Todas las respuestas de error incluyen un JSON con el campo error.

400Bad Request

Datos de entrada invalidos o campos requeridos ausentes.

{ "error": "weight_kg es obligatorio", "status": 400, "timestamp": "..." }

401Unauthorized

API key ausente, invalida o revocada.

{ "error": "Invalid API key", "status": 401, "timestamp": "..." }

403Forbidden

La API key no tiene permisos para esta operacion, o el plan no lo permite.

{ "error": "Plan does not include this feature", "status": 403, "timestamp": "..." }

429Too Many Requests

Limite de rate excedido. Incluye header Retry-After.

{ "error": "Rate limit exceeded", "status": 429, "resetAt": "2026-04-03T10:31:00Z" }

500Internal Server Error

Error interno del servidor. Contacta soporte si persiste.

{ "error": "Internal server error", "status": 500, "timestamp": "..." }

9. Webhooks Salientes

AuditWaste puede enviar notificaciones HTTP a tu servidor cuando ocurren eventos relevantes. Configura tu endpoint en Dashboard > Integraciones.

Eventos disponibles

Evento	Descripcion
record.created	Se ha creado un nuevo registro de merma.
record.updated	Se ha actualizado un registro existente.
subscription.changed	El plan de suscripcion ha cambiado.
subscription.canceled	La suscripcion ha sido cancelada.
alert.spike_detected	Se ha detectado un pico de merma inusual.
plan.generated	Se ha generado un nuevo Plan de Prevencion (PPDA).

Formato del payload

{
  "event": "record.created",
  "timestamp": "2026-04-03T10:30:00.123Z",
  "data": {
    "id": "uuid-del-registro",
    "establishment_id": "uuid-establecimiento",
    "food_category": "meat",
    "weight_kg": 2.5,
    "created_at": "2026-04-03T10:30:00Z"
  }
}

Verificacion de firma

Cada webhook incluye un header X-AuditWaste-Signature con un HMAC-SHA256 del body usando tu webhook secret. Verifica la firma antes de procesar el evento.

# Verificacion en bash
echo -n "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}'

Politica de reintentos

AuditWaste espera una respuesta HTTP 2xx en menos de 10 segundos.
Si la entrega falla, se reintenta hasta 5 veces con backoff exponencial: 1 min, 5 min, 30 min, 2 h, 12 h.
Tras 5 fallos consecutivos, el webhook se desactiva y se notifica por email al administrador.
Los webhooks desactivados se pueden reactivar manualmente desde el dashboard.

Documentacion API REST

Integra AuditWaste con tu ERP, POS o cualquier sistema de gestion. Todos los endpoints devuelven JSON y usan autenticacion por API Key.

URL base: https://auditwaste.com

1. Autenticacion

Todas las llamadas a la API requieren autenticacion via header Authorization.

Formato del header

Authorization: Bearer aw_live_tu_clave_aqui

Obtener tu API Key

Accede a tu dashboard en Configuracion > API Keys.
Haz clic en “Generar nueva clave”.
Copia la clave — solo se muestra una vez.
Incluye la clave en cada peticion como header Authorization: Bearer aw_live_...

Seguridad: Las API keys dan acceso completo a tu establecimiento. Nunca las expongas en codigo frontend, repositorios publicos o logs. Usa variables de entorno en tu servidor.

Tipos de clave

Prefijo	Entorno	Uso
aw_live_	Produccion	Datos reales, integraciones de produccion
aw_test_	Test	Desarrollo e integracion, datos de prueba

2. Registros de Merma

Crear y consultar registros de desperdicio alimentario.

POST/api/v1/records

Crear un registro individual de merma.

Campos requeridos

Campo	Tipo	Descripcion
food_category	string	Categoria: meat, fish, fruit_veg, dairy, bakery, prepared_meals, cereals, beverages, others
weight_kg	number	Peso en kilogramos (>0)
destino_id	uuid	ID del destino de la merma

Campos opcionales

Campo	Tipo	Descripcion
causa_id	uuid	ID de la causa de merma
product_name	string	Nombre del producto
waste_stage	string	Etapa: receiving, storage, preparation, service, post_service
shift_id	uuid	ID del turno activo
notes	string	Observaciones (max 500 caracteres)
photo_url	string	URL de foto del registro

Ejemplo de peticion (cURL)

curl -X POST https://auditwaste.com/api/v1/records \
  -H "Authorization: Bearer aw_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "food_category": "meat",
    "weight_kg": 2.5,
    "destino_id": "uuid-del-destino",
    "causa_id": "uuid-de-la-causa",
    "product_name": "Solomillo de ternera",
    "waste_stage": "preparation",
    "notes": "Recortes no aprovechables"
  }'

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "id": "uuid-del-registro",
    "establishment_id": "uuid-establecimiento",
    "food_category": "meat",
    "weight_kg": 2.5,
    "record_hash": "sha256...",
    "created_at": "2026-04-03T10:30:00Z"
  },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

POST/api/v1/records/batch

Crear hasta 500 registros en una sola llamada. Ideal para integraciones con ERP o importaciones masivas.

Campos requeridos

Campo	Tipo	Descripcion
records	array	Array de registros (max 500). Cada uno con los mismos campos que POST /api/v1/records.

Ejemplo de peticion (cURL)

curl -X POST https://auditwaste.com/api/v1/records/batch \
  -H "Authorization: Bearer aw_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "food_category": "fish", "weight_kg": 1.2, "destino_id": "uuid-1" },
      { "food_category": "dairy", "weight_kg": 0.8, "destino_id": "uuid-2" }
    ]
  }'

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "inserted": 2,
    "failed": 0,
    "errors": []
  },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

Maximo 500 registros por llamada. Los registros que fallen la validacion se reportan individualmente en el array errors.

GET/api/v1/records

Consultar registros de merma con filtros opcionales.

Campos opcionales

Campo	Tipo	Descripcion
from	string (ISO date)	Fecha inicio (default: hace 30 dias)
to	string (ISO date)	Fecha fin (default: hoy)
food_category	string	Filtrar por categoria
limit	number	Registros por pagina (default: 50, max: 200)
offset	number	Offset para paginacion

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/records?from=2026-03-01&to=2026-03-31&food_category=meat&limit=50" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "food_category": "meat",
      "weight_kg": 2.5,
      "product_name": "Solomillo",
      "created_at": "2026-03-15T10:30:00Z"
    }
  ],
  "meta": {
    "pagination": { "limit": 50, "offset": 0, "total": 127 }
  },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

3. Webhooks Entrantes

Recibe datos desde tu ERP, POS o sistema de gestion.

POST/api/v1/webhooks/inbound

Endpoint para recibir eventos desde sistemas externos (ERP, POS). Convierte automaticamente los datos al formato de AuditWaste.

Campos requeridos

Campo	Tipo	Descripcion
event	string	Tipo de evento: waste.created, waste.updated, inventory.loss
payload	object	Datos del evento segun el tipo

Ejemplo de peticion (cURL)

curl -X POST https://auditwaste.com/api/v1/webhooks/inbound \
  -H "Authorization: Bearer aw_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "waste.created",
    "payload": {
      "food_category": "prepared_meals",
      "weight_kg": 3.0,
      "destino_id": "uuid-destino",
      "source": "erp_sap"
    }
  }'

Ejemplo de respuesta

{
  "success": true,
  "data": { "event_id": "uuid-evento", "status": "processed" },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

4. Catalogos (Lectura)

Consulta los catalogos de tu establecimiento: causas, destinos, productos y establecimientos.

GET/api/v1/causas

Lista todas las causas de merma activas del establecimiento.

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/causas" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": "uuid", "nombre": "Caducidad", "icono": "calendar_today", "activo": true },
    { "id": "uuid", "nombre": "Sobreproduccion", "icono": "trending_up", "activo": true }
  ],
  "timestamp": "2026-04-03T10:30:00.123Z"
}

GET/api/v1/destinos

Lista todos los destinos de merma del establecimiento.

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/destinos" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": "uuid", "nombre": "Uso interno", "orden": 1, "es_recuperacion": true },
    { "id": "uuid", "nombre": "Donacion", "orden": 2, "es_recuperacion": true },
    { "id": "uuid", "nombre": "Basura", "orden": 6, "es_recuperacion": false }
  ],
  "timestamp": "2026-04-03T10:30:00.123Z"
}

GET/api/v1/establishments

Lista los establecimientos accesibles con tu API key.

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/establishments" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": "uuid", "name": "Restaurante Central", "cif": "B12345678" }
  ],
  "timestamp": "2026-04-03T10:30:00.123Z"
}

GET/api/v1/products

Lista los productos del catalogo del establecimiento.

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/products" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": "uuid", "name": "Solomillo de ternera", "food_category": "meat", "ean": "8412345678901" }
  ],
  "timestamp": "2026-04-03T10:30:00.123Z"
}

5. Analytics

Consulta datos analiticos y benchmarking sectorial.

GET/api/v1/analytics

Metricas de merma del establecimiento: totales, por categoria, por destino, tendencias.

Campos opcionales

Campo	Tipo	Descripcion
from	string (ISO date)	Fecha inicio
to	string (ISO date)	Fecha fin
group_by	string	Agrupar por: day, week, month

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/analytics?from=2026-03-01&to=2026-03-31&group_by=week" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "total_kg": 245.8,
    "total_records": 87,
    "by_category": { "meat": 45.2, "fish": 32.1, "dairy": 18.5 },
    "by_destino": { "uso_interno": 120.3, "donacion": 45.2, "basura": 80.3 },
    "trend": [
      { "period": "2026-W10", "total_kg": 62.3 },
      { "period": "2026-W11", "total_kg": 58.1 }
    ]
  },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

GET/api/v1/benchmarking

Comparativa anonima con otros establecimientos de tu sector.

Campos opcionales

Campo	Tipo	Descripcion
sector	string	Sector: horeca, industrial, retail, distribucion, colectividades

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/benchmarking?sector=horeca" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": {
    "your_avg_kg_per_day": 8.2,
    "sector_avg_kg_per_day": 12.5,
    "percentile": 72,
    "sector": "horeca",
    "sample_size": 150
  },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

Requiere plan Enterprise. Los datos de benchmarking son anonimos y agregados.

6. Turnos

Gestion de turnos de trabajo para segmentar registros por turno.

GET/api/v1/shifts

Lista los turnos configurados del establecimiento.

Ejemplo de peticion (cURL)

curl "https://auditwaste.com/api/v1/shifts" \
  -H "Authorization: Bearer aw_live_xxxxx"

Ejemplo de respuesta

{
  "success": true,
  "data": [
    { "id": "uuid", "name": "Manana", "start_time": "07:00", "end_time": "15:00" },
    { "id": "uuid", "name": "Tarde", "start_time": "15:00", "end_time": "23:00" }
  ],
  "timestamp": "2026-04-03T10:30:00.123Z"
}

POST/api/v1/shifts

Crear un nuevo turno.

Campos requeridos

Campo	Tipo	Descripcion
name	string	Nombre del turno
start_time	string (HH:MM)	Hora de inicio
end_time	string (HH:MM)	Hora de fin

Ejemplo de peticion (cURL)

curl -X POST https://auditwaste.com/api/v1/shifts \
  -H "Authorization: Bearer aw_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Noche",
    "start_time": "23:00",
    "end_time": "07:00"
  }'

Ejemplo de respuesta

{
  "success": true,
  "data": { "id": "uuid-turno", "name": "Noche", "start_time": "23:00", "end_time": "07:00" },
  "timestamp": "2026-04-03T10:30:00.123Z"
}

7. Limites de Rate

Todas las llamadas a la API estan sujetas a limites de tasa para garantizar la estabilidad del servicio.

Endpoint	Limite	Ventana
Endpoints generales	10 peticiones	Por minuto, por API key
POST /api/v1/records	30 peticiones	Por minuto, por API key
POST /api/v1/records/batch	500 registros	Por llamada (max tamanio batch)
GET /api/v1/analytics	10 peticiones	Por hora, por API key

Headers de respuesta: Todas las respuestas incluyen los headers X-RateLimit-Limit, X-RateLimit-Remaining y Retry-After (cuando se excede el limite).

8. Errores

La API usa codigos HTTP estandar. Todas las respuestas de error incluyen un JSON con el campo error.

400Bad Request

Datos de entrada invalidos o campos requeridos ausentes.

{ "error": "weight_kg es obligatorio", "status": 400, "timestamp": "..." }

401Unauthorized

API key ausente, invalida o revocada.

{ "error": "Invalid API key", "status": 401, "timestamp": "..." }

403Forbidden

La API key no tiene permisos para esta operacion, o el plan no lo permite.

{ "error": "Plan does not include this feature", "status": 403, "timestamp": "..." }

429Too Many Requests

Limite de rate excedido. Incluye header Retry-After.

{ "error": "Rate limit exceeded", "status": 429, "resetAt": "2026-04-03T10:31:00Z" }

500Internal Server Error

Error interno del servidor. Contacta soporte si persiste.

{ "error": "Internal server error", "status": 500, "timestamp": "..." }

9. Webhooks Salientes

AuditWaste puede enviar notificaciones HTTP a tu servidor cuando ocurren eventos relevantes. Configura tu endpoint en Dashboard > Integraciones.

Eventos disponibles

Evento	Descripcion
record.created	Se ha creado un nuevo registro de merma.
record.updated	Se ha actualizado un registro existente.
subscription.changed	El plan de suscripcion ha cambiado.
subscription.canceled	La suscripcion ha sido cancelada.
alert.spike_detected	Se ha detectado un pico de merma inusual.
plan.generated	Se ha generado un nuevo Plan de Prevencion (PPDA).

Formato del payload

{
  "event": "record.created",
  "timestamp": "2026-04-03T10:30:00.123Z",
  "data": {
    "id": "uuid-del-registro",
    "establishment_id": "uuid-establecimiento",
    "food_category": "meat",
    "weight_kg": 2.5,
    "created_at": "2026-04-03T10:30:00Z"
  }
}

Verificacion de firma

Cada webhook incluye un header X-AuditWaste-Signature con un HMAC-SHA256 del body usando tu webhook secret. Verifica la firma antes de procesar el evento.

# Verificacion en bash
echo -n "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}'

Politica de reintentos

AuditWaste espera una respuesta HTTP 2xx en menos de 10 segundos.
Si la entrega falla, se reintenta hasta 5 veces con backoff exponencial: 1 min, 5 min, 30 min, 2 h, 12 h.
Tras 5 fallos consecutivos, el webhook se desactiva y se notifica por email al administrador.
Los webhooks desactivados se pueden reactivar manualmente desde el dashboard.