Introduccion

CertiVeh Partner API · Integra CertiVeh en tu aplicacion para que tus usuarios obtengan su certificado UPME sin salir de tu plataforma.

Esta API REST permite crear usuarios, iniciar tramites de certificacion UPME, subir documentos, procesar pagos y consultar el estado de cada tramite de forma programatica.

Autenticacion

Todas las solicitudes requieren el header X-API-Key con tu clave de partner.

X-API-Key: pk_live_xxxxxxxxxxxxx

Base URL

https://ykolfdgnlaxahtbuurgj.supabase.co/functions/v1/partner-api

Registra un nuevo usuario asociado a tu cuenta de partner.

Cuerpo de la solicitud · Persona Natural

Campos adicionales · Persona Juridica

Ejemplo de solicitud

curl -X POST \
  https://ykolfdgnlaxahtbuurgj.supabase.co/functions/v1/partner-api/users \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@ejemplo.com",
    "phone": "+573001234567",
    "person_type": "natural",
    "first_names": "JUAN CARLOS",
    "last_names": "GARCIA LOPEZ",
    "cedula_number": "1020304050",
    "date_of_birth": "1990-05-15",
    "expedition_date": "2010-03-20",
    "ciiu_code": "4511",
    "department": "CUNDINAMARCA",
    "municipality": "BOGOTA D.C.",
    "address": "Calle 100 #15-20 Apto 501"
  }'

Respuesta 201

{
  "user_id": "uuid-del-usuario",
  "status": "created"
}

Crea un tramite de certificacion UPME con los datos del vehiculo. Retorna el desglose de costos.

Cuerpo de la solicitud

Ejemplo de solicitud

curl -X POST \
  https://ykolfdgnlaxahtbuurgj.supabase.co/functions/v1/partner-api/tramites \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "uuid-del-usuario",
    "plate": "QMX060",
    "vin": "KNACP81EGT5328961",
    "brand": "KIA",
    "line": "NIRO DESIRE",
    "year": 2025,
    "propulsion_type": "Hibrido",
    "owner_name": "JUAN CARLOS GARCIA LOPEZ",
    "owner_id": "1020304050",
    "purchase_value_cop": 116805309,
    "purchase_date": "2025-08-10",
    "dealer_name": "KIA MOTORS BOGOTA",
    "invoice_number": "FV-2025-001234",
    "buyer_name": "JUAN CARLOS GARCIA LOPEZ"
  }'

Respuesta 201

{
  "case_id": "uuid-del-tramite",
  "amount_cop": 1415800,
  "amount_cents": 141580000,
  "breakdown": {
    "costo_upme": 701812,
    "honorarios": 599990,
    "iva": 113998,
    "discount": 0,
    "total": 1415800
  }
}

Sube documentos requeridos. Cada documento se procesa automaticamente con IA.

Campos del formulario

Tipos de documento

Ejemplo de solicitud

curl -X POST \
  https://ykolfdgnlaxahtbuurgj.supabase.co/functions/v1/partner-api/tramites/uuid-del-tramite/documents \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxx" \
  -F "type=factura" \
  -F "file=@/path/to/factura.pdf"

Respuesta 200

// Documentos del vehiculo (factura, tarjeta-propiedad-*)
{
  "case_id": "uuid",
  "type": "factura",
  "ocr_status": "pending"
}

// Documentos personales (cedula-frente, cedula-reverso, rut)
{
  "document_id": "uuid",
  "type": "cedula-frente",
  "ocr_status": "pending"
}

Retorna el estado actual y detalles de un tramite.

Ejemplo de solicitud

curl -X GET \
  https://ykolfdgnlaxahtbuurgj.supabase.co/functions/v1/partner-api/tramites/uuid-del-tramite \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxx"

Respuesta 200

{
  "case_id": "uuid",
  "status": "IN_PROGRESS",
  "step": 5,          // 1-7
  "progress_pct": 67,   // 0-100, basado en 7 pasos
  "paid_at": "2026-05-20T...",
  "created_at": "2026-05-15T...",
  "updated_at": "2026-05-20T...",
  "vehicle": {
    "brand": "KIA",
    "line": "NIRO DESIRE",
    "year": 2025,
    "plate": "QMX060",
    "vin": "KNACP81EGT5328961",
    "propulsion_type": "Hibrido",
    "purchase_value_cop": 116805309
  },
  "documents": [
    { "type": "factura", "ocr_status": "done" },
    { "type": "tarjeta-propiedad-frente", "ocr_status": "done" }
  ],
  "payment": {
    "status": "APPROVED",
    "amount_cents": 141580000,
    "reference": "CERTIVEH-xxx-xxx",
    "created_at": "2026-05-20T14:00:00Z"
  }
}

Pasos del pipeline (1–7)

Estados del tramite

Inicializa una sesion de pago y retorna los datos de integracion con Wompi.

Ejemplo de solicitud

curl -X POST \
  https://ykolfdgnlaxahtbuurgj.supabase.co/functions/v1/partner-api/tramites/uuid-del-tramite/payment \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxx"

Respuesta 200

{
  "reference": "CERTIVEH-xxx-xxx",
  "amount_cents": 141580000,
  "amount_cop": 1415800,
  "currency": "COP",
  "public_key": "pub_prod_xxx",
  "signature": "sha256-hash",
  "redirect_url": "https://portal.certiveh.co/tramite/confirmacion?ref=xxx"
}

Integracion Widget Wompi

Usa los valores de la respuesta para renderizar el boton de pago de Wompi:

<script src="https://checkout.wompi.co/widget.js"
  data-render="button"
  data-public-key="{'{'+'public_key}'}"
  data-currency="{'{'+'currency}'}"
  data-amount-in-cents="{'{'+'amount_cents}'}"
  data-reference="{'{'+'reference}'}"
  data-redirect-url="{'{'+'redirect_url}'}"
  data-signature:integrity="{'{'+'signature}'}">
</script>

Simula la aprobacion de un pago sin realizar un cobro real. Solo disponible en modo sandbox.

Ejemplo de solicitud

curl -X POST \
  https://ykolfdgnlaxahtbuurgj.supabase.co/functions/v1/partner-api/tramites/uuid-del-tramite/simulate-payment \
  -H "X-API-Key: sk_sandbox_xxxxxxxxxxxxx"

Respuesta 200

{
  "case_id": "uuid-del-tramite",
  "payment_id": "uuid-del-pago",
  "status": "APPROVED",
  "case_status": "DOCUMENT_REVIEW",
  "sandbox": true,
  "message": "Payment simulated successfully. No real charge was made."
}

Webhooks

CertiVeh envia notificaciones HTTP POST a tu webhook URL cuando el estado de un tramite cambia. Proporciona tu webhook URL al solicitar tu API key.

Payload

{
  "event": "tramite.status_changed",
  "case_id": "uuid",
  "status": "DOCUMENT_REVIEW",
  "timestamp": "2026-05-20T15:30:00Z"
}

Transiciones de estado tipicas

Errores

Todas las respuestas de error siguen un formato consistente:

{
  "error": "Description"
}

Codigos HTTP

• 400 Solicitud invalida · campo faltante o formato incorrecto
• 401 API key invalida o inactiva
• 403 No autorizado · el recurso no pertenece a tu cuenta de partner
• 404 Recurso no encontrado
• 429 Demasiadas solicitudes · limite de tasa excedido
• 500 Error interno del servidor

Limite de tasa

Todos los endpoints estan limitados a 100 solicitudes por minuto por API key.

Cuando se excede el limite, la API retorna 429 Too Many Requests. Espera a que la ventana se reinicie antes de reintentar.

Seguridad

Todas las solicitudes a la API se registran automaticamente incluyendo direccion IP, user-agent y codigo de respuesta para auditoria y seguridad.

Descuentos de partner

Los precios retornados por POST /tramites y POST /tramites/:id/payment aplican automaticamente cualquier descuento configurado para tu cuenta de partner. El campo breakdown.discount refleja el monto del descuento aplicado. No se necesitan parametros adicionales.

Ambiente de pruebas (Sandbox)

CertiVeh provee un ambiente de sandbox completo para que puedas desarrollar y probar tu integracion sin generar cobros reales, facturas, ni emails.

Como funciona

Flujo tipico de prueba

1. Usa tu API key sandbox X-API-Key: sk_sandbox_xxx · Todos los endpoints funcionan igual, pero la data se marca como sandbox.
2. Crea usuario y tramite POST /users y POST /tramites · Funcionan identico a produccion. Las respuestas incluyen "sandbox": true.
3. Sube documentos POST /tramites/:id/documents · El OCR se ejecuta normalmente para que puedas validar la extraccion de datos.
4. Simula el pago POST /tramites/:id/payment para crear el pago, luego POST /tramites/:id/simulate-payment para aprobar instantaneamente sin Wompi.
5. Recibe el webhook Tu endpoint recibe tramite.payment_confirmed con sandbox: true. Valida tu implementacion.

Flujo de integracion

Integracion tipica de punta a punta en 6 pasos:

1. Crear usuario POST /users · Registra al usuario con sus datos personales. Si el email ya existe, retorna el user_id existente.
2. Crear tramite con datos del vehiculo POST /tramites · Envia los datos del vehiculo y recibe el desglose de costos. El tramite se crea en estado DRAFT.
3. Subir documentos POST /tramites/:id/documents · Sube cedula (frente y reverso), tarjeta de propiedad (frente y reverso) y factura. Cada documento se procesa con OCR automaticamente. El orden no importa.
4. Iniciar pago POST /tramites/:id/payment · Obtiene los parametros para renderizar el widget de Wompi. Cuando el usuario paga, el tramite cambia automaticamente a DOCUMENT_REVIEW.
5. Consultar estado GET /tramites/:id · Consulta el progreso del tramite periodicamente. Usa status para el estado general y step (1-7) para el progreso detallado.
6. Recibir webhooks Tu endpoint recibe notificaciones automaticas cada vez que el estado del tramite cambia (pago recibido, en proceso, certificado emitido, etc.).

Contacto

Para solicitar tu API key o soporte tecnico, escribe a:

contacto@certiveh.co