Batch import
Cargar lotes, pólizas, clientes y siniestros por API, con reporte por fila.
POST /v1/import/{aois|policies|clients|claims} encola sobre /v1/jobs, el
mismo contrato asíncrono del cálculo de footprint. No hay un segundo mecanismo:
dos formas de preguntar "¿terminó?" garantizan que aprendas la equivocada la
mitad de las veces.
Fuente del diagrama (mermaid)
flowchart TD
F[Archivo] --> P[Parseo por fila]
P --> V{¿validate_only?}
V -- sí --> R1[200 · reporte, nada escrito]
V -- no --> J[202 · job + preview]
J --> W[Worker aplica las filas aceptadas]
W --> R2[GET /v1/jobs/id/result]
curl -sS "$SBOX/v1/import/clients?validate_only=true" -X POST \
-H "authorization: Bearer $TOKEN" \
-H "idempotency-key: import-clients-dryrun-1" \
-H "content-type: application/json" \
-d '{"format":"csv","columnMapping":{"displayName":"nombre","contactEmail":"mail"},"content":"nombre,mail\nCoop Uno,uno@sbox.invalid\nSin mail,\n"}'Por fila, no por archivo
Una aseguradora sube trescientas pólizas y tres vienen rotas. Rechazar el archivo entero la obliga a encontrarlas a ojo; aceptarlo entero mete datos inválidos en contratos que después se peritan. Entran las 297 y las 3 vuelven con su número de fila y su motivo.
atomic: true existe para el caso contrario y es opt-in: si fuera el
default, el caso frecuente —archivo grande con errores de tipeo— sería el caso
caro.
Formatos
GeoJSON, KML y CSV-con-WKT para AOIs; CSV o JSON con columnMapping para el
resto. El CSV soporta lo que Excel en español escribe de verdad: BOM, ;
como delimitador, comillas con coma adentro y CRLF.
Lo que se rompe
code | Qué pasó |
|---|---|
missing_required_field | Falta un campo obligatorio del tipo |
invalid_field_value | Correo mal formado, número no positivo |
invalid_geometry | Lo dice el evaluador compartido con la consola |
duplicate_in_payload | La fila se repite dentro del mismo archivo |
duplicate_in_tenant | Ese id natural ya existe en la organización |
unknown_reference | Apunta a un clientId/aoiId que no existe |
row_limit_exceeded | Más de 5.000 filas |
atomic_batch_aborted | La fila era válida pero el lote atómico falló |
Límites: 5.000 filas, 8 MiB (413 por encima). El permiso lo decide el tipo:
importar pólizas pide underwriting:write, importar lotes portfolio:write.