Claix

Conversão de Excel / CSV para JSON

Endpoint

POST https://claix.dev/api/excel-json

Este endpoint aceita um arquivo tabular (.xlsx ou .csv) e o retorna transformado em JSON com a estrutura exata que você define por meio de um schema. As colunas do arquivo não precisam corresponder literalmente aos nomes das propriedades do schema: o sistema reconhece automaticamente sinônimos, abreviações, traduções e variantes.

Ele é destinado a integrações servidor-para-servidor (backends, scripts, n8n/Zapier/Make). Não deve ser chamado a partir do navegador de um usuário final, pois requer uma chave de API secreta.

1. Autenticação

Cada requisição deve incluir sua chave de API. Ela é uma credencial pessoal do servidor, distinta de qualquer token de sessão, e deve ser tratada com o mesmo cuidado que uma senha de banco de dados.

Opção A — Cabeçalho dedicado (recomendado):

x-api-key: <YOUR_API_KEY>

Opção B — Cabeçalho de Autorização padrão:

Authorization: Bearer <YOUR_API_KEY>

Qualquer uma das opções é suficiente. Se você enviar ambas, x-api-key tem prioridade.

Antes de processar o arquivo, o sistema valida que:

• A chave de API existe e está ativa.
• A conta associada está ativa (não suspensa).

Se a validação falhar, a requisição é rejeitada com 401 sem processar o arquivo.

2. Formato da requisição

Campo	Tipo	Obrigatório	Descrição
file	Arquivo binário	Sim	Excel (.xlsx) ou CSV (.csv). Deve ser o próprio arquivo, não um caminho ou URL.
schema_id	Texto (UUID)	Sim	Identificador do schema excel-json criado na sua conta.
space_id	Texto (UUID)	Não	Opcional. Espaço de conhecimento ao qual o documento armazenado está vinculado. Deve pertencer à mesma conta que a chave de API. Só tem efeito quando o schema tem a janela de contexto habilitada, que é quando o documento é armazenado. Você pode então consultar todo o espaço com POST /space-context/{space_id}.

Método: POST · Content-Type: multipart/form-data

Os nomes dos campos devem ser exatamente file e schema_id. O schema deve ser do tipo Excel → JSON; se você enviar um do tipo oposto, receberá 400.

Requisitos do arquivo:

• Formatos: .xlsx, .csv.
• Pelo menos uma linha de cabeçalho e uma linha de dados.
• Se houver várias planilhas, apenas a primeira é processada.

3. Como construir a requisição

1. Tenha sua chave de API e o schema_id correto prontos.
2. Construa uma requisição POST para a URL do endpoint.
3. Adicione o cabeçalho de autenticação.
4. Envie multipart/form-data com file e schema_id.
5. Verifique o código de status HTTP: apenas 200 indica sucesso.

4. Exemplos de requisição

Veja o painel à direita para exemplos em cURL, JavaScript, Node.js, Python, PHP e n8n. Você pode alternar os idiomas com o seletor no topo e copiar o código diretamente.

5. Formato de resposta bem-sucedida

200 OK · Content-Type: application/json

{
  "success": true,
  "schema_utilizado": "Leads de Ventas",
  "total_filas_procesadas": 247,
  "mapa_columnas": {
    "Nom_cliente": "nombre_completo",
    "Tlf": "telefono_movil",
    "mail de contacto": "email_contacto"
  },
  "data": [
    {
      "nombre_completo": "Ana María Gómez",
      "cargo": "CEO & Founder",
      "empresa": "TechSolutions",
      "email_contacto": "ana.gomez@techsolutions.com",
      "telefono_movil": "+1 (555) 019-2231"
    }
  ],
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

Campo	Tipo	Descrição
success	booleano	Sempre true quando o HTTP é 200.
schema_utilizado	string	Nome do schema aplicado (não o id).
total_filas_procesadas	número	Linhas transformadas em data (linhas vazias não contadas).
mapa_columnas	objeto	Mapeamento de coluna original → propriedade do schema.
data	array	Registros com chaves correspondentes às propriedades do schema. Se a verificação de origem estiver habilitada no schema, cada propriedade é { value, source }.
log_id	string (UUID)	UUID da linha usage_logs desta chamada. Presente no sucesso e na maioria dos erros autenticados.

Toda resposta inclui log_id (o UUID da linha usage_logs) quando o log pôde ser armazenado. Ele também aparece na maioria dos erros após a requisição ser autenticada. Use-o para encontrar a chamada no painel de logs.

Se a verificação de origem estiver habilitada no schema, cada propriedade extraída (e cada campo agent_data no modo Agente) se torna { "value": ..., "source": "..." } em vez de um valor simples. source é obrigatório: ele cita a evidência (página, parágrafo, célula, trecho citado, região de imagem ou o segundo / intervalo de segundos em áudio). Se não houver evidência, source é exatamente requires_human_revision. Se a verificação de origem estiver desativada, o formato permanece inalterado.

Exemplo com verificação de origem habilitada:

{
  "success": true,
  "schema_utilizado": "Leads de Ventas",
  "total_filas_procesadas": 1,
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34",
  "mapa_columnas": {
    "Nom_cliente": "nombre_completo",
    "Tlf": "telefono_movil"
  },
  "data": [
    {
      "nombre_completo": {
        "value": "Ana María Gómez",
        "source": "columna \"Nom_cliente\", fila 2"
      },
      "telefono_movil": {
        "value": "+1 (555) 019-2231",
        "source": "columna \"Tlf\", fila 2"
      }
    }
  ]
}

6. Códigos de erro

{
  "error": "Descripción legible del problema.",
  "detalle": "Información técnica adicional (solo presente en algunos casos).",
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

400 — Requisição inválida: arquivo ou schema_id ausente, multipart incorreto, arquivo corrompido, sem linhas de dados ou schema do tipo errado.

401 — Falha de autenticação: chave ausente, inexistente, desativada ou conta suspensa.

404 — schema_id não existe ou não pertence à sua conta.

422 — Arquivo lido, mas sem correspondências com o schema.

502 — Falha no serviço de IA (transitória; tente novamente com backoff).

405 — Método diferente de POST. · 500 — Erro interno.

8. Boas práticas

• Valide o código de status HTTP antes de ler os dados.
• Apenas colunas com correspondência real no schema aparecem.
• Tente novamente automaticamente apenas em 500 e 502, nunca em 4xx, a menos que a requisição mude.
• Salve mapa_columnas para rastreabilidade durante os testes.
• Não inclua sua chave de API em código de frontend ou repositórios públicos.