NUBEX CERTIFICADOS · v1.0

Documentación API

Conexión

https://nubexcertificados.lovable.app/api/public/v1

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

Autenticación y seguridad

Authorization: Bearer <CLAVE_API>
X-Software-House-Code: <CODIGO_EMPRESA>
  • El administrador crea una credencial por empresa en Integración API. Se muestra una sola vez y puede revocarse.
  • Guardar la clave en el servidor del software; nunca en aplicaciones de navegador, repositorios o registros.
  • Cada empresa solo consulta sus solicitudes. Una solicitud ajena devuelve 404. Empresas inactivas y claves revocadas reciben 401.
  • Máximo 60 peticiones por minuto por clave. HTTP 429 incluye Retry-After: 60.
  • La contraseña requiere autorización explícita al crear la credencial. No se incluye en listados ni en notificaciones.

Registrar solicitud

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.

Respuesta 201

{
  "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.

Consulta y descarga

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

Operaciones del certificado

1 · 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
  }
}

Estados

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.

Notificaciones webhook

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.

Errores

{ "error": { "code": "unauthorized", "message": "Credenciales inválidas." } }
401
Clave incorrecta, revocada o empresa inactiva.
403
La credencial no permite consultar contraseñas.
404
Solicitud ajena/inexistente o certificado/contraseña no guardados.
409
Referencia duplicada o certificado aún no emitido.
413 / 415 / 422
Tamaño, formato, campos o documentos inválidos.
429 / 503
Límite alcanzado o servicio temporalmente no disponible.