NUBEX CERTIFICADOS · v1.0
https://nubexcertificados.lovable.app/api/public/v1Requiere publicación de esta versión para usar la dirección de producción. Camerfirma sigue simulado: no se emiten certificados automáticamente; un administrador carga el P12/PFX y registra su estado y contraseña.
Authorization: Bearer <CLAVE_API>
X-Software-House-Code: <CODIGO_EMPRESA>POST /api/public/v1/solicitudes
Enviar multipart/form-data con los ocho campos y los cuatro archivos. No configurar Content-Type manualmente: el cliente genera el separador. Máximo 25 MB total y 20 MB por archivo, formato PDF/JPG/PNG. No se aceptan URLs remotas de documentos.
curl -X POST 'https://nubexcertificados.lovable.app/api/public/v1/solicitudes' \
-H 'Authorization: Bearer <CLAVE_API>' \
-H 'X-Software-House-Code: <CODIGO_EMPRESA>' \
-F 'reference=ERP-2026-00891' \
-F 'cert_type=representacion_legal' \
-F 'holder_name=Carlos Alberto Gómez Restrepo' \
-F 'holder_document=79845123' \
-F 'holder_email=titular@example.com' \
-F 'holder_phone=+573105551234' \
-F 'company_nit=900123456-1' \
-F 'company_name=Empresa de ejemplo S.A.S.' \
-F 'camara_comercio=@camara.pdf' \
-F 'rut=@rut.pdf' \
-F 'cedula_frontal=@frente.jpg' \
-F 'cedula_trasera=@reverso.jpg'Ejemplos ficticios. cert_type admite representacion_legal, persona_natural o persona_juridica. La Cámara debe haberse expedido máximo 30 días antes de la solicitud; los representantes deben coincidir entre Cámara, RUT y cédula, con ambos lados legibles. Recibir 201 confirma recepción, no aprobación documental.
{
"id": "c8f1e2a0-4b5c-4d3e-9f0a-1a2b3c4d5e6f",
"reference": "ERP-2026-00891",
"cert_type": "representacion_legal",
"holder_name": "Carlos Alberto Gómez Restrepo",
"holder_document": "79845123",
"holder_email": "titular@example.com",
"holder_phone": "+573105551234",
"company_nit": "900123456-1",
"company_name": "Empresa de ejemplo S.A.S.",
"status": "recibida",
"provider": "Camerfirma",
"provider_connection": "simulated"
}La referencia es única dentro de la empresa. Si recibes 409 o pierdes la respuesta, consulta GET /solicitudes?reference=ERP-2026-00891 antes de reintentar.
GET /api/public/v1/solicitudes?limit=20&offset=0
Lista paginada de solicitudes. reference es un filtro opcional; limit admite 1 a 100 y offset 0 a 100000.
GET /api/public/v1/solicitudes/{id}
Estado de la solicitud y certificate.available. download_url es una ruta relativa protegida; envía las mismas cabeceras al descargar.
GET /api/public/v1/solicitudes/{id}/documentos
Nombre y tamaño de los documentos recibidos, separados en camara_comercio, rut, cedula_frente y cedula_reverso.
GET /api/public/v1/solicitudes/{id}/certificado
Binario P12/PFX con Content-Type application/x-pkcs12. Solo emitida o entregada y archivo presente. Descargar no marca la solicitud como entregada.
GET /api/public/v1/solicitudes/{id}/clave
Contraseña del certificado: { id, password }. Requiere permiso de contraseña, estado emitida/entregada y P12/PFX guardado. Cache-Control: no-store.
curl 'https://nubexcertificados.lovable.app/api/public/v1/solicitudes/<ID>/certificado' \
-H 'Authorization: Bearer <CLAVE_API>' \
-H 'X-Software-House-Code: <CODIGO_EMPRESA>' \
--fail --output certificado.p121 · POST /api/public/v1/solicitudes
Solicitar certificado por primera vez (ver Registrar solicitud).
2 · POST /api/public/v1/solicitudes/{id}/renovacion
Renovar un certificado emitido o entregado. multipart/form-data con reference nueva y camara_comercio actualizada (máximo 30 días). El RUT y la cédula se reutilizan de la solicitud original; los datos del titular se copian. Responde 201 con operation: renovacion y parent_request_id.
curl -X POST 'https://nubexcertificados.lovable.app/api/public/v1/solicitudes/<ID>/renovacion' \
-H 'Authorization: Bearer <CLAVE_API>' \
-H 'X-Software-House-Code: <CODIGO_EMPRESA>' \
-F 'reference=ERP-2026-01200' \
-F 'camara_comercio=@camara.pdf'3 · POST /api/public/v1/solicitudes/{id}/revocatoria
Solicitar revocatoria de un certificado emitido o entregado. JSON con reference nueva y reason (10 a 500 caracteres). Un administrador la revisa: si la aprueba, la revocatoria y el certificado original pasan a revocada y el certificado deja de descargarse; si no, la revocatoria queda rechazada. Solo una revocatoria abierta por certificado.
curl -X POST 'https://nubexcertificados.lovable.app/api/public/v1/solicitudes/<ID>/revocatoria' \
-H 'Authorization: Bearer <CLAVE_API>' \
-H 'X-Software-House-Code: <CODIGO_EMPRESA>' \
-H 'Content-Type: application/json' \
-d '{"reference":"REV-2026-0001","reason":"Cambio de representante legal"}'4 · GET /api/public/v1/certificados/ultimo?holder_document=79845123
Copia del último certificado vigente (emitido o entregado, no revocado) del titular, incluidas renovaciones. company_nit es un filtro opcional. Devuelve el binario P12/PFX y la cabecera X-Request-Id con la solicitud de origen; la contraseña se consulta en /solicitudes/{id}/clave.
5 · GET /api/public/v1/estado-cuenta?desde=2026-01-01&hasta=2026-12-31
Resumen de cantidades de la empresa: total, por operación, por estado, certificados vigentes y pendientes. Fechas opcionales AAAA-MM-DD. No incluye valores monetarios.
{
"desde": "2026-01-01",
"hasta": "2026-12-31",
"total": 42,
"by_operation": {
"emision": 35,
"renovacion": 5,
"revocatoria": 2
},
"by_status": {
"recibida": 3,
"enviada": 1,
"en_validacion": 2,
"emitida": 4,
"entregada": 28,
"rechazada": 2,
"error": 0,
"revocada": 2
},
"active_certificates": 31,
"pending": 6
}6 · GET /api/public/v1/solicitudes/{id}
Estado actual de cualquier solicitud (emisión, renovación o revocatoria): status, operation, parent_request_id, updated_at y disponibilidad del certificado. Si solo tienes tu referencia, usa GET /api/public/v1/solicitudes?reference=ERP-2026-00891.
{
"id": "<ID>",
"reference": "ERP-2026-00891",
"status": "en_validacion",
"operation": "emision",
"parent_request_id": null,
"updated_at": "2026-11-10T22:00:00Z",
"certificate": {
"available": false,
"download_url": null
}
}recibida · enviada · en_validacion · emitida · entregada · rechazada · error · revocada
Los estados de emisión y entrega se registran administrativamente mientras la conexión con Camerfirma sea simulada.
El administrador registra la dirección HTTPS de cada empresa en Integración API. Al cambiar el estado de una solicitud creada por API, se envía un POST firmado. No envíes callback_url en el formulario. Solo se incluyen el ID, referencia y estado: nunca documentos ni contraseñas.
{
"event_id": "<ID_EVENTO>",
"event": "solicitud.emitida",
"timestamp": "2026-11-10T22:00:00Z",
"data": {
"solicitud_id": "<ID_SOLICITUD>",
"reference": "ERP-2026-00891",
"status": "emitida"
}
}X-Nubex-Signature contiene t=UNIX,v1=HEX. Verifica HMAC-SHA256 de «t.cuerpo_original» usando la clave activa más reciente de la empresa. X-Nubex-Key-Prefix identifica esa clave. Rechaza firmas incorrectas o tiempos con más de cinco minutos de diferencia; deduplica event_id y responde 2xx. Hay hasta cinco intentos inmediatos por evento; los fallidos se reintentan manualmente desde Integración API. Si cambia la clave, actualiza el receptor. Consulta GET como respaldo si no llega una notificación.
import hashlib, hmac, time
# raw_body: bytes recibidos sin modificar.
parts = dict(item.split("=", 1) for item in signature_header.split(","))
timestamp = int(parts["t"])
if abs(time.time() - timestamp) > 300:
raise ValueError("Notificación vencida")
expected = hmac.new(api_key.encode(),
parts["t"].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, parts["v1"]):
raise ValueError("Firma inválida")
# Deduplicar event_id antes de procesar; responder HTTP 2xx.{ "error": { "code": "unauthorized", "message": "Credenciales inválidas." } }