Obter JSON com a IA: dados estruturados confiáveis

Você pede à IA que extraia as informações de uma fatura “em JSON”, e ela responde: “Claro! Aqui está o JSON solicitado”, seguido de um bloco de código e depois de uma nota que explica as escolhas dela. No dia seguinte, o campo valor se chama total, a data aparece por extenso e o preço vira "125,50 €", uma cadeia de caracteres. Para um humano, é legível. Para um script ou uma planilha, é uma pane.

JSON é um formato de texto que organiza dados em pares de nome e valor. Você não precisa saber programar para aproveitá-lo, e se o seu destino é uma planilha, o CSV será ainda mais simples. Nos dois casos, o princípio é o mesmo: você decide o formato de antemão, sem margem de interpretação.

Descrever o esquema em vez de dizer “em JSON”

A palavra “JSON” sozinha deixa o modelo livre para escolher a estrutura, os nomes e os tipos. É preciso dar a ele o molde completo. Pense num restaurateur que quer acompanhar as faturas dos fornecedores.

Antes:

Extraia as informações desta fatura em JSON.

Depois:

Extraia os dados da fatura abaixo. Responda apenas com um objeto JSON válido, sem texto antes nem depois e sem marcadores de código Markdown.

Respeite exatamente esta estrutura e estes nomes de campos:

{
  "fornecedor": "texto",
  "numero_fatura": "texto",
  "data": "AAAA-MM-DD",
  "total_sem_impostos": número,
  "total_com_impostos": número,
  "itens": [
    { "descricao": "texto", "quantidade": número, "preco_unitario_sem_impostos": número }
  ],
  "categoria": "bebidas" | "taxas" | "mercearia" | "outros"
}

Regras:
- Os números se escrevem com ponto decimal, sem símbolo de moeda.
- Se uma informação estiver ausente ou ilegível, coloque null. Nunca adivinhe nem a calcule.
- Não acrescente nenhum campo.

Fatura:
[TEXTO DA FATURA]

Quatro escolhas fazem a diferença. O esquema é mostrado por inteiro, então os nomes dos campos não mudam mais. A data tem um formato sem ambiguidade: 2026-03-04 não se confunde de um país para outro. A categoria é uma lista fechada, o que evita ter “Bebidas”, “bebida” e “Vinhos” no mesmo arquivo. Por fim, o null dá à IA uma saída honesta quando falta a informação.

Os campos ausentes, fonte da maioria dos erros

Quando um campo é obrigatório no seu esquema e a informação não está no documento, o modelo tende a produzir uma. Um número de inscrição fiscal pode aparecer onde não havia nenhum. O JSON será perfeitamente válido e falso.

Duas precauções ajudam. A primeira é a regra do null acima, para cada campo. A segunda é pedir a prova quando o que está em jogo justificar: acrescente um campo trecho_origem que copie a passagem de onde vem o valor. Você pode então comparar rapidamente numa amostra. Para a lógica geral, o artigo para reduzir as alucinações vai mais longe.

O caso mais comum: um CSV para o Excel

Se o seu destino é uma planilha, esqueça o JSON: peça diretamente um CSV. Uma dificuldade que vale conhecer: com as configurações regionais do Brasil, o Excel geralmente espera ponto e vírgula como separador e vírgula para os decimais. Um CSV com vírgulas pode, portanto, abrir com tudo numa única coluna.

Exemplo para uma tesoureira de associação que transforma inscrições recebidas por e-mail, aqui com dados fictícios:

Transforme as mensagens abaixo em uma tabela CSV, sem nenhum texto em volta e sem marcadores de código.

Parâmetros:
- separador: ponto e vírgula ;
- decimais: vírgula ;
- primeira linha, exatamente: nome;sobrenome;atividade;valor;forma_pagamento;a_verificar
- atividade: entre [LISTA DAS ATIVIDADES]
- forma_pagamento: cheque, transferencia, dinheiro ou vazio se não for informada.

Uma linha por pessoa inscrita. Se uma mensagem inscrever duas pessoas, faça duas linhas. Se uma informação estiver ausente ou ambígua, deixe a célula vazia e coloque “sim” em a_verificar.

Mensagens:
[COLE AS MENSAGENS]

Cole o resultado num arquivo .csv, ou na sua planilha usando a função de importação de texto. Atenção aos dados pessoais: antes de colar mensagens de pessoas reais, veja o que não se deve colocar em um chatbot e os termos do seu plano.

Validar o resultado, todas as vezes

Uma saída estruturada pode quebrar de três maneiras: o texto não é um JSON válido, a estrutura não corresponde ao esquema ou os valores estão errados. As duas primeiras se controlam automaticamente. Eis um script Python curto que para assim que aparece um problema:

import json

CAMPOS = {"fornecedor", "numero_fatura", "data", "total_sem_impostos",
          "total_com_impostos", "itens", "categoria"}
CATEGORIAS = {"bebidas", "taxas", "mercearia", "outros"}

def validar(resposta: str) -> dict:
    dados = json.loads(resposta)  # falha se não for JSON
    if set(dados) != CAMPOS:
        raise ValueError(f"Campos incorretos: {set(dados) ^ CAMPOS}")
    if dados["categoria"] not in CATEGORIAS:
        raise ValueError(f"Categoria desconhecida: {dados['categoria']}")
    com, sem = dados["total_com_impostos"], dados["total_sem_impostos"]
    if com is not None and sem is not None and com < sem:
        raise ValueError("Total com impostos inferior ao total sem impostos")
    return dados

O controle do total com impostos é uma questão de bom senso do negócio, e pega erros que nenhum esquema veria. Para os valores, preveja uma checagem por amostragem: compare dez documentos à mão antes de confiar no processamento e, depois, alguns de vez em quando.

Sem código, você pode pedir ao modelo que aponte as linhas suspeitas numa nova conversa, mas ele pode deixar passar algumas. Uma soma recalculada na planilha continua mais segura.

Passar para a API quando o volume sobe

Se você processa dezenas de documentos por meio de um programa, o prompt sozinho não é a melhor solução. As APIs dos principais fornecedores oferecem opções para restringir a saída a um esquema JSON. Os nomes e as garantias delas evoluem, então veja a documentação do seu fornecedor quando for começar. Essas opções garantem uma estrutura conforme, não valores certos: mantenha a regra do null e os controles de negócio.

Para um fluxo em várias etapas, uma saída JSON também serve de ponte entre dois modelos ou dois prompts, como numa cadeia de prompts.

Faça o teste com três documentos reais

Escolha três documentos do mesmo tipo, entre eles um mal feito: uma fatura escaneada, uma mensagem incompleta. Passe-os pelo prompt de sua escolha com um esquema de apenas cinco campos e depois compare cada valor com o original. O documento mal feito dirá quais regras acrescentar antes de ampliar o esquema.