Skip to main content
POST
Exportação em massa de entidades

Visão geral

Exporta entidades com os mesmos filtros de GET /entities e gera um arquivo (csv, xlsx ou json). Com deliveryMode: "download_only", o arquivo fica disponível no histórico sem enviar e-mail nem consumir créditos de e-mail. Com deliveryMode: "email", ele também é enviado aos destinatários informados. A resposta é 202 com jobId.

Endpoint

Autenticação, permissões e marketplace

Sempre requer Authorization, X-Organization-ID e entities:export. A integração global_sender_email, o remetente e o saldo são verificados somente com deliveryMode: "email"; a cobrança é por destinatário. download_only não consome créditos de e-mail.

Domínio e remetente

  • fromEmail: domínio verificado; remetente cadastrado não é obrigatório.
  • fromSenderId: UUID em organization_email_senders.
  • Não enviar os dois juntos.

Corpo JSON

string
download_only para manter o arquivo somente no histórico, ou email para adicionar o envio por e-mail. Por compatibilidade, se omitido com destinatários informados, é interpretado como email.
string[]
Obrigatório e não vazio com deliveryMode: "email" (máx. 26 deduplicados). Deve ser [] com download_only.
string
required
csv, xlsx ou json.
object
Mesma forma dos filtros de GET /entities. Padrão {}.
string
en, es ou pt para o e-mail de conclusão quando deliveryMode for email.
string[]
Colunas snake_case opcionais; omitir = todas permitidas.
string (uuid)
Remetente por UUID. Aplica-se somente a email e é exclusivo com fromEmail.
string
Remetente em domínio verificado. Aplica-se somente a email e é exclusivo com fromSenderId.

Exemplo sem e-mail

Exemplo com e-mail

Resposta 202

Acompanhamento

  • GET /entities/export/jobs — histórico paginado de exportações da organização.
  • GET /entities/export/jobs/{jobId} — status (queued, running, completed, completed_email_failed, failed) e modo de entrega.
  • GET /entities/export/jobs/{jobId}/download — download autenticado enquanto o arquivo estiver disponível.
  • Se o envio por e-mail falhar após a geração, o job fica como completed_email_failed e continua disponível no histórico.
As respostas de listagem e detalhe incluem fileExpiresAt. O campo aceita null: nesse caso, o arquivo armazenado não expira. linkExpiresAt é independente e indica somente quando o link assinado enviado por e-mail deixa de funcionar. Novos arquivos de exportações de entidades e transações não expiram e permanecem disponíveis no histórico, salvo remoção explícita.

Erros 400

Os erros de modo incluem EXPORT_RECIPIENTS_REQUIRED, EXPORT_RECIPIENTS_NOT_ALLOWED e EXPORT_STORAGE_REQUIRED. Com deliveryMode: "email", também se aplicam os erros de pre-flight de report-export-email, como domínio não verificado ou saldo insuficiente.

Relacionado