Skip to main content

​
Endpoints para baixar falhas

Alias legacy CSV entidades: GET /entities/automatic/bulk/imports/{jobId}/failures.csv.
  • …/failures.csv → arquivo CSV para download (Content-Type: text/csv)
  • …/failures → JSON (Content-Type: application/json)

​
Modelo de três camadas

Cada falha por linha inclui code (máquina) e message (humano). Jobs legacy podem ter só error em texto livre; a API normaliza na leitura.

​
Três resultados possíveis por linha (entidades)

​
Duplicado por taxId

Bulk manual (default): duplicateTaxIdPolicy: skip_existing.
  • Mesmo taxId + mesmo type já existe → skipped_existing, código SKIPPED_DUPLICATE_TAX_ID
  • Não aparece em failures.csv
  • Contador: skippedExisting no histórico unificado
Bulk automático: entidade principal já existia → skipped_existing
  • refresh: false: SKIPPED_ENTITY_ALREADY_EXISTS — sem re-enriquecimento
  • refresh: true: SKIPPED_ENTITY_ALREADY_EXISTS_REFRESHED — criação omitida, re-enriquecimento executado
Quando é falha (failed):

​
Códigos de falha por linha (failures[] / failures.csv)

​
Ids arredondados por planilha

Abrir um CSV no Excel ou no Google Sheets faz com que ids numéricos longos (CPF, CNPJ, números de conta) sejam lidos como números e reexportados arredondados: 50400000000000 vira 5,04E+13. Sobrevivem apenas três dígitos significativos, então o id original não pode ser recuperado do valor. As linhas do batch de transações são rejeitadas com SCIENTIFIC_NOTATION_ID quando algum de externalId, originExternalId, destinationExternalId, originTaxId ou destinationTaxId corresponde a esse padrão. A message da falha nomeia os campos afetados, e identifier_type no failures.csv os lista. Para evitar, exporte o CSV mantendo as colunas de id como texto (no Sheets: Arquivo → Fazer download → CSV sem abrir as colunas como números; no Excel: defina o formato Texto na coluna antes de importar, ou use Dados → De Texto/CSV marcando as colunas de id como Texto).

​
Códigos de skip (skips[] — só entidades, não é falha)

Matriz de risco / regras de negócio: a execução de regras ocorre depois de criar a linha. Resultados de regras não aparecem em failures.csv / JSON failures[] e não revertem a linha. Use alertas, score de risco e timelines de auditoria.

​
Códigos de job completo (jobFailure)

​
Matriz de cenários (FAQ cliente)

​
Cenários reproduzíveis (testes)

User events: CSV válido + mapping; uma linha com campo obrigatório vazio → GET …/user-event-jobs/{jobId}/failures. Entidades (manual): criar entidade com external_id=X, importar outra linha com mesmo external_id → DUPLICATE_EXTERNAL_ID. Transações (job-level abort): validateExistingEntity=true + batchErrorHandling=rollback_all + originExternalId=DOES_NOT_EXIST → job failed, jobFailure.code=INVALID_ENTITY_REFERENCES, detalhe em failures.csv. Transações (row-level skip): batchErrorHandling=continue_collect_errors + refs inválidas misturadas com válidas → linhas válidas criadas; inválidas como ENTITY_NOT_FOUND no endpoint de falhas. Transações (row-level insert): batchErrorHandling=continue_collect_errors + linhas válidas misturadas com violações de constraint → entradas no endpoint de falhas.

​
Limites

  • O sample JSON de falhas por linha é limitado a 500 (truncated + failuresTotal), hidratado a partir de failures.csv no S3 quando existir (jobs legacy podem cair para DB). O download CSV é a lista completa.
Relatório completo por email (entidades): todas as linhas (created, skipped_existing, failed) com coluna code. Ver também: Importações em lote — overview.