POST /v1/jobs

Crear Trabajo

Crea un trabajo borrador y envía SMS al cliente para completarlo en la app de ReciGo.

Importante: Este es un trabajo borrador

Esta llamada NO publica el trabajo inmediatamente a los ayudantes. Crea un borrador que el cliente debe completar en la app móvil. El cliente debe añadir su método de pago y publicar el trabajo.

POSThttps://api.recigo.es/v1/jobs

Crea un trabajo borrador y envía SMS al cliente con el enlace para completarlo.

Petición

Headers

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

Body

{
  "external_reference": "blocket-listing-12345",
  "title": "Mover sofá desde centro a las afueras",
  "description": "Sofá de 2 plazas en buen estado",
  "size": "L",
  "pickup": {
    "address": "Calle Gran Vía 1, Madrid"
  },
  "dropoff": {
    "address": "Calle Alcalá 100, Madrid"
  },
  "customer_phone": "+34612345678",
  "photos": [
    "https://tuplatforma.com/images/photo1.jpg",
    "https://tuplatforma.com/images/photo2.jpg"
  ]
}

Parámetros

external_referenceopcional

Tu ID interno para este trabajo. Útil para rastrear el trabajo en tu sistema.

Ejemplo: "blocket-listing-12345"

titlerequerido

Título descriptivo del trabajo.

Ejemplo: "Mover sofá de 2 plazas"

descriptionopcional

Descripción detallada del trabajo o artículo.

Ejemplo: "Sofá gris en buen estado, 2 plazas"

sizerequerido

Tamaño del artículo. Valores permitidos:

S- Pequeño (cabe en coche)

M- Mediano (requiere furgoneta pequeña)

L- Grande (requiere furgoneta grande)

XL- Extra Grande (requiere camión)

pickup.addressrequerido

Dirección completa de recogida. ReciGo geocodificará automáticamente para obtener lat/lon.

Ejemplo: "Calle Gran Vía 1, 28013 Madrid"

dropoff.addressrequerido

Dirección completa de entrega.

Ejemplo: "Calle Alcalá 100, 28009 Madrid"

customer_phonerequerido

Número de teléfono del cliente en formato E.164 (con código de país).

Ejemplo: "+34612345678"

photosopcional

Array de URLs de fotos públicas. ReciGo descargará, comprimirá y almacenará las imágenes automáticamente.

Máximo: 2MB por imagen

Ejemplo: ["https://tuplatforma.com/photo1.jpg"]

¿Qué Sucede?

ReciGo geocodifica las direcciones

Convierte las direcciones a coordenadas lat/lon

Descarga y comprime las fotos

Descarga desde tus URLs y las almacena en Supabase Storage (máx 2MB cada una)

Calcula el precio

Usa el motor de precios basado en tamaño, distancia y otros factores

Crea el trabajo borrador

Estado = "draft" (no visible para ayudantes todavía)

Envía SMS al cliente

El cliente recibe: "Tu trabajo de [TuEmpresa] está listo en ReciGo..."

Respuesta

201 Created

{
  "job_id": "abc123-def456-ghi789",
  "status": "draft",
  "external_reference": "blocket-listing-12345",
  "created_at": "2026-02-21T09:00:00Z",
  "deep_link_url": "recigo://draft/abc123?phone=%2B34612345678",
  "sms_sent": true,
  "pricing": {
    "base_price_eur": 45.00,
    "platform_fee_eur": 1.49,
    "total_customer_pays_eur": 46.49,
    "helper_payout_eur": 38.25,
    "calculation_breakdown": {
      "base_by_size": 30.00,
      "distance_km": 2.5,
      "distance_charge_eur": 12.00,
      "stairs_charge_eur": 0.00,
      "service_modifier": 1.0,
      "urgency_modifier": 0.0
    }
  },
  "photos": [
    "https://recigo-storage.supabase.co/job-photos/uuid1.jpg",
    "https://recigo-storage.supabase.co/job-photos/uuid2.jpg"
  ],
  "next_steps": {
    "action": "customer_must_complete_in_app",
    "message": "SMS enviado al cliente con enlace para completar en la app.",
    "expires_at": "2026-02-23T09:00:00Z"
  }
}

deep_link_url: Enlace que abre directamente el borrador en la app

sms_sent: Confirma que el SMS fue enviado

expires_at: El borrador expira en 48 horas si el cliente no lo completa

Mensaje SMS que Recibe el Cliente

Tu trabajo de [TuEmpresa] está listo en ReciGo.

📦 Mover sofá de 2 plazas
📍 Madrid → Las Rozas
💰 €46.49

Completa tu trabajo aquí:
https://recigo.es/draft/abc123?phone=%2B34612345678

Descarga ReciGo si no tienes la app.

Nota: [TuEmpresa] se reemplaza automáticamente con el nombre de tu empresa desde tu perfil de partner.

Errores Comunes

400

Datos inválidos

{
  "error": "validation_error",
  "message": "Datos del trabajo inválidos",
  "details": {
    "size": "Debe ser uno de: S, M, L, XL",
    "customer_phone": "Formato de teléfono inválido"
  }
}

400

Referencia externa duplicada

{
  "detail": "Ya existe un trabajo con external_reference 'blocket-listing-12345'"
}