Bulk API (Importação/Exportação de Dados)
Migrações, cargas de abertura, arquivos de interface mensais — quando a contagem de registros tem vírgulas, a ferramenta é a Bulk API padrão (e seu rosto mais amigável, o Data Loader). Nos objetos da REDA Financials, ela se comporta exatamente como a REST, com uma propriedade crucial preservada: cada trigger é executado em cada linha, de modo que os documentos carregados em massa são documentos reais — numerados, validados, prontos para contabilização.
O padrão de carga que funciona
Carregue na ordem de dependência, como rascunhos
Primeiro os dados mestres (contas, produtos, contas contábeis — geralmente via UI/configuração, não em massa), depois os cabeçalhos de documento (Rascunho), depois as linhas. Mantenha sua referência de origem no campo Reference para rastreabilidade e idempotência.
Contabilize em uma segunda passagem
Uma atualização em massa que muda refin__Status__c para 'Posted' executa o mecanismo completo por registro. Como alternativa, contabilize pela UI com Contabilização em massa — mesma engrenagem, com uma tabela de resultados visível para o usuário. De qualquer forma, as falhas são por registro: os sucessos permanecem, e o arquivo de erros indica o motivo exato de cada falha.
Verifique como um contador, não como um engenheiro
A contagem de linhas bater é necessária, mas não suficiente: execute o balancete e concilie com o sistema de origem. O guia de migração é a lista de verificação completa.
Notas de ajuste fino para objetos contábeis
- A contabilização é a etapa pesada — o motor de impostos, as gravações no livro razão e as validações são executados por documento. Use tamanhos de lote moderados na passagem de contabilização (comece com cerca de 50–100 documentos por lote e observe) em vez de maximizar; o modo serial evita disputa de bloqueios em pais compartilhados, como entidades e sequências.
- A numeração de documentos sob carga é segura — as sequências são atribuídas atomicamente; inserções paralelas não duplicam números. Se você estiver preservando números legados, grave o Name explicitamente, e a exclusividade é validada.
- As exportações são triviais — consulta Bulk em qualquer objeto
refin__; o livro razão (refin__Accounting_Transaction__c) é exportado sem problemas para alimentar data warehouses.
Bulk API 2.0, na prática
O ciclo de vida padrão do job, direcionado a objetos refin__:
| Etapa | Método e endpoint |
|---|---|
| Criar um job de ingestão | POST /services/data/v65.0/jobs/ingest (o corpo indica o objeto, ex.: refin__Purchase_Invoice__c, e a operação) |
| Fazer upload do CSV | PUT /services/data/v65.0/jobs/ingest/{jobId}/batches |
| Iniciar o processamento | PATCH /services/data/v65.0/jobs/ingest/{jobId} com o estado UploadComplete |
| Consultar o status | GET /services/data/v65.0/jobs/ingest/{jobId} |
| Coletar os resultados | GET …/{jobId}/successfulResults e …/{jobId}/failedResults |
| Exportar em escala | POST /services/data/v65.0/jobs/query com o seu SOQL |
A passagem de contabilização é o CSV mais simples que você vai enviar — Ids de registro e um único campo:
Id,refin__Status__c
a0Y8d000002GhIjEAK,Posted
a0Y8d000002GhIkEAK,Posted
a0Y8d000002GhIlEAK,PostedCada linha que falha cai em failedResults com a mensagem de validação literal do pacote na coluna de erro — a mesma frase que um usuário leria, pronta para a sua planilha de conciliação.
A carga de abertura da Meridian, em números
Quando a entidade do Reino Unido da Meridian Properties Group entrou em produção, a virada foi três jobs Bulk executados em sequência em um sábado: 1.830 cabeçalhos de faturas de venda em aberto (Rascunho), suas 2.614 linhas, e depois a passagem de contabilização. O job de contabilização retornou 1.821 sucessos e 9 falhas — todas com a mesma mensagem sobre um período que não havia sido aberto para as faturas legadas mais antigas. A equipe abriu o período, executou novamente um CSV de 9 linhas e conciliou o balancete com o sistema legado antes do almoço de domingo. A lição que ficou: o arquivo de erros é a lista de pendências — pequena, literal e finita.
Erros comuns a evitar
| Erro | Por que prejudica | Faça isto em vez disso |
|---|---|---|
| Carregar linhas antes de os cabeçalhos terminarem | As linhas fazem referência a cabeçalhos que ainda não existem — uma parede de falhas de busca (lookup) | Sequencie os jobs: cabeçalhos completos, depois linhas, depois a passagem de contabilização |
| Maximizar o paralelismo na passagem de contabilização | A contabilização é a etapa pesada; lotes paralelos disputam bloqueios em pais compartilhados (entidades, sequências, períodos) | Modo serial ou concorrência modesta para a contabilização; observe e depois escale |
| Esperar um "modo de carga de dados" que ignore as validações | Não existe — todos os 52 triggers empacotados são executados em cada linha do Bulk, sem sinalizador de bypass, deliberadamente | Prepare dados que passem nas regras; as regras são o produto |
| Carregar documentos históricos em períodos já fechados | Cada linha falha na validação de fechamento | Sequencie a migração: carregue e contabilize o histórico primeiro, defina as datas de fechamento por último |
| Tratar a paridade na contagem de linhas como sucesso | Todas as linhas entraram, mas os livros ainda estão errados — valores, moedas ou mapeamentos de contas contábeis podem estar sistematicamente incorretos | Concilie o balancete com o sistema de origem antes de considerar a tarefa concluída |
O que vem a seguir
- Saldos de Abertura e Migração de Dados — a metodologia.
- Contabilização em massa — o equivalente na UI da passagem de contabilização.
- REST API — a contraparte registro a registro.
Perguntas frequentes
O mesmo mecanismo por baixo — Data Loader para cargas ocasionais/manuais (o hábito do seu parceiro de implementação), Bulk 2.0 para pipelines programáticos. O comportamento dos triggers e o padrão acima são idênticos.
É uma divisão limpa, não uma quebra: os sucessos são documentos completos, as falhas simplesmente não aconteceram (atomicidade por registro). Corrija as causas no arquivo de erros e execute novamente apenas essas linhas — a idempotência baseada em Reference torna as reexecuções seguras.
Sim — os objetos de aplicação são carregados como qualquer registro, com todas as validações de correspondência aplicadas por linha. Carregue-os depois que os dois lados estiverem contabilizados, ou melhor: deixe a aplicação automática fazer a correspondência assim que os documentos estiverem no sistema.
Não há um limite rígido publicado — o custo da contabilização varia com o número de linhas por documento, a complexidade dos impostos e as dimensões. Comece de forma moderada (50–100 documentos por lote, em série), observe o tempo do job e quaisquer erros de bloqueio em um teste em sandbox no volume de produção, e escale a partir de evidências, não de otimismo.
As mesmas coisas que uma pessoa faria manualmente: o conjunto de permissões empacotado para os documentos sendo carregados, além de um assento de licença REDA — a verificação de licença se aplica às gravações via Bulk como a qualquer outra. Nada a mais, nada a menos.
Isso foi útil?