POST /v1/pricing/estimate

Obtén una estimación de precio antes de crear un trabajo.

Descripción

Este endpoint te permite calcular el precio estimado de un trabajo antes de crearlo. Es útil para mostrar a tus usuarios el costo aproximado basado en el tamaño del objeto y las direcciones de recogida y entrega.

Importante: Este es un precio aproximado. El precio final puede variar ligeramente cuando se cree el trabajo real debido a ajustes en la geocodificación o cálculos de distancia.

Endpoint

POST https://api.recigo.es/v1/pricing/estimate

Headers

X-API-Key: recigo_live_abc123...
Content-Type: application/json

Parámetros del Request Body

sizerequerido

string

Tamaño del objeto a transportar. Valores permitidos:

S - Pequeño (cabe en un coche)
M - Mediano (necesita maletero grande)
L - Grande (necesita furgoneta pequeña)
XL - Extra grande (necesita furgoneta grande)

pickuprequerido

object

Dirección de recogida.

address*

Dirección completa en formato de texto (ej: "Calle Gran Vía 1, Madrid")

flooropcional

Número de piso (usado para calcular cargo por escaleras)

has_elevatoropcional

boolean - Si hay ascensor disponible (afecta cargo por escaleras)

dropoffrequerido

object

Dirección de entrega.

address*

Dirección completa en formato de texto (ej: "Calle Alcalá 100, Madrid")

flooropcional

Número de piso (usado para calcular cargo por escaleras)

has_elevatoropcional

boolean - Si hay ascensor disponible (afecta cargo por escaleras)

Ejemplo de Request

POST /v1/pricing/estimate

{
  "size": "L",
  "pickup": {
    "address": "Calle Gran Vía 1, Madrid",
    "floor": 3,
    "has_elevator": false
  },
  "dropoff": {
    "address": "Calle Alcalá 100, Madrid",
    "floor": 1,
    "has_elevator": true
  }
}

Respuesta Exitosa (200 OK)

{
  "base_price_eur": 45.00,
  "platform_fee_eur": 1.49,
  "total_customer_pays_eur": 46.49,
  "helper_receives_eur": 38.25,
  "calculation_breakdown": {
    "base_by_size": 30.00,
    "distance_km": 2.5,
    "distance_charge_eur": 12.00,
    "stairs_charge_eur": 3.00,
    "service_modifier": 1.0,
    "urgency_modifier": 0.0
  },
  "estimated_duration_minutes": 90,
  "disclaimer": "Este es un precio aproximado. El precio final puede variar."
}

Campos de la Respuesta

base_price_eur

Precio base del trabajo en euros (antes de comisión de plataforma)

platform_fee_eur

Comisión de la plataforma ReciGo en euros

total_customer_pays_eur

Total que pagará el cliente (base_price + platform_fee)

helper_receives_eur

Cantidad que recibirá el transportista

calculation_breakdown

Desglose detallado del cálculo del precio

estimated_duration_minutes

Duración estimada del trabajo en minutos

disclaimer

Aviso legal sobre la estimación de precio

Códigos de Error

400Bad Request

Datos de entrada inválidos

{
  "error": "validation_error",
  "message": "Datos de estimación inválidos",
  "details": {
    "size": "Debe ser uno de: S, M, L, XL",
    "pickup.address": "Dirección de recogida es requerida"
  }
}

401Unauthorized

API key inválida o faltante

{
  "error": "unauthorized",
  "message": "API key inválida o faltante"
}

422Unprocessable Entity

No se pudo geocodificar la dirección

{
  "error": "geocoding_failed",
  "message": "No se pudo geocodificar una o más direcciones",
  "details": {
    "pickup.address": "Dirección no encontrada"
  }
}

429Too Many Requests

Límite de tasa excedido

{
  "error": "rate_limit_exceeded",
  "message": "Has excedido el límite de solicitudes",
  "retry_after_seconds": 60
}

Notas Importantes

📍 Geocodificación Automática

ReciGo geocodifica automáticamente las direcciones proporcionadas para calcular la distancia exacta. Asegúrate de proporcionar direcciones completas y válidas.

💰 Cálculo de Precio

El precio se calcula basándose en:

Tamaño del objeto (S/M/L/XL)
Distancia entre recogida y entrega
Número de pisos y disponibilidad de ascensor
Tipo de servicio (siempre "mover_entregar" para partners)
Urgencia (siempre "programado" para partners, sin cargo extra)

⚡ Valores Predeterminados

Los siguientes valores son siempre predeterminados para trabajos de partners:

Tipo de servicio: mover_entregar
Urgencia: programado (sin cargo extra)
Segunda persona: false

⚠️ Precio Aproximado

Siempre muestra el disclaimer a tus usuarios: "Este es un precio aproximado. El precio final puede variar." El precio final se calcula cuando se crea el trabajo real y puede diferir ligeramente debido a ajustes en la geocodificación.

Siguiente Paso

Una vez que hayas mostrado el precio estimado a tu usuario y esté listo para continuar, puedes crear el trabajo usando el endpoint de creación de trabajos.

Ver Endpoint de Creación de Trabajos →