gupp
ServiciosCómo funcionaSé proveedorPreguntas
Descarga la app

Güpp para desarrolladores

Pide grúas y asistencia en vía desde tu sistema, recibe cada cambio por webhook, o deja que un agente de IA actúe por tus usuarios con el servidor MCP.

  • Cómo integrarte
  • API de aliados
    • Autenticación
    • Endpoints
    • Crear una orden
    • Estados y PIN
    • Cancelaciones
    • Errores y límites
  • Webhooks
    • Eventos
    • Verificar la firma
  • Servidor MCP
    • OAuth y consentimiento
    • Herramientas
    • Conectar en Claude

Cómo integrarte

API de aliadosServidor MCP
ParaAseguradoras, flotas, concesionarios y plataformas (B2B)Usuarios de Güpp desde Claude, ChatGPT u otro agente de IA
AutenticaciónX-API-Key: gk_live_… (la entrega Güpp)OAuth 2.1 con registro dinámico y PKCE; el usuario entra con su celular
Actúa comoTu empresa: las órdenes se te facturanEl usuario que autorizó: cobra como en la app
Base/api/partner/v1/mcp

Para obtener una API key escríbenos a aliados@gupp.co. El equipo de Güpp crea tu cuenta de aliado, genera la llave con los permisos que necesitas y configura tu webhook.

API de aliados

API REST con JSON. Todas las rutas cuelgan de https://api-sandbox-3e2d10e3.up.railway.app/api/partner/v1. Los valores de dinero son pesos colombianos enteros (150000 = $150.000) y las fechas van en ISO 8601 con zona horaria.

Autenticación

Envía tu llave en el header X-API-Key en cada petición. Las llaves empiezan por gk_live_, se muestran una sola vez al crearlas y Güpp solo guarda su huella: si pierdes una, pide que la revoquen y te creen otra. Guárdala en un gestor de secretos, nunca en el código del cliente ni en una app móvil.

Verificar la llave
curl -s -H "X-API-Key: $GUPP_KEY" https://api-sandbox-3e2d10e3.up.railway.app/api/partner/v1/me

Cada llave tiene permisos (scopes). Pide solo los que uses:

PermisoPermite
catalog:readVer servicios y aliados cercanos (CDA, talleres)
quotes:writeCotizar servicios
orders:writeCrear y cancelar órdenes
orders:readConsultar órdenes y el costo de cancelarlas

Endpoints

RutaPermisoQué hace
GET/mecualquieraAliado, nombre y permisos de la llave, límite y webhook configurado
GET/servicescatalog:readServicios disponibles con tarifas
GET/places?lat&lng&kindcatalog:readAliados cercanos (CDA, talleres, lavaderos). radius_km opcional
POST/quotesquotes:writePrecio estimado, distancia, proveedores cerca y ETA
POST/ordersorders:writePide el servicio (201 con la orden)
GET/orders?status=active&external_ref=orders:readTus órdenes, paginadas (limit, offset)
GET/orders/{id}orders:readDetalle: estado, proveedor, ETA, PIN, precio e historial
GET/orders/{id}/cancel-previeworders:readCuánto costaría cancelar en este momento
POST/orders/{id}/cancelorders:writeCancela la orden; exige accept_fee: true si tiene costo
Cotizar
curl -s -X POST https://api-sandbox-3e2d10e3.up.railway.app/api/partner/v1/quotes \
  -H "X-API-Key: $GUPP_KEY" -H "Content-Type: application/json" \
  -d '{
    "service_code": "grua",
    "pickup_lat": 4.6533, "pickup_lng": -74.0836,
    "dropoff_lat": 4.7001, "dropoff_lng": -74.0502,
    "vehicle_kind": "carro"
  }'

Crear una orden

El cuerpo lleva los mismos campos de la cotización más los datos de la persona en sitio. El proveedor llamará a contact_phone, así que debe ser el celular de quien está con el vehículo.

CampoTipoDescripción
service_codetexto, obligatorioCódigo del servicio, p. ej. grua, paso_corriente, cambio_llanta
pickup_lat, pickup_lngnúmero, obligatorioDónde está el vehículo
dropoff_lat, dropoff_lngnúmeroDestino. Obligatorio en servicios con traslado (grúa)
pickup_address, dropoff_addresstextoDirecciones legibles para el proveedor
vehicle_kindmoto | carro | camioneta | pesadoDefine la tarifa y el tipo de grúa
vehicle_descriptiontextoPlaca, marca y color, p. ej. “ABC123 · Kia Picanto gris”
contact_name, contact_phonetexto, obligatorioPersona en sitio
external_reftextoTu referencia (siniestro, ticket). Única entre tus órdenes activas: sirve de idempotencia
problem, notestextoQué pasó e indicaciones para llegar
scheduled_atfecha ISOPara servicios con cita (lavado, revisión técnico-mecánica)
Pedir una grúa
curl -s -X POST https://api-sandbox-3e2d10e3.up.railway.app/api/partner/v1/orders \
  -H "X-API-Key: $GUPP_KEY" -H "Content-Type: application/json" \
  -d '{
    "service_code": "grua",
    "pickup_lat": 4.6533, "pickup_lng": -74.0836,
    "pickup_address": "Av. 68 con Cll 26",
    "dropoff_lat": 4.7001, "dropoff_lng": -74.0502,
    "dropoff_address": "Taller aliado Cll 100",
    "vehicle_kind": "carro",
    "vehicle_description": "ABC123 · Kia Picanto gris",
    "contact_name": "Ana Ruiz",
    "contact_phone": "3157778899",
    "external_ref": "SINIESTRO-2026-00123",
    "problem": "choque",
    "notes": "Vehículo en el carril derecho"
  }'
Si reintentas por un timeout, usa el mismo external_ref: si la orden ya existe y sigue activa, recibirás 409 en lugar de un duplicado. Consúltala con GET /orders?external_ref=….
Buscar por tu referencia
curl -s -H "X-API-Key: $GUPP_KEY" \
  "https://api-sandbox-3e2d10e3.up.railway.app/api/partner/v1/orders?status=active&external_ref=SINIESTRO-2026-00123"

Las órdenes de aliados se facturan a tu empresa (payment_method: "invoice") y puedes tener muchas activas a la vez. Cada orden trae tracking_url, un link público de seguimiento en vivo que puedes compartir con tu cliente.

Estados de la orden y PIN de inicio

EstadoSignifica
searchingBuscando el proveedor más cercano
assignedUn proveedor aceptó. Ya hay proveedor, ETA y start_pin
en_routeEl proveedor va en camino
arrivedEl proveedor llegó al punto de recogida
in_serviceServicio en curso (empezó tras validar el PIN)
completedFinalizado. final_price trae el valor definitivo
cancelledCancelada por ti, por soporte o por el proveedor
no_providerNo hubo proveedores disponibles a tiempo. Puedes volver a pedirla
scheduledReserva con cita creada; Güpp la confirma
confirmedReserva confirmada
PIN de inicio. Cuando la orden tiene proveedor, la respuesta y los webhooks incluyen start_pin. Hazlo llegar a tu cliente (SMS, WhatsApp o tu app): el proveedor se lo pedirá para empezar el servicio. Así tu cliente confirma que es el proveedor correcto antes de entregar el vehículo.

Cancelaciones

Cancelar es gratis mientras buscamos proveedor y durante los 2 minutos siguientes a la asignación. Después se cobra una compensación al proveedor por el desplazamiento: 20 % del valor estimado si va en camino, o 35 % si ya llegó, con un mínimo de $8.000 y un máximo de $30.000. Un servicio en curso, finalizado o ya cancelado no se puede cancelar (409). Consulta siempre el costo antes:

Cancelar
# 1. ¿Cuánto cuesta cancelar ahora?
curl -s -H "X-API-Key: $GUPP_KEY" https://api-sandbox-3e2d10e3.up.railway.app/api/partner/v1/orders/$ORDER_ID/cancel-preview
# → {"fee": 0, "reason": "Cancelación sin costo"}

# 2. Cancelar. Si fee > 0 hay que confirmar con "accept_fee": true (si no, responde 409)
curl -s -X POST https://api-sandbox-3e2d10e3.up.railway.app/api/partner/v1/orders/$ORDER_ID/cancel \
  -H "X-API-Key: $GUPP_KEY" -H "Content-Type: application/json" \
  -d '{"reason": "El cliente consiguió ayuda por su cuenta", "accept_fee": true}'

Errores y límites

Los errores responden JSON con un campo detail en español. En validaciones (422), detail es una lista con el campo y el problema.

CódigoCuándoQué hacer
401Falta X-API-Key, o la llave es inválida, está revocada o vencióRevisa la llave; pide una nueva si la revocaron
403La llave no tiene el permiso, o tu cuenta de aliado está desactivadaPide el permiso o contacta a Güpp
404La orden no existe o no es tuyaVerifica el id
409external_ref repetido en una orden activa, o la orden ya no admite el cambioConsulta el estado actual antes de reintentar
422Cuerpo o parámetros inválidosCorrige los campos indicados en detail
429Superaste el límite de peticiones por minutoEspera los segundos del header Retry-After y reintenta

Cada llave tiene un límite de peticiones por minuto (120 por defecto, ajustable hasta 5.000). En vez de consultar una orden en bucle, usa los webhooks.

Webhooks

Güpp hace POST a la URL https que configuraste cada vez que se crea o cambia una de tus órdenes. El cuerpo es JSON con el evento, la fecha y la orden completa en data (el mismo formato de GET /orders/{id}).

Eventos y entregas

EventoCuándo
order.createdSe creó una orden tuya
order.updatedCambió el estado, el proveedor, el precio o el PIN de una orden
pingPrueba enviada desde la consola de Güpp
Ejemplo de entrega
POST /webhooks/gupp HTTP/1.1
Content-Type: application/json
User-Agent: Gupp-Webhooks/1.0
X-Gupp-Event: order.updated
X-Gupp-Delivery: 5b0c3c1e-8f0a-4d1e-9a51-0b7f2d6a9e44
X-Gupp-Signature: t=1794449005,v1=6f1c0a…e93b

{
  "event": "order.updated",
  "created_at": "2026-11-11T21:27:44.512Z",
  "data": {
    "id": "d0df529f-38be-4b59-87a4-8847bffc7b4c",
    "code": "GP-Q2YRSD",
    "status": "en_route",
    "external_ref": "SINIESTRO-2026-00123",
    "start_pin": "4821",
    "eta_minutes": 7,
    "provider": { "display_name": "Rescate Vial Norte", "vehicle_plate": "TTX902", … },
    …
  }
}
  • Responde con un código 2xx en menos de 10 segundos. Procesa en segundo plano si tu lógica tarda.
  • Si no respondes 2xx, se reintenta: 3 intentos en total (inmediato, a los 5 s y a los 30 s).
  • Usa X-Gupp-Delivery para descartar duplicados, y el campo status de la orden (no el orden de llegada) como fuente de verdad.
  • Todas las entregas, con su respuesta, quedan registradas en la consola de Güpp para soporte.

Verificar la firma

Cada entrega trae X-Gupp-Signature: t=<unix>,v1=<hex>, donde v1 es HMAC_SHA256(webhook_secret, `${t}.${cuerpo_crudo}`) en hexadecimal. Verifica sobre el cuerpo crudo (antes de parsear el JSON), compara en tiempo constante y rechaza firmas con más de 5 minutos para evitar repeticiones. El secreto te lo entrega Güpp y se puede rotar.

Node.js (Express)
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.GUPP_WEBHOOK_SECRET;
const TOLERANCE_S = 5 * 60;

function verifyGupp(header, rawBody) {
  const parts = Object.fromEntries(
    (header ?? "").split(",").map((p) => p.split("=", 2)),
  );
  const t = Number(parts.t);
  if (!t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_S) return false;

  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${t}.`)
    .update(rawBody) // Buffer con el cuerpo tal cual llegó
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();
// Importante: el cuerpo crudo, no el JSON ya parseado.
app.post("/webhooks/gupp", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyGupp(req.get("X-Gupp-Signature"), req.body)) {
    return res.status(400).send("firma inválida");
  }
  const event = JSON.parse(req.body.toString("utf8"));
  // Responde rápido y procesa en segundo plano (idempotente por X-Gupp-Delivery).
  res.sendStatus(204);
  queue.push(event);
});
Python (FastAPI)
import hashlib
import hmac
import os
import time

from fastapi import FastAPI, Header, HTTPException, Request

SECRET = os.environ["GUPP_WEBHOOK_SECRET"].encode()
TOLERANCE_S = 5 * 60
app = FastAPI()


def verify_gupp(header: str | None, raw_body: bytes) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in (header or "").split(","))
        t = int(parts["t"])
        received = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > TOLERANCE_S:
        return False
    expected = hmac.new(SECRET, f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)


@app.post("/webhooks/gupp", status_code=204)
async def gupp_webhook(request: Request, x_gupp_signature: str | None = Header(None)):
    raw = await request.body()  # cuerpo crudo
    if not verify_gupp(x_gupp_signature, raw):
        raise HTTPException(400, "firma inválida")
    event = await request.json()
    # Encola y responde en menos de 10 s; deduplica por X-Gupp-Delivery.
    enqueue(event)

Servidor MCP

Güpp expone un servidor Model Context Protocol para que un agente de IA cotice y pida servicios, maneje el parqueo o consulte multas en nombre de un usuario de Güpp.

DatoValor
URLhttps://api-sandbox-3e2d10e3.up.railway.app/mcp
TransporteStreamable HTTP
AutorizaciónOAuth 2.1: registro dinámico de clientes (RFC 7591) + código de autorización con PKCE S256
Scopegupp
Descubrimiento/.well-known/oauth-protected-resource/mcp y /.well-known/oauth-authorization-server

OAuth y consentimiento

  1. El cliente MCP descubre el servidor de autorización y se registra solo en /register.
  2. Abre /authorize con PKCE. El usuario llega a la pantalla de consentimiento de Güpp, escribe su celular y el código de verificación (OTP).
  3. Ve qué app pide acceso y qué podrá hacer, y toca Autorizar.
  4. El cliente cambia el código en /token: recibe un access token de 1 hora y un refresh token de 30 días (rotativo). Se pueden revocar en /revoke.

El agente actúa como el usuario: los servicios se cobran como en la app (billetera, tarjeta o efectivo). Güpp puede bloquear una app, lo que revoca todos sus tokens, o retirar el acceso de un usuario puntual.

Herramientas

HerramientaQué hace
list_servicesCatálogo de servicios con tarifas
my_vehiclesVehículos del usuario y vencimientos de documentos
quote_serviceCotiza un servicio entre dos puntos
request_servicePide el servicio (grúa, asistencia, lavado…)
my_ordersÓrdenes del usuario (activas por defecto)
get_orderEstado, proveedor, ETA y PIN de una orden
cancel_orderCancela. Si hay tarifa, primero la informa y exige accept_fee=true
find_parkingZonas de parqueo en vía cercanas
start_parkingInicia un parqueo por minutos
my_parkingParqueos activos y tiempo restante
stop_parkingTermina el parqueo y reembolsa los minutos no usados
wallet_balanceSaldo de la billetera Güpp
my_policiesPólizas SOAT y todo riesgo
check_finesConsulta multas por cédula o placa

Conectar en Claude

  1. Abre Configuración → Conectores.
  2. Toca “Agregar conector personalizado”.
  3. Pega https://api-sandbox-3e2d10e3.up.railway.app/mcp y guarda.
  4. Inicia sesión con tu celular y el código de verificación, revisa los permisos y toca Autorizar.
  5. Pídele a Claude, por ejemplo: “Cotízame una grúa desde la Calle 26 con 68 hasta mi taller”.
gupp

Grúa, asistencia en vía, mantenimiento, seguros, parqueo y trámites para tu vehículo. Hecho en Colombia.

Güpp

ServiciosCómo funcionaSé proveedor GüppPreguntas frecuentesDesarrolladores

Legal

Términos y condicionesPolítica de privacidad (Ley 1581 de 2012)soporte@gupp.co

© 2026 Güpp. Los servicios en sitio los prestan proveedores independientes verificados por Güpp.