Skip to main content
A nova importação depende de MCP_IMPORTS_ENABLED na API e no worker. O dashboard também depende de NEXT_PUBLIC_MCP_IMPORTS_ENABLED. FeatureNotEnabled indica que a implantação ainda não habilitou o recurso.
Use uma chave pessoal com imports.write, resources.read, projetos explicitamente autorizados e uma função atual que permita gerenciar públicos. Assinaturas de tópicos também exigem permissão atual para gerenciar automações. Chaves existentes não recebem permissões novas automaticamente. Cobrança, planos, pagamentos, créditos, faturas e assinaturas comerciais ficam fora do MCP.

​
Fluxo de importação

  1. Descubra a conta, a equipe e o projeto. Confirme o destino com project_get e informe project_id em cada ferramenta.
  2. Crie a importação com imports_create, declarando o formato, o mapeamento, as referências e uma idempotency_key exclusiva.
  3. Envie o arquivo para a URL de imports_upload_url, usando apenas os cabeçalhos retornados. Nunca envie a chave pessoal para o armazenamento. Como alternativa, use imports_append com até 500 linhas e 1 MiB por lote. Reutilize part_id somente para dados idênticos.
  4. Execute imports_validate e consulte imports_get, respeitando poll_after_ms.
  5. Analise imports_errors e imports_preview. A prévia não altera contatos nem entrega mensagens.
  6. Aplique a proposta revisada com imports_commit, prepared_action_id e uma chave de idempotência estável. A preparação expira em dez minutos.
  7. Acompanhe o resultado e os totais aplicados, ignorados e rejeitados.
Agentes de programação podem transmitir arquivos com o SDK ou CLI. Clientes de chat sem acesso aos bytes devem fornecer o upload_handoff.url ao titular autenticado. A página verifica o projeto e o proprietário; o agente continua usando imports_get para acompanhar a conclusão. Um MCP hospedado não pode ler um caminho local.

​
Dados e limites

São aceitos contatos, declarações de propriedades, definições de públicos estáticos ou dinâmicos, associações estáticas e assinaturas de tópicos. Os formatos são CSV, Excel .xlsx, arrays JSON e NDJSON. Os limites são um milhão de linhas, 500 MiB por arquivo, 100 colunas e 64 KiB por linha. Excel exige o nome exato da planilha; fórmulas, macros, arquivos criptografados e links externos são rejeitados. URLs remotas arbitrárias não são buscadas. Campos não vazios são mesclados. Valores omitidos e células vazias preservam os dados existentes. Limpar um campo exige clear_empty: true no mapeamento. Emails são normalizados. A primeira ocorrência prevalece; repetições recebem um diagnóstico. Duplicidades ambíguas existentes precisam de correção explícita. Declare propriedades, públicos e tópicos desconhecidos antes de referenciá-los. Públicos dinâmicos recebem regras, e suas associações continuam calculadas. Novas associações permanecem sem assinatura, a menos que a importação declare consent: "asserted" e a linha informe is_subscribed: true. Descadastros existentes e supressões de entrega continuam protegidos. Por padrão, linhas válidas são aplicadas e as inválidas são relatadas. strict: true bloqueia a aplicação quando há linhas inválidas.

​
Efeitos e recuperação

automation_effects: "suppress" é o padrão e permanece nos jobs, eventos derivados e reprocessamentos. trigger pode iniciar ou retomar automações e enviar mensagens reais; exige automations.trigger e autorização atual de automações. Revogação, expiração, alteração de associação ou redução de função interrompem o trabalho seguinte. Cancelar interrompe os próximos lotes sem desfazer linhas já aplicadas. imports_retry_failed revalida o trabalho sem sucesso e exige uma nova revisão e confirmação; linhas aplicadas não são repetidas. Corrija linhas inválidas em uma nova importação. Reutilize os recibos e as chaves de idempotência para evitar duplicação. Passe metadata.next como after para paginar os diagnósticos. Arquivos e relatórios de linhas são removidos após sete dias. Resumos de auditoria sem conteúdo dos contatos seguem a política de retenção existente.

​
CLI

Configure a chave em SENDREALM_API_KEY; não a coloque em argumentos, prompts ou repositórios. O upload valida, mas não aplica automaticamente. Consulte os exemplos do SDK.