Claix

1. Autenticação

Toda solicitaçã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 um deles é suficiente. Se você enviar ambos, 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 solicitação é rejeitada com 401 sem processar o arquivo.

2. Formato da solicitaçã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 esquema excel-json criado na sua conta.

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

Os nomes dos campos devem ser exatamente file e schema_id. O esquema 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 solicitação

1. Tenha sua chave de API e o schema_id correto prontos.
2. Construa uma solicitaçã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 solicitaçã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" } ] }

Campo	Tipo	Descrição
success	booleano	Sempre verdadeiro quando HTTP é 200.
schema_utilizado	string	Nome do esquema aplicado (não o id).
total_filas_procesadas	número	Linhas transformadas em dados (linhas vazias não contadas).
mapa_columnas	objeto	Mapeamento da coluna original → propriedade do esquema.
data	array	Registros com chaves correspondentes às propriedades do esquema.

6. Códigos de erro

{ "error": "Descripción legible del problema.", "detalle": "Información técnica adicional (solo presente en algunos casos)." }

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

401 — Falha na 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 esquema.

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

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

7. Resumo dos códigos

Código	Categoria	Tentar novamente?
200	Sucesso	—
400	Erro do cliente (dados malformados)	Não — corrija a solicitação primeiro
401	Erro de autenticação	Não — corrija as credenciais primeiro
404	Recurso não encontrado	Não — corrija o schema_id primeiro
405	Método HTTP incorreto	Não — corrija o método primeiro
422	Nenhuma correspondência encontrada	Não — revise dados/esquema primeiro
500	Erro interno do servidor	Sim, com cautela
502	Falha no serviço de IA	Sim, recomendado com backoff

8. Boas práticas

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

Exemplos de solicitação

cURLJavaScriptNode.jsPythonPHPn8n

Copiar

curl -X POST "https://www.claix.dev/api/excel-json"
-H "x-api-key: <TU_API_KEY>"
-F "file=@./leads_octubre.xlsx"
-F "schema_id=8f14e45f-ceea-4e6f-8b23-1e2d3c4b5a6f"