Formato dos arquivos do lote

Esta página descreve o arquivo que você programa contra ao automatizar o enriquecimento em lote: o que o painel gera como modelo, e o formato exato do arquivo de resultado. Quem sobe e baixa pelo painel não precisa saber disso — é para quem monta a planilha ou lê o resultado por código.

Arquivo de entrada (modelo)

O painel gera o modelo depois que você escolhe as consultas: um CSV com separador ;, codificação UTF-8 com BOM e quebra de linha CRLF — o formato que o Excel em português abre certo, sem pedir conversão. O arquivo já vem com as colunas que as consultas escolhidas pedem e uma ou duas linhas de exemplo preenchidas (duas quando alguma coluna aceita "uma ou outra", para mostrar os dois caminhos).

Documentos (CPF, CNPJ) são tratados como texto, nunca como número. Se o Excel remover o zero à esquerda ao salvar (01234567890 virando 1234567890), a prévia do lote detecta isso e completa o zero de volta antes de consultar — nenhuma linha é perdida por causa disso. Ao abrir o arquivo de resultado depois, formate a coluna do documento como texto para não perder o zero de novo na próxima edição.

Quando os produtos escolhidos pedem CPF e CNPJ, os dois documentos de uma mesma entidade vão na mesma linha — nunca em linhas separadas.

Arquivo de resultado

O nome do arquivo segue o padrão lote-<nome>-<id>-completo.csv quando o lote terminou, ou lote-<nome>-<id>-parcial.csv quando ainda está em andamento — dá para baixar o resultado parcial antes do lote terminar; a linha que ainda não rodou sai marcada como pendente.

O dialeto é o mesmo do modelo (;, UTF-8 com BOM, CRLF). O cabeçalho segue esta forma:

<colunas originais da planilha> ; _consulta ; produto._status ; produto._documento ; produto.campo… ; produto.objeto_campo… ; produto.lista_N… ; produto._dados

• Colunas originais da planilha voltam como foram enviadas, exceto a coluna do documento, que volta normalizada (com o zero à esquerda reposto, se for o caso). A ordem é alfabética.

• _consulta: vazia na linha principal. Numa linha que gera mais de uma consulta — por exemplo, um produto que aceita CPF ou CNPJ e a linha tem os dois — a consulta extra sai numa linha adicional, e é essa linha extra que traz o nome do produto em _consulta.

• produto._status: só existe em produtos que fazem consulta (não em colunas de metadado). O vocabulário é fechado:

  Valor	Significado
  ok	A consulta rodou e trouxe resposta.
  negativo	A consulta rodou e não há nada a constar — resultado autoritativo, cobrado normalmente.
  not_found	O documento consultado não tem registro na base da consulta.
  erro	Falha técnica ao consultar essa linha — não é cobrada.
  pendente	A linha ainda não foi processada (arquivo parcial).
  pulado	A linha foi deliberadamente pulada.

  Célula vazia é diferente de todos esses valores: significa que o produto não se aplica àquela linha (ela não tinha o documento que o produto pede) — nada foi consultado, e nada foi cobrado.

• produto._documento: presente só nos produtos que aceitam CPF ou CNPJ. Diz qual dos dois documentos aquela consulta usou.

• produto.campo: uma coluna por campo simples de topo da resposta do produto, com o mesmo nome usado na documentação daquele produto.

• produto.objeto_campo: campos simples de um objeto de topo da resposta saem achatados assim — por exemplo, score-credito-quod.pessoaFisica_score.

• produto.lista_1 … produto.lista_N: os N primeiros itens de uma lista da resposta, um por coluna — por exemplo, cadastro-pf-basica.telefones_1, cadastro-pf-basica.telefones_2. Itens além de N não têm coluna própria; eles continuam disponíveis em _dados.

• produto._dados: um JSON compacto com a resposta inteira do produto — a fonte íntegra, inclusive o que já apareceu em colunas. Se esse JSON passar de 32.000 caracteres, a célula vira {"__truncado":true,"parcial":"…"} em vez do JSON completo.

Toda coluna de controle começa com _ (_consulta, _status, _documento, _dados); nenhum campo de produto começa com _, então não há ambiguidade entre os dois.

Formato dos valores

• Booleanos saem como true ou false.
• Números usam ponto como separador decimal.
• Célula vazia é nulo — não há um texto especial para "sem valor".
• Uma célula de resultado cujo conteúdo comece com = ou @ recebe um ' na frente (proteção contra fórmula ao abrir no Excel).

Reenviando o resultado como nova planilha

O arquivo de resultado pode ser reenviado como uma nova planilha de entrada, com o mesmo dialeto. Uma ressalva: as linhas extras (as que vieram de um produto que gerou mais de uma consulta na mesma linha original) repetem o CPF e o CNPJ — reenviar o arquivo sem filtrar essas linhas soma essas repetições de novo no próximo lote.

Compatibilidade

Colunas novas só são acrescentadas antes de _dados, nunca no meio das existentes. Leia o arquivo pelo nome da coluna, nunca pela posição — é o que garante que um lote programado hoje continue funcionando quando um produto ganhar um campo novo.