Disparar la emisión del certificado (proveedor mail o viafirma)

POST 
/certificate-request/:id/issue

Inicia la emisión del certificado de la solicitud con el proveedor de su tipo de emisión. Resolución del proveedor: lo decide el flujo de la solicitud (issuance_flow, fijado al crearla): BIOMETRIC → viafirma, DOCUMENTARY → mail, sea cual sea hoy el issuance_provider de la empresa (viafirma, mail o dual). Si ese proveedor no puede atender la solicitud se responde 422, sin probar otro. El campo provider del cuerpo no elige el proveedor: si contradice el flujo responde 422 ISSUANCE_PROVIDER_MISMATCH (recomendación: no enviarlo). Cuerpo manual de la emisión documental (request_status o user_of_change, que envían «Procesar / enviar correo» y «Reenviar solicitud»): solo se admite sobre solicitudes DOCUMENTARY; sobre una BIOMETRIC responde 409 ISSUANCE_FLOW_ACTION_NOT_ALLOWED sin abrir ningún trámite. Condiciones de viafirma: módulo Viafirma habilitado, email_certificate informado y sin otro trámite Viafirma vigente para la solicitud. Si la solicitud tiene varios trámites se evalúa el vigente (prioridad: con certificado emitido > con verificación de identidad completada > en curso > fallido > cancelado > sin estado; a igual prioridad, el más reciente): si está en FAILED, FAILED_RECOVERABLE o EXPIRED se permite reintentar; en cualquier otro estado (en curso, CANCELLED, REVOKED, COMPLETED) no. Solo puede haber una emisión Viafirma a la vez por solicitud: si otra emisión (p. ej. la automática) todavía está enviando a Viafirma y aún no registró su trámite, esta llamada responde 409 de inmediato, sin esperar; si la otra ya registró su trámite, este cuenta como trámite vigente en curso y la llamada no da 409: responde 422 ('El proveedor 'viafirma' del tipo de emisión de la solicitud no soporta esta solicitud.'). Responde 201 con el trámite en SUBMITTED; desde ahí avanza solo (polling cada 60 s) y se consulta con GET /certificate-request/{id}/issuance. Condiciones de mail: la solicitud debe tener al menos un archivo adjunto de tipo ATTACHED; se pasa a PROCESSING y se envía por correo a la autoridad certificadora. Responde 200. Límite de peticiones: 5 por minuto por usuario en este endpoint, además del límite general de 60 por minuto.

Request

Responses

200

Proveedor mail: solicitud enviada por correo. dataRecords.provider='mail', dataRecords.status='sent', dataRecords.external_id=null, dataRecords.resource_id=ID de la solicitud y dataRecords.data={"data": [CertificateRequest actualizado]}.

201

Proveedor viafirma: trámite creado en Viafirma RA. dataRecords.status='submitted', dataRecords.external_id=cod_request, dataRecords.resource_id=ID del trámite (viafirma_certificate_requests.id) y dataRecords.data con public_id, profile_type, identity_type, internal_state, remote_status, submitted_at y expires_at.

400

Proveedor mail: la solicitud no tiene adjuntos ATTACHED al momento del envío u otro error de datos al enviarla. También responde 400, sin provider, cuando ocurre un error de integridad de datos (p. ej. dato duplicado, dato relacionado inexistente o dato obligatorio faltante) fuera del proveedor mail, por ejemplo al registrar el trámite Viafirma; el mensaje es un texto seguro, sin SQL ni datos, que depende del error (p. ej. 'Ya existe un registro con ese valor (dato duplicado).', 'No se puede completar: un dato relacionado no existe.', 'Falta un dato obligatorio.' o 'Los datos no cumplen las reglas de integridad (dato duplicado o en uso).').

401

No autenticado (token ausente, inválido o expirado).

403

Proveedor mail: la empresa del usuario está inactiva.

404

La solicitud no existe o pertenece a otra empresa; el administrador accede a todas ('La solicitud de certificado {id} no existe.'), o (proveedor mail) el usuario no tiene empresa asociada. Solo se llega a esta comprobación con un cuerpo válido (ver 422).

409

ISSUANCE_FLOW_ACTION_NOT_ALLOWED (con error_code, sin provider): el cuerpo trae request_status o user_of_change (acción manual de la emisión documental) y la solicitud es BIOMETRIC; no se crea ningún trámite. Proveedor viafirma: otra emisión de la misma solicitud está enviando a Viafirma en este momento y aún no registró su trámite ('La solicitud {id} ya tiene un trámite Viafirma en curso (emisión en curso).'; si ya lo registró, la respuesta es 422, ver la descripción), o el trámite se creó entre la validación del proveedor y el envío ('La solicitud {id} ya tiene un trámite Viafirma en curso (id={trámite}, state={estado}).'). En ambos casos el mensaje contiene 'ya tiene un trámite Viafirma en curso' y provider='viafirma'. No se crea ningún trámite nuevo; consulte GET /certificate-request/{id}/issuance.

422

Validación del cuerpo fallida (con errors), ISSUANCE_PROVIDER_MISMATCH (con error_code y errors.issuance_flow): el provider del cuerpo contradice el tipo de emisión de la solicitud; o error de negocio (con provider): el proveedor del tipo de emisión no soporta la solicitud (falta email_certificate, ya hay un trámite Viafirma vigente, módulo Viafirma deshabilitado o, para mail, no hay adjuntos ATTACHED); ningún proveedor disponible; organization_type obligatorio para FE-PJ o prohibido para FE-PN; datos de la solicitud incompletos; o Viafirma RA rechazó la petición o devolvió una respuesta inválida (error 4xx distinto de 429, o respuesta sin codRequest/publicId): message = El servicio de Viafirma rechazó la solicitud. Revisa los datos e intenta de nuevo., seguido opcionalmente de Código: {errorCode}. cuando Viafirma devuelve un código que cumple ^[A-Za-z0-9_.-]{1,64}$, con provider=viafirma. La URL interna de la RA y el cuerpo de la respuesta remota solo quedan en el log. También responde 422 con provider=viafirma (y el mensaje del error) cuando falla la preparación del trámite, antes de contactar a Viafirma y sin registrar ningún trámite: el tipo de documento de identidad o el tipo de organización de la solicitud no tiene equivalente en Viafirma; a la solicitud le falta un dato obligatorio del certificado (país, departamento, ciudad, dirección, número de documento, correo o nombres y apellidos del representante legal y, para FE-PJ, la razón social) o el país no es un código de 2 letras; o falla por un problema interno la generación de la llave o del CSR (si no se puede guardar la llave privada en el almacén de llaves la respuesta es 503, ver abajo). Estos últimos son fallos del servidor, no de los datos enviados: si persisten al reintentar, contacte a soporte. Los fallos de comunicación con Viafirma no responden 422 sino 502. La validación del cuerpo se ejecuta antes de comprobar que la solicitud exista y pertenezca a la empresa: con un cuerpo inválido se responde 422 (con errors) aunque la solicitud no exista.

429

Más de 5 emisiones por minuto del mismo usuario (o límite general de 60 peticiones por minuto; en ese caso el cuerpo es ThrottleErrorResponse).

500

Error interno. Hay dos formas de cuerpo: (a) error de la aplicación al emitir: {success:false, message} (con provider cuando lo genera el proveedor), p. ej. proveedor mal configurado, o no se pudo resolver el proveedor del tipo de emisión de la solicitud ('No se pudo resolver el proveedor de emisión de la solicitud. Intente de nuevo más tarde.'); cualquier otro error inesperado responde 'Error interno del servidor. {detalle}' (un fallo de base de datos se reemplaza por un texto genérico sin SQL ni datos); (b) error no controlado, p. ej. cuando {id} no es un número entero (como el UUID de la solicitud) o falla la base de datos al buscar la solicitud: lo responde el manejador de errores general con {"message": "Server Error"}, sin success, en producción; si la petición no envía Accept: application/json, la respuesta puede ser una página HTML. Los fallos al generar la llave o el CSR del trámite Viafirma no responden 500 sino 422, y el fallo al guardar la llave privada responde 503; ver arriba y abajo. Un error de integridad de datos al registrar la emisión no responde 500 sino 400; ver arriba.

502

Proveedor viafirma: fallo transitorio al comunicarse con Viafirma RA (error de red o tiempo de espera, o Viafirma respondió 5xx o 429). No se registra ningún trámite; se puede reintentar la emisión pasados unos segundos. El detalle técnico solo queda en el log.

503

Proveedor viafirma: no se pudo guardar la llave privada en el almacén de llaves (AWS KMS o cifrado local). No se registra ningún trámite; se puede reintentar. El detalle técnico solo queda en el log.