Introduction

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.

Authentication

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

Registers a new user associated with your partner account.

Request Body · Persona Natural

Additional Fields · Persona Juridica

Response 201

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

Creates UPME certification tramite with vehicle data. Returns amount to pay.

Request Body

Response 201

{
  "case_id": "uuid-del-tramite",
  "amount_cop": 1131566,
  "amount_cents": 113156600,
  "breakdown": {
    "costo_upme": 350906,
    "honorarios": 599990,
    "iva": 180670,
    "discount": 0,
    "total": 1131566
  }
}

Uploads required documents. Each document is processed automatically with AI.

Form Fields

Document Types

Response 200

{
  "case_id": "uuid",
  "type": "factura",
  "ocr_status": "pending"
}

Returns the current status and details of a tramite.

Response 200

{
  "case_id": "uuid",
  "status": "IN_PROGRESS",
  "step": 5,
  "progress_pct": 44,
  "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": 113156600,
    "reference": "CERTIVEH-xxx-xxx"
  }
}

Tramite Statuses

Initializes a payment session and returns Wompi integration data.

Response 200

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

Wompi Widget Integration

Use the response values to render the Wompi checkout button:

<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>

Webhooks

CertiVeh sends notifications to your webhook URL when a tramite status changes. Provide your webhook URL when requesting your API key.

Payload

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

Errors

All error responses follow a consistent format:

{
  "error": "Description"
}

HTTP Status Codes

• 400 Invalid request · missing field or wrong format
• 401 Invalid or inactive API key
• 403 Unauthorized · resource doesn't belong to your partner account
• 404 Resource not found
• 500 Internal server error

Integration Flow

Typical end-to-end integration in 6 steps:

1. Create user POST /users · Register the end-user with personal data.
2. Create tramite with vehicle data POST /tramites · Submit vehicle details, receive pricing breakdown.
3. Upload documents POST /tramites/:id/documents · Upload cedula, tarjeta de propiedad, and factura.
4. Initialize payment POST /tramites/:id/payment · Get Wompi widget parameters and render checkout.
5. Poll status GET /tramites/:id · Check tramite progress periodically.
6. Receive webhooks Your endpoint receives status updates automatically as the tramite progresses.

Contact

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

contacto@certiveh.co