Respuestas de Oferta

Nuevo en v3

Este endpoint fue introducido en API v3 y no está disponible en versiones anteriores.

Endpoint

GET /api/v3/offer-responses

Descripción

Permite consultar en tiempo real las respuestas recibidas para una oferta de servicio activa. Retorna tanto las respuestas individuales de las centrales como la oferta aceptada (si ya existe una).

Este endpoint es útil para monitorear el estado del proceso de ofertamiento sin necesidad de esperar el webhook de aceptación.

Autenticación

Authorization: Basic <credenciales_base64>

Parámetros de Entrada

Headers

Content-Type: application/json
Authorization: Basic <credenciales>

Body (JSON)

Campo	Tipo	Requerido	Descripción
uuid	string (UUID)	Sí	Identificador único de la oferta a consultar

Ejemplo de Request

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

Respuestas

✅ Éxito - Oferta en proceso (200 OK)

Cuando la oferta está activa y hay respuestas pero aún no hay una aceptada:

{
  "status": true,
  "msg": "RESPUESTAS DE LA OFERTA",
  "data": {
    "responses": [
      {
        "distance": 3.2,
        "techCoords": {
          "latitud": "6.2400",
          "longitud": "-75.5800"
        },
        "tech_names": "Carlos Ramírez",
        "time": 12,
        "rate": 4.8
      },
      {
        "distance": 5.7,
        "techCoords": {
          "latitud": "6.2510",
          "longitud": "-75.5710"
        },
        "tech_names": "Juan Pérez",
        "time": 20,
        "rate": 4.5
      }
    ],
    "accepted": null
  }
}

✅ Éxito - Oferta aceptada (200 OK)

Cuando ya existe una oferta aceptada:

{
  "status": true,
  "msg": "RESPUESTAS DE LA OFERTA",
  "data": {
    "responses": [],
    "accepted": {
      "distance": 3.2,
      "techCoords": {
        "latitud": "6.2400",
        "longitud": "-75.5800"
      },
      "tech_names": "Carlos Ramírez",
      "time": 12,
      "rate": 4.8
    }
  }
}

Campos de respuesta

Campo	Tipo	Descripción
responses	array	Lista de respuestas recibidas de las centrales (vacía si ya hay una aceptada)
responses[].distance	number	Distancia del técnico al punto de servicio (km)
responses[].techCoords	object	Coordenadas actuales del técnico
responses[].techCoords.latitud	string	Latitud del técnico
responses[].techCoords.longitud	string	Longitud del técnico
responses[].tech_names	string	Nombre completo del técnico
responses[].time	number	Tiempo estimado de llegada (minutos)
responses[].rate	number	Calificación del técnico (1-5)
accepted	object|null	Oferta aceptada seleccionada, o null si aún no hay una

❌ Error - UUID no proporcionado (400 Bad Request)

{
  "status": false,
  "msg": "NO SE HA PROPORCIONADO EL UUID DE LA OFERTA",
  "data": []
}

❌ Error - Oferta no encontrada (403 Forbidden)

{
  "status": false,
  "msg": "NO SE HA ENCONTRADO LA OFERTA",
  "data": []
}

Ejemplos de Código

cURL

curl -X GET "[URL_API]/api/v3/offer-responses" \
  --user "tu_usuario:tu_password" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }'

JavaScript

const response = await fetch('[URL_API]/api/v3/offer-responses', {
  method: 'GET',
  headers: {
    'Authorization': `Basic ${btoa('usuario:password')}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uuid: '123e4567-e89b-12d3-a456-426614174000'
  })
});

const result = await response.json();

if (result.data.accepted) {
  console.log('Oferta aceptada por:', result.data.accepted.tech_names);
  console.log('Tiempo estimado:', result.data.accepted.time, 'minutos');
} else {
  console.log('Respuestas recibidas:', result.data.responses.length);
}

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    '[URL_API]/api/v3/offer-responses',
    auth=HTTPBasicAuth('usuario', 'password'),
    json={
        "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
)

result = response.json()

if result['data']['accepted']:
    print(f"Oferta aceptada por: {result['data']['accepted']['tech_names']}")
else:
    print(f"Respuestas recibidas: {len(result['data']['responses'])}")

Casos de uso

Polling durante el período de oferta

Durante los 30 segundos en que la oferta está abierta, puedes consultar este endpoint periódicamente para monitorear las respuestas en tiempo real:

// Polling cada 5 segundos durante la fase de oferta
const pollInterval = setInterval(async () => {
  const result = await fetch('[URL_API]/api/v3/offer-responses', {
    method: 'GET',
    headers: {
      'Authorization': `Basic ${btoa('usuario:password')}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ uuid: 'mi-uuid' })
  }).then(r => r.json());

  if (result.data.accepted) {
    clearInterval(pollInterval);
    console.log('Oferta aceptada, procediendo con asignación...');
    // Continuar con POST /api/v3/asignacion
  }
}, 5000);

Notas Importantes

• Este endpoint complementa el sistema de webhooks; úsalo cuando necesites consultar el estado de manera activa
• El campo accepted estará en null mientras el sistema evalúa las respuestas dentro del período de 30 segundos
• Una vez vencido el período y seleccionada la mejor oferta, accepted contendrá los datos del técnico seleccionado

Flujo Relacionado

POST /api/v3/oferta              → Crear oferta
GET  /api/v3/offer-responses     → Monitorear respuestas ← aquí
[Webhook de aceptación]          → Notificación automática
POST /api/v3/asignacion          → Completar asignación

---

Consejo

Combina este endpoint con el webhook de aceptación para mayor robustez: usa el webhook como notificación principal y este endpoint como mecanismo de verificación.