Subir archivos en Base64 a una solicitud

POST 
/certificate-request/:id/files

Adjunta uno o más archivos, enviados en Base64 dentro del JSON (no multipart), a una solicitud existente. Tipos permitidos: PDF, JPG, PNG, GIF y ZIP; el tipo se valida con el prefijo Data URI si viene, o se detecta por el contenido (el mime_type guardado y devuelto solo se toma del prefijo Data URI; sin prefijo queda en null). Límites: 2 MB por archivo (decodificado); la solicitud no puede superar 6 archivos en total contando los que ya tiene (incluido el Excel generado al crearla); 20 cargas por minuto por usuario. Certificado en ZIP: si el nombre del archivo termina en .zip (en minúsculas; un .ZIP se guarda sin procesar y no se registran los datos del certificado) y se envía pin, el servidor descomprime el ZIP con el NIT de la solicitud como contraseña (NIT + DV si es Persona Jurídica), busca el certificado solo en la raíz del ZIP (no en subcarpetas): usa el primer archivo .p12/.pfx (extensión en minúsculas) de la raíz; si no hay ninguno, intenta con el último archivo de la raíz en orden alfabético, por lo que un .P12 en mayúsculas o sin extensión puede funcionar si es el único archivo, pero falla si hay otros archivos que se ordenan después (use siempre extensión .p12 o .pfx en minúsculas); lo valida con el pin y guarda en la solicitud la fecha de vencimiento del certificado (expiration_date), el inicio y el fin de vigencia (issued_at, cert_valid_to) y el PIN. El pin se aplica a todos los .zip del envío. Tras cada archivo se disparan el webhook de archivo cargado y, para JPG/PNG/PDF, el análisis automático de documentos (si está habilitado en el servidor). Todo o nada: si falla cualquier archivo del envío, no se registra ninguno (tampoco se guardan los datos del certificado en la solicitud); corrija el error y reintente el lote completo. Nota: en ese caso puede llegar el webhook de archivo cargado de un archivo que finalmente no quedó registrado. Orden de comprobación: la validación del cuerpo (400) se evalúa antes que la existencia de la solicitud (404), así que un id inexistente o de otra empresa con un cuerpo inválido recibe 400.

Request

Responses

200

Archivos guardados

400

Validación o regla de negocio incumplida, con dos formatos. CertificateFormRequestError (validación): attachments ausente o vacío, Base64 inválido, archivo de más de 2 MB, tipo no permitido, document_type o pin inválidos, name que no es texto o de más de 255 caracteres, type que no es texto o de más de 100 caracteres (aunque se ignora, se sigue validando), o size no entero. ApiErrorResponse (negocio): No se pueden subir más de 6 archivos en total.; solicitud sin ruta de almacenamiento; ZIP sin ningún archivo en su raíz: No se ha encontrado el archivo P12 o PFX en el ZIP.; certificado que no se pudo leer con el pin (PIN incorrecto, o el archivo tomado de la raíz del ZIP no es un certificado válido, por ejemplo un ZIP sin .p12/.pfx en minúsculas pero con otros archivos): The certificate could not be read. ... (en inglés, seguido del detalle técnico). Un ZIP que no se puede abrir o descomprimir con el NIT no responde 400 sino 500.

401

No autenticado

403

La empresa del usuario que llama está inactiva (también aplica a un administrador cuya propia empresa está inactiva, aunque suba archivos a una solicitud de otra empresa). Se evalúa después del límite de 6 archivos. Mensaje: Acceso no autorizado. La empresa se encuentra inactiva.

404

La solicitud no existe o pertenece a otra empresa (el administrador accede a todas). Mensaje: Solicitud de certificado no encontrada. Si quien llama es un administrador sin empresa asociada, el mensaje es No se encontró la empresa asociada al usuario.

422

Solo si se envía un archivo como parte de multipart/form-data (formato no soportado por este endpoint) cuyo tipo real no está permitido, por ejemplo un texto plano o un ejecutable. Se comprueba antes que la validación del cuerpo. Mensaje: El archivo '<nombre>' tiene un tipo de contenido no permitido (<mime>). Envíe el cuerpo en JSON con attachments[].base64.

429

Más de 20 cargas por minuto. Mensaje: Demasiadas solicitudes de carga de archivos. Intente nuevamente en un minuto. (ApiErrorResponse). También puede responder 429 el límite general de 60 peticiones por minuto; en ese caso el cuerpo es ThrottleErrorResponse (Too Many Attempts., sin success) e incluye la cabecera Retry-After.

500

Error interno. Incluye un ZIP enviado con pin que no se pudo abrir (corrupto o no es un ZIP) o descomprimir con el NIT (NIT + DV en Persona Jurídica): message empieza por Error interno del servidor. seguido de Error al extraer el archivo ZIP. Verifica la contraseña o los permisos del directorio de destino. ... o de No se pudo abrir el archivo ZIP. .... Nota: un archivo sin name cuyo Base64 no trae prefijo Data URI también responde 500, pero con el cuerpo genérico {"message": "Server Error"}, sin success (o una página HTML si la petición no envía Accept: application/json); envíe siempre name o el prefijo Data URI. Ocurre lo mismo (500 genérico) si base64 llega como objeto o array en vez de texto; envíe siempre base64 como string.