Mapeos de importación

Generado desde DialerDigital/core commit 0fc18008b3c8 — especificación openapi/dialer-v1.yaml v0.134.0. No se edita a mano; consulta Cómo se construye esta referencia. Descargar la especificación OpenAPI.

English version

Traducción en curso

Esta referencia se genera desde la especificación OpenAPI. Las cadenas que todavía no tienen traducción aparecen en inglés.

Plantillas de importación CSV (mapeo columna -> campo y opciones de análisis), versionadas de sólo anexado por tenant.

Endpoints

Método	Ruta	Resumen
GET	/v1/import-mappings	Las plantillas de importación CSV del tenant, cada una con su versión vigente
POST	/v1/import-mappings	Crear una plantilla de importación (versión 1)
GET	/v1/import-mappings/{id}	Una plantilla de importación, en su versión vigente
PATCH	/v1/import-mappings/{id}	Renombrar una plantilla, o editarla para crear una versión NUEVA
DELETE	/v1/import-mappings/{id}	Archivar una plantilla
GET	/v1/import-mappings/{id}/versions	Todas las versiones de una plantilla, de la más antigua a la más reciente
GET	/v1/import-mappings/{id}/versions/{version}	Una versión de una plantilla
GET	/v1/import-mappings/{id}/uses	Las importaciones que usaron una plantilla, de la más reciente a la más antigua

Las plantillas de importación CSV del tenant, cada una con su versión vigente

GET /v1/import-mappings

Por nombre, las vivas; ?include_archived=true añade las archivadas. Cada plantilla viene con su versión VIGENTE. Con tope de 2 000.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
include_archived	query	boolean	no

Respuestas

200

Las plantillas.

Campo	Tipo	Obligatorio	Descripción
import_mappings	arreglo de ImportMapping	sí
import_mappings[].id	string (uuid)	sí
import_mappings[].tenant_id	string (uuid)	no
import_mappings[].name	string	sí
import_mappings[].archived	boolean	sí
import_mappings[].version	integer	sí	La versión vigente.
import_mappings[].mapping	arreglo de object	sí	Lista ORDENADA de columna CSV -> campo de destino. El orden es el del archivo, porque una plantilla se aplica a un archivo cuya firma de cabecera (sus cabeceras, en orden) es igual a la de la plantilla.
import_mappings[].mapping[].column	string	sí	La cabecera del CSV, tal como la escribe el archivo.
import_mappings[].mapping[].field	string	sí	El campo de destino, o skip. Un punto opcional group.name (contact.phone_e164).
import_mappings[].options	object (ImportMappingOptions)	sí	Opciones de análisis. Las claves desconocidas se rechazan.
import_mappings[].options.separator	comma · semicolon · tab	no
import_mappings[].options.default_currency	string	no
import_mappings[].version_created_at	string (date-time)	no
import_mappings[].created_at	string (date-time)	no
import_mappings[].updated_at	string (date-time)	no

401 — Unauthorized

Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

Crear una plantilla de importación (versión 1)

POST /v1/import-mappings

name se recorta, no debe estar vacío, tiene como máximo 200 caracteres y es único entre las plantillas VIVAS del tenant (409). mapping es una lista ORDENADA de {column, field}: column es la cabecera del CSV tal como la escribe el archivo (recortada, como máximo 200 caracteres; dos entradas no pueden diferir sólo por mayúsculas o espacios), field el destino (a-z, dígitos y _, como máximo 64, con un punto group.name opcional). El servidor comprueba la FORMA de field, no un vocabulario cerrado: cada consumidor de una plantilla falla cerrado ante un campo que no conoce. Al menos una entrada debe mapear a un campo distinto de skip. options acepta separator (comma, semicolon, tab; por defecto comma) y default_currency (tres letras mayúsculas); cualquier otra clave se rechaza. Un tenant mantiene como máximo 500 plantillas vivas (422).

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
name	string	sí
mapping	arreglo de object	sí	Lista ORDENADA de columna CSV -> campo de destino. El orden es el del archivo, porque una plantilla se aplica a un archivo cuya firma de cabecera (sus cabeceras, en orden) es igual a la de la plantilla.
mapping[].column	string	sí	La cabecera del CSV, tal como la escribe el archivo.
mapping[].field	string	sí	El campo de destino, o skip. Un punto opcional group.name (contact.phone_e164).
options	object (ImportMappingOptions)	no	Opciones de análisis. Las claves desconocidas se rechazan.
options.separator	comma · semicolon · tab	no
options.default_currency	string	no

{
  "name": "Cartera Q3 — export CMS",
  "mapping": [
    {
      "column": "Cuenta",
      "field": "external_ref"
    },
    {
      "column": "Teléfono",
      "field": "phone_primary"
    },
    {
      "column": "Notas",
      "field": "skip"
    }
  ],
  "options": {
    "separator": "semicolon",
    "default_currency": "USD"
  }
}

Respuestas

201

La plantilla, en la versión 1.

Campo	Tipo	Obligatorio	Descripción
import_mapping	object (ImportMapping)	sí	Una plantilla: su cabecera y su versión VIGENTE.
import_mapping.id	string (uuid)	sí
import_mapping.tenant_id	string (uuid)	no
import_mapping.name	string	sí
import_mapping.archived	boolean	sí
import_mapping.version	integer	sí	La versión vigente.
import_mapping.mapping	arreglo de object	sí	Lista ORDENADA de columna CSV -> campo de destino. El orden es el del archivo, porque una plantilla se aplica a un archivo cuya firma de cabecera (sus cabeceras, en orden) es igual a la de la plantilla.
import_mapping.mapping[].column	string	sí	La cabecera del CSV, tal como la escribe el archivo.
import_mapping.mapping[].field	string	sí	El campo de destino, o skip. Un punto opcional group.name (contact.phone_e164).
import_mapping.options	object (ImportMappingOptions)	sí	Opciones de análisis. Las claves desconocidas se rechazan.
import_mapping.options.separator	comma · semicolon · tab	no
import_mapping.options.default_currency	string	no
import_mapping.version_created_at	string (date-time)	no
import_mapping.created_at	string (date-time)	no
import_mapping.updated_at	string (date-time)	no

400 — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

401 — Unauthorized

Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

409 — Conflict

Transición de estado no válida, conflicto de unicidad, o un asiento que está ocupado/reservado.

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

422 — Unprocessable

La forma es correcta, la semántica no (regla de dominio incumplida).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

Una plantilla de importación, en su versión vigente

GET /v1/import-mappings/{id}

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
id	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como 404.

Respuestas

200

La plantilla (también las archivadas, marcadas archived).

Campo	Tipo	Obligatorio	Descripción
import_mapping	object (ImportMapping)	sí	Una plantilla: su cabecera y su versión VIGENTE.
import_mapping.id	string (uuid)	sí
import_mapping.tenant_id	string (uuid)	no
import_mapping.name	string	sí
import_mapping.archived	boolean	sí
import_mapping.version	integer	sí	La versión vigente.
import_mapping.mapping	arreglo de object	sí	Lista ORDENADA de columna CSV -> campo de destino. El orden es el del archivo, porque una plantilla se aplica a un archivo cuya firma de cabecera (sus cabeceras, en orden) es igual a la de la plantilla.
import_mapping.mapping[].column	string	sí	La cabecera del CSV, tal como la escribe el archivo.
import_mapping.mapping[].field	string	sí	El campo de destino, o skip. Un punto opcional group.name (contact.phone_e164).
import_mapping.options	object (ImportMappingOptions)	sí	Opciones de análisis. Las claves desconocidas se rechazan.
import_mapping.options.separator	comma · semicolon · tab	no
import_mapping.options.default_currency	string	no
import_mapping.version_created_at	string (date-time)	no
import_mapping.created_at	string (date-time)	no
import_mapping.updated_at	string (date-time)	no

401 — Unauthorized

Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

Renombrar una plantilla, o editarla para crear una versión NUEVA

PATCH /v1/import-mappings/{id}

Envía al menos uno de name, mapping, options. Un renombrado cambia sólo la cabecera. Cambiar mapping u options añade la versión n+1 (el que se omite se hereda de la vigente) y deja la versión n exactamente como estaba: una importación puede haberla usado. Una edición que no cambia nada no escribe ninguna versión. base_version es opcional y, si se envía, debe ser la versión vigente; en caso contrario 409 y no se escribe nada, de modo que dos personas que editen la misma plantilla no se sobrescriban sin darse cuenta. Una plantilla archivada no se puede editar (409); una plantilla tiene como máximo 1 000 versiones (422).

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
id	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como 404.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
name	string	no
mapping	arreglo de object	no	Lista ORDENADA de columna CSV -> campo de destino. El orden es el del archivo, porque una plantilla se aplica a un archivo cuya firma de cabecera (sus cabeceras, en orden) es igual a la de la plantilla.
mapping[].column	string	sí	La cabecera del CSV, tal como la escribe el archivo.
mapping[].field	string	sí	El campo de destino, o skip. Un punto opcional group.name (contact.phone_e164).
options	object (ImportMappingOptions)	no	Opciones de análisis. Las claves desconocidas se rechazan.
options.separator	comma · semicolon · tab	no
options.default_currency	string	no
base_version	integer	no

{
  "base_version": 1,
  "options": {
    "separator": "comma"
  }
}

Respuestas

200

La plantilla, en su versión vigente tras la edición.

Campo	Tipo	Obligatorio	Descripción
import_mapping	object (ImportMapping)	sí	Una plantilla: su cabecera y su versión VIGENTE.
import_mapping.id	string (uuid)	sí
import_mapping.tenant_id	string (uuid)	no
import_mapping.name	string	sí
import_mapping.archived	boolean	sí
import_mapping.version	integer	sí	La versión vigente.
import_mapping.mapping	arreglo de object	sí	Lista ORDENADA de columna CSV -> campo de destino. El orden es el del archivo, porque una plantilla se aplica a un archivo cuya firma de cabecera (sus cabeceras, en orden) es igual a la de la plantilla.
import_mapping.mapping[].column	string	sí	La cabecera del CSV, tal como la escribe el archivo.
import_mapping.mapping[].field	string	sí	El campo de destino, o skip. Un punto opcional group.name (contact.phone_e164).
import_mapping.options	object (ImportMappingOptions)	sí	Opciones de análisis. Las claves desconocidas se rechazan.
import_mapping.options.separator	comma · semicolon · tab	no
import_mapping.options.default_currency	string	no
import_mapping.version_created_at	string (date-time)	no
import_mapping.created_at	string (date-time)	no
import_mapping.updated_at	string (date-time)	no

400 — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

401 — Unauthorized

Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

409 — Conflict

Transición de estado no válida, conflicto de unicidad, o un asiento que está ocupado/reservado.

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

422 — Unprocessable

La forma es correcta, la semántica no (regla de dominio incumplida).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

Archivar una plantilla

DELETE /v1/import-mappings/{id}

Las plantillas nunca se borran: las versiones que usó una importación son evidencia. Archivar libera el nombre para una plantilla nueva y saca la plantilla de la lista por defecto; ya no se puede editar ni nombrar en una importación. Idempotente.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
id	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como 404.

Respuestas

204

La plantilla está archivada.

401 — Unauthorized

Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

Todas las versiones de una plantilla, de la más antigua a la más reciente

GET /v1/import-mappings/{id}/versions

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
id	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como 404.

Respuestas

200

Las versiones (con tope de 1 000).

Campo	Tipo	Obligatorio	Descripción
versions	arreglo de ImportMappingVersion	sí
versions[].mapping_id	string (uuid)	sí
versions[].version	integer	sí
versions[].mapping	arreglo de object	sí	Lista ORDENADA de columna CSV -> campo de destino. El orden es el del archivo, porque una plantilla se aplica a un archivo cuya firma de cabecera (sus cabeceras, en orden) es igual a la de la plantilla.
versions[].mapping[].column	string	sí	La cabecera del CSV, tal como la escribe el archivo.
versions[].mapping[].field	string	sí	El campo de destino, o skip. Un punto opcional group.name (contact.phone_e164).
versions[].options	object (ImportMappingOptions)	sí	Opciones de análisis. Las claves desconocidas se rechazan.
versions[].options.separator	comma · semicolon · tab	no
versions[].options.default_currency	string	no
versions[].created_at	string (date-time)	no

401 — Unauthorized

Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

Una versión de una plantilla

GET /v1/import-mappings/{id}/versions/{version}

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
id	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como 404.
version	path	integer	sí	El número de versión (>= 1). Una desconocida, mal formada o de otro tenant se lee como 404.

Respuestas

200

La versión, exactamente como se escribió.

Campo	Tipo	Obligatorio	Descripción
version	object (ImportMappingVersion)	sí	Una versión inmutable de una plantilla.
version.mapping_id	string (uuid)	sí
version.version	integer	sí
version.mapping	arreglo de object	sí	Lista ORDENADA de columna CSV -> campo de destino. El orden es el del archivo, porque una plantilla se aplica a un archivo cuya firma de cabecera (sus cabeceras, en orden) es igual a la de la plantilla.
version.mapping[].column	string	sí	La cabecera del CSV, tal como la escribe el archivo.
version.mapping[].field	string	sí	El campo de destino, o skip. Un punto opcional group.name (contact.phone_e164).
version.options	object (ImportMappingOptions)	sí	Opciones de análisis. Las claves desconocidas se rechazan.
version.options.separator	comma · semicolon · tab	no
version.options.default_currency	string	no
version.created_at	string (date-time)	no

401 — Unauthorized

Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

Las importaciones que usaron una plantilla, de la más reciente a la más antigua

GET /v1/import-mappings/{id}/uses

Una fila por importación que nombró la plantilla (?mapping_id= en POST /v1/debts/import o POST /v1/debt-lists/{id}/import): la versión que usó y cuántos elementos entraron y fallaron. De sólo anexado. Con tope de 200.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
id	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como 404.

Respuestas

200

Los usos.

Campo	Tipo	Obligatorio	Descripción
uses	arreglo de ImportMappingUse	sí
uses[].id	string (uuid)	sí
uses[].mapping_id	string (uuid)	sí
uses[].version	integer	sí
uses[].list_id	string (uuid) | null	no	La lista, cuando la importación pasó por /v1/debt-lists/{id}/import.
uses[].imported	integer	sí
uses[].failed	integer	sí	Número de elementos que fallaron.
uses[].created_at	string (date-time)	no

401 — Unauthorized

Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}