Skip to main content
POST
Exportación masiva de entidades

Resumen

Exporta entidades según los mismos filtros que GET /entities y genera un archivo (csv, xlsx o json). Con deliveryMode: "download_only" queda disponible en el historial sin enviar correo ni consumir créditos de email. Con deliveryMode: "email" también se envía a los destinatarios indicados. La respuesta es 202 con jobId.

Endpoint

Autenticación, permisos y marketplace

Siempre requiere Authorization, X-Organization-ID y permiso entities:export. La integración global_sender_email, el remitente y el saldo solo se validan con deliveryMode: "email"; el cobro es por destinatario. El modo download_only no consume créditos de email.

Dominio y remitente

Misma semántica que el PDF por correo:
  • fromEmail: dominio verificado en la org; no hace falta fila en Remitentes.
  • fromSenderId: UUID en organization_email_senders.
  • No enviar ambos a la vez.

Cuerpo JSON

string
download_only para dejar el archivo únicamente en el historial, o email para agregar el envío por correo. Por compatibilidad, si se omite y hay destinatarios, se interpreta como email.
string[]
Obligatorio y no vacío con deliveryMode: "email" (máx. 26 deduplicados). Debe ser [] con download_only.
string
required
csv, xlsx o json.
object
Filtros con la misma forma que el query de GET /entities (búsqueda, fechas, tipo, etc.). Por defecto {}.
string
en, es o pt para el correo de finalización cuando deliveryMode es email.
string[]
Columnas snake_case del layout de exportación; omitir o [] = todas las columnas permitidas.
string (uuid)
Remitente por UUID. Solo aplica a email y es excluyente con fromEmail.
string
Remitente por dirección en dominio verificado. Solo aplica a email y es excluyente con fromSenderId.

Ejemplo sin correo

Ejemplo con correo

Respuesta 202

Seguimiento del job

  • GET /entities/export/jobs — historial paginado de la organización.
  • GET /entities/export/jobs/{jobId} — estado (queued, running, completed, completed_email_failed, failed) y modo de entrega.
  • GET /entities/export/jobs/{jobId}/download — descarga autenticada mientras el archivo siga disponible.
  • Si falla un correo después de generar el archivo, el job queda como completed_email_failed y todavía puede descargarse desde el historial.
Las respuestas de listado y detalle incluyen fileExpiresAt. Es nullable: null significa que el archivo guardado no caduca. linkExpiresAt es independiente e indica únicamente cuándo deja de funcionar el enlace firmado enviado por correo. Los archivos nuevos de exportaciones de entidades y transacciones no caducan y quedan disponibles en el historial salvo que se eliminen de forma explícita.

Errores 400

Los errores de modo incluyen EXPORT_RECIPIENTS_REQUIRED, EXPORT_RECIPIENTS_NOT_ALLOWED y EXPORT_STORAGE_REQUIRED. Con deliveryMode: "email" también aplican los códigos de pre-flight de report-export-email, como dominio no verificado o saldo insuficiente.

Relacionado