API de importación de casos de prueba

Los endpoints de importación cargan un archivo exportado y luego lo confirman directamente en un proyecto — no hay paso de vista previa ni de simulación. Una confirmación exitosa crea (o reemplaza) casos de prueba y suites en una sola petición; cualquier fila que no se pudo importar se reporta individualmente, y el resto del archivo se importa igual.

Probara es la plataforma de reimportación predeterminada. Reimportar un archivo que esta API exportó previamente (ver la API de exportación) es el camino sin configuración: cualquier formato que Probara puede exportar — JSON, XML, CSV y XLSX — puede reimportarse, y la importación conserva la fidelidad completa. También se aceptan exportaciones de Qase y TestRail, con una superficie de mapeo de campos más reducida (ver abajo).

Todas las peticiones requieren autenticación (token de API Bearer o cookie de sesión) con rol mínimo de member en la organización del proyecto. Los usuarios con rol viewer reciben 403 forbidden.

Cargar el archivo

POST/api/v1/projects/{projectId}/imports:stage

{projectId} es el código del proyecto (por ejemplo ACME). El cuerpo de la petición es multipart/form-data con una única parte file que lleva el archivo exportado.

Respuesta

200 con:

{ "uploadUlid": "01J...", "byteSize": 4821, "filename": "acme-export.json" }

uploadUlid identifica el archivo cargado para la llamada de confirmación de abajo. Los archivos cargados no se conservan indefinidamente — confirma poco después de cargar.

Errores

Estado	Código	Condición
403	forbidden	El rol del llamante es viewer
413	file_too_large	El archivo subido supera IMPORT_MAX_FILE_BYTES (10 MB)
422	validation_failed	La petición no lleva ninguna parte file
429	too_many_requests	Se superó el límite de tasa de carga de la organización

Confirmar la importación

POST/api/v1/projects/{projectId}/imports/commit

{
  "uploadUlid": "01J...",
  "sourceFormat": "probara_json",
  "targetSuiteUlid": null,
  "replaceMatching": false
}

Campo	Notas
uploadUlid	El valor devuelto por la llamada de carga anterior.
sourceFormat	Uno de probara_json, probara_xml, probara_csv, probara_xlsx, qase_xml, qase_json, qase_csv, qase_xlsx, testrail_xml, testrail_csv. El asistente web resuelve este valor automáticamente a partir de la extensión/contenido del archivo subido — un integrador que llama a la API directamente debe establecerlo explícitamente.
targetSuiteUlid	null importa debajo de la raíz del proyecto; en otro caso, la jerarquía de suites del archivo se recrea debajo de la suite indicada.
replaceMatching	Cuando es true, un caso del origen cuyo título coincida exactamente con un caso existente en la suite destino sobrescribe el contenido de ese caso en lugar de crear un duplicado.

Respuesta

200 con el reporte de la confirmación:

{
  "counts": { "suitesCreated": 2, "casesCreated": 8, "casesReplaced": 1, "rowsFailed": 0 },
  "created": [{ "caseUlid": "01J...", "displayId": "ACME-42", "title": "Login succeeds" }],
  "replaced": [],
  "failures": [],
  "warnings": []
}

failures lista las filas que no se importaron (el resto del archivo sí se confirmó); warnings lista filas que sí se importaron pero con un aviso no crítico — ver abajo.

Reimportación de Probara: fidelidad completa

Reimportar una exportación de Probara (cualquiera de los cuatro formatos) mapea de vuelta todos los campos de clasificación del sistema — prioridad, severidad, estado, tipo, capa, comportamiento, estado de automatización, es inestable (flaky), precondiciones y poscondiciones — además de cada valor de campo personalizado definido por el usuario que ya exista, emparejado automáticamente por nombre (título para JSON/XML, encabezado de columna convertido a slug para CSV/XLSX). Los pasos, etiquetas, descripción y ruta de suite siempre se conservan íntegramente sin importar la plataforma de origen.

Nunca se crea un campo ni una opción al importar. Cada coincidencia se resuelve contra los campos personalizados y las opciones existentes de la organización en el momento de confirmar — no hay carga de mapeo de campos en la petición, ni un paso de vinculación interactivo. Esto hace que la reimportación sea segura de ejecutar repetidamente (por ejemplo, para restaurar un respaldo o migrar casos entre proyectos) sin contaminar el esquema del proyecto.

Las exportaciones de Qase y TestRail mapean un conjunto más reducido — solo prioridad, tipo y estado. Los campos personalizados definidos por el usuario no se mapean para esas dos plataformas.

Comportamiento ante campos y opciones desconocidos

Una importación nunca falla una fila solo porque el valor de un campo no se pudo mapear — en su lugar, confirma el caso y registra un aviso:

Código de aviso	Significado
unmapped_value	Un valor de opción del sistema o definido por el usuario no coincidió con ninguna opción existente, y el campo no tiene un valor predeterminado configurado — el campo queda sin asignar.
defaulted_value	Igual que el anterior, pero el campo tiene una opción predeterminada configurada — el campo usa esa opción predeterminada.
unmapped_field	El título de un campo definido por el usuario (o el slug de una columna CSV/XLSX) no coincidió con ningún campo existente en el proyecto — el valor se omite, no se crea nada.

Cada fila fallida y cada aviso nombra la sourceRow y el title del caso afectado, de modo que una importación parcialmente exitosa se puede diagnosticar por completo solo con la respuesta.

Filas fallidas

Una fila falla (y su caso no se importa) solo por estas razones — cualquier otro desajuste de valor pertenece a la familia de avisos de arriba, nunca a un fallo:

Código	Condición
missing_title	La fila no tiene título.
ambiguous_match	replaceMatching está activo y el título coincide con más de un caso existente en la suite destino.

Límites de tamaño

Una importación está acotada a IMPORT_MAX_CASES (5000) casos analizados y IMPORT_MAX_FILE_BYTES (10 MB) de bytes cargados. Un archivo que supere cualquiera de los dos límites se rechaza antes de escribir cualquier suite o caso.

Límite de tasa

Tanto la carga como la confirmación están limitadas por organización (10 peticiones/hora cada una). Superar el límite devuelve 429 con { "error": { "code": "too_many_requests", ... } }.

Markdown no es un formato de importación admitido

Markdown nunca ha sido, ni es, un formato de origen importable. El asistente rechaza un archivo .md del lado del cliente con un error en línea traducido; un integrador que carga un archivo .md y trata de confirmarlo con cualquier sourceFormat recibe 422 parse_failed — el archivo no se podrá analizar como el formato declarado.

Errores

Estado	Código	Condición
403	forbidden	El rol del llamante es viewer
404	not_found	projectId, targetSuiteUlid, o el uploadUlid cargado no se resuelve en la organización activa
413	file_too_large	Los bytes cargados superan IMPORT_MAX_FILE_BYTES (nueva verificación de refuerzo al confirmar)
422	parse_failed	Los bytes cargados no se analizaron como el sourceFormat declarado, o la jerarquía de suites anida demasiado
422	empty_import	El archivo se analizó y arrojó cero casos
422	too_many_cases	La cantidad de casos analizados supera IMPORT_MAX_CASES
429	too_many_requests	Se superó el límite de tasa de importación de la organización

Ejemplo

Carga un archivo y luego confírmalo como una reimportación de Probara en JSON:

curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -F "file=@acme-export.json" \
  "https://probara.net/api/v1/projects/ACME/imports:stage"

curl -sS \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uploadUlid":"01J...","sourceFormat":"probara_json","targetSuiteUlid":null,"replaceMatching":false}' \
  "https://probara.net/api/v1/projects/ACME/imports/commit"

Páginas relacionadas

• API de exportación de casos de prueba — produce los archivos que este endpoint reimporta.