Saltar al contenido principal

API 1.20.0 - Tipo de emisión por solicitud (biométrica o documental)

· 8 min de lectura

Aquí resumimos lo que cambió para los integradores desde la entrada 1.19.5. La novedad principal es el tipo de emisión por solicitud (issuance_flow): biométrica o documental, con precios, compras y cupos separados por tipo. Incluye también las versiones 1.19.6 a 1.19.10. Las rutas siguen bajo el prefijo /api/v1.

Todo es aditivo: si tu integración no cambia nada, sigue creando solicitudes, comprando y consultando el saldo como hasta ahora (ver «Compatibilidad»). Revisa sobre todo los puntos de abajo.

Cambios que requieren acción
  • issuance_provider puede valer dual y ya no llega null: en el login, en GET /company y en GET /quota/status vale viafirma, mail o dual. dual significa que tu empresa puede elegir el tipo de emisión en cada solicitud. Si en el futuro llega un valor distinto de viafirma, mail y dual, no lo trates como mail: no crees solicitudes y contacta a soporte.
  • Decide por la solicitud, no por la empresa: cada solicitud trae issuance_flow (BIOMETRIC o DOCUMENTARY). Úsalo para saber si la emisión arranca sola, si hay verificación de identidad o si debes llamar a /issue. Una empresa dual tiene solicitudes de los dos tipos.
  • El cupo es por tipo de emisión: una solicitud solo consume certificados de su mismo tipo. Sin cupo, el 402 trae ahora error_code = QUOTA_EXHAUSTED, un message que nombra el tipo (No tiene certificados disponibles de tipo Documental (sin biometría) para vigencia de 1 año(s)…), issuance_flow, vigencia y available_in_other_flows. Si comparabas el texto del mensaje, guíate por error_code.
  • postpaid de GET /quota/status ahora suma todos los cupos pospago vigentes del tipo, y expires_at es el vencimiento más próximo. Antes mostraba solo el cupo pospago más reciente, así que el número puede subir.
  • POST /orders sin rango de precios responde 422 con error_code = PRICING_TIER_NOT_FOUND. Antes respondía 500.
  • Empresas viafirma cuando la emisión biométrica no está disponible: POST /certificate-request responde 400 con error_code = ISSUANCE_FLOW_UNAVAILABLE y la solicitud no se crea ni consume cupo. Antes la solicitud se creaba y fallaba después, al emitir.

Cambios de comportamiento​

Tipo de emisión de cada solicitud​

issuance_flowQué significaCómo se tramita
BIOMETRICBiométrica (con verificación de identidad)Exige legal_rep_email, legal_rep_first_name y legal_rep_last_name; los adjuntos son opcionales. Nace en PROCESSING y la emisión arranca sola
DOCUMENTARYDocumental (sin biometría)Exige 2 a 3 adjuntos en Base64. Nace en DRAFT y se envía a emisión con POST /certificate-request/{id}/issue

Los tipos que puede usar tu empresa dependen de issuance_provider:

issuance_providerTipos permitidosSin issuance_flow en la petición
viafirmaBIOMETRICBIOMETRIC (como antes)
mailDOCUMENTARYDOCUMENTARY (como antes)
dualBIOMETRIC y DOCUMENTARYDOCUMENTARY. Para una emisión biométrica envía "issuance_flow": "BIOMETRIC"

Desaparece el caso issuance_provider = null y sus reglas especiales de validación.

  • POST /certificate-request: nuevo campo opcional issuance_flow. Las reglas de validación dependen del tipo elegido, no de la empresa. La respuesta trae dataRecords.issuance_flow. Nuevos errores 400 con error_code (sin success, como los demás 400 de este endpoint) y el motivo en message:

    • INVALID_ISSUANCE_FLOW: el valor no es BIOMETRIC ni DOCUMENTARY.
    • ISSUANCE_FLOW_NOT_ALLOWED: tu empresa no tiene habilitado ese tipo.
    • ISSUANCE_FLOW_UNAVAILABLE: la emisión biométrica no está disponible en este momento.

    Si tu empresa es dual y no envías issuance_flow ni adjuntos, errors.attachments añade La empresa admite ambos flujos; envíe issuance_flow=BIOMETRIC para emisión biométrica.

  • PUT /certificate-request/{id}: el tipo no se puede cambiar. No envíes issuance_flow; si llega uno distinto del que tiene la solicitud, responde 400 ISSUANCE_FLOW_IMMUTABLE. Para usar otro tipo, elimina la solicitud (solo en DRAFT o REJECTED) y crea otra.

  • Listados y detalle: GET /certificate-request y GET /certificate-request/{id} traen issuance_flow en cada solicitud. Las solicitudes anteriores ya traen su tipo. El listado acepta el filtro ?issuance_flow=BIOMETRIC|DOCUMENTARY; otro valor responde 422 INVALID_ISSUANCE_FLOW.

  • POST /certificate-request/{id}/issue: el proveedor lo decide el tipo de la solicitud. Un provider en el cuerpo que no corresponde a ese tipo responde 422 ISSUANCE_PROVIDER_MISMATCH: no envíes provider. Si envías request_status o user_of_change en el cuerpo de /issue sobre una solicitud BIOMETRIC, responde 409 ISSUANCE_FLOW_ACTION_NOT_ALLOWED: no envíes esos campos.

  • Descargas, verificación de identidad, rechazo, revocación y renovación no cambian. La renovación sigue disponible solo para certificados biométricos.

Detalle en Solicitudes de certificado y Emisión de certificados.

Precios, compras y cupos por tipo de emisión​

  • GET /pricing: nuevo parámetro opcional ?issuance_flow=; sin él, el tipo por defecto de tu empresa. Cada rango y la cotización (quantity + vigencia) traen issuance_flow, y la cotización añade tier_name. Un tipo no válido o no habilitado responde 422 (INVALID_ISSUANCE_FLOW o ISSUANCE_FLOW_NOT_ALLOWED); sin rango para la cantidad, 422 PRICING_TIER_NOT_FOUND. En esta versión los dos tipos se cotizan con las mismas tarifas; desde la 1.21.0 cada tipo tiene las suyas.
  • POST /orders: nuevo campo opcional issuance_flow (sin él, el tipo por defecto). Los certificados comprados solo se usan en solicitudes de ese tipo. La respuesta, dentro de data, añade issuance_flow y tier. GET /orders y GET /orders/{uuid} añaden issuance_flow y pricing_tier_id; una orden antigua puede traer issuance_flow = null.
  • GET /quota/status: nuevos issuance_provider, has_quota_any_flow y by_flow, con un bloque por tipo (BIOMETRIC / DOCUMENTARY) que trae selectable, postpaid, prepaid_items_available, prepaid_1_year, prepaid_2_year, available_1_year, available_2_year y has_quota. available_N_year es pospago más prepago para esa vigencia. Un tipo con saldo que tu empresa ya no puede usar llega con selectable: false. Las claves de primer nivel describen el tipo por defecto de tu empresa (con dual, DOCUMENTARY).
  • Consumo de cupo: una solicitud usa primero el pospago vigente de su tipo (el que vence antes) y, si no hay, un certificado prepago de su tipo y su vigencia. Si eliminas la solicitud (en DRAFT o REJECTED), la rechazas con /issuance/reject o se cancela porque venció la verificación de identidad, el certificado vuelve al mismo saldo del que salió. Pasarla a CANCELLED con PUT /certificate-request/{id}/status no devuelve el cupo.

Detalle en Precios, Órdenes y Cupos.

Estadísticas por tipo de emisión​

GET /consume/{year}, GET /consume/{year}/{month}, GET /certificate-request/stats/{companyId} y GET /certificates/expiring aceptan ?issuance_flow=BIOMETRIC|DOCUMENTARY y traen el desglose por tipo:

  • /consume/*: cada fila trae by_flow ({"BIOMETRIC": n, "DOCUMENTARY": m}) y la respuesta indica en issuance_flow el filtro aplicado.
  • /certificate-request/stats/{companyId}: cada año trae by_flow con total y statuses por tipo; además grand_total_by_flow, issuance_flow y quota.by_flow.
  • /certificates/expiring: cada certificado trae issuance_flow; además total_by_flow e issuance_flow.

Sin el filtro, las cifras y claves existentes no cambian. Un issuance_flow vacío cuenta como si no lo enviaras; otro valor responde 422 INVALID_ISSUANCE_FLOW con errors.issuance_flow. Detalle en Consumo y Notificaciones.

Webhooks​

EventoNovedad
certificate_request.createddata.issuance_flow
certificate_request.status_changeddata.issuance_flow (null solo si la solicitud se eliminó antes de la entrega)
payment.approved / payment.failedSe define su contenido (order_id con el UUID de la orden, issuance_flow, quantity y vigencia de la compra), pero en esta versión se aceptan en la suscripción y todavía no generan entregas: el resultado de un pago se consulta con GET /orders/{uuid}. Empiezan a entregarse en la 1.21.1
certificate.expiringSin cambios: se acepta en la suscripción y todavía no genera entregas

La firma, las cabeceras, el tiempo de espera y la desactivación tras 10 fallos no cambian.

Configuración general y cuenta (1.19.6 a 1.19.10)​

  • PUT /company/settings ya guarda los cambios: actualiza value de los parámetros indicados por su id (el de GET /company/settings). Corrige lo indicado en la entrada 1.19.5, donde esta operación respondía 500. Detalle en Empresa.
  • Nueva operación DELETE /profile: el titular elimina su propia cuenta confirmando su contraseña actual. Revoca todos sus tokens (incluidos los Personal Access Tokens) y anonimiza sus datos personales; la empresa, sus solicitudes, pedidos y pagos se conservan. No se puede deshacer. Límite: 5 peticiones por minuto. Detalle en Perfil.

Compatibilidad​

Si tu integración…Resultado
No envía issuance_flow al crearUsa el tipo por defecto: el de siempre con viafirma y mail; DOCUMENTARY con dual
No envía issuance_flow en /pricing u /ordersCotiza y compra en el tipo por defecto
Lee solo las claves de primer nivel de /quota/statusRecibe el saldo del tipo por defecto, coherente con lo que consumirá una solicitud sin issuance_flow
Trata dual como mailFunciona: sin issuance_flow la solicitud es DOCUMENTARY, igual que con mail. Pero no podrás emitir solicitudes biométricas y mostrarás mal las que ya existan: actualiza la integración para reconocer dual y decidir por el issuance_flow de cada solicitud
Ignora los campos nuevos de webhooks y estadísticasSin efecto

Documentación​

  • La referencia de la API documenta issuance_flow, los nuevos errores y los campos por tipo de emisión en Solicitudes, Emisión, Precios, Órdenes, Cupos, Consumo, Notificaciones y Webhooks.
  • Las guías y la colección de Postman se actualizaron con el tipo de emisión por solicitud y el saldo por tipo.

¿Vas a actualizar una integración existente? Revisa la guía paso a paso, los casos de uso y la solución de problemas.