Entrada de documentos

Cada petición de procesamiento incluye un array documents. Cada documento debe tener un campo type que determina cómo Matil recibe el contenido.

URL

Envía un enlace de descarga directa. Matil descarga el archivo y lo procesa.

{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/factura.pdf"
    }
  ]
}

La URL debe apuntar directamente al archivo. Los enlaces que requieren autenticación, redirigen a una página de login, o devuelven HTML en lugar del archivo fallarán con un error 400. Para servicios como Google Drive o Dropbox, usa la URL de descarga directa, no el enlace para compartir.

Base64

Envía el contenido del archivo codificado en base64. Incluye siempre mime_type para que Matil sepa cómo procesar el archivo.

{
  "documents": [
    {
      "type": "base64",
      "content": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw...",
      "mime_type": "application/pdf",
      "filename": "factura.pdf"
    }
  ]
}

Campo	Requerido	Descripción
`content`	Sí	El contenido del archivo codificado en base64.
`mime_type`	No	Tipo MIME del archivo (ej. `application/pdf`, `image/png`). Muy recomendado.
`filename`	No	Nombre original del archivo. Ayuda a Matil a detectar el tipo cuando no se proporciona `mime_type`.

Envía solo la cadena base64 sin prefijos. No incluyas el prefijo data:application/pdf;base64, — ese es un formato Data URI usado en navegadores, no en peticiones a la API.

Codificar un archivo a base64

import base64

with open("factura.pdf", "rb") as f:
    content = base64.b64encode(f.read()).decode("utf-8")

# Usar en tu petición
document = {
    "type": "base64",
    "content": content,
    "mime_type": "application/pdf",
    "filename": "factura.pdf"
}

import fs from "fs";

const content = fs.readFileSync("factura.pdf").toString("base64");

// Usar en tu petición
const document = {
  type: "base64",
  content: content,
  mime_type: "application/pdf",
  filename: "factura.pdf"
};

# Codificar y enviar en un solo comando
curl -X POST "https://api.matil.ai/v3/deployments/{deployment_id}" \
  -H "x-api-key: tu-api-key" \
  -H "Content-Type: application/json" \
  -d "{
    \"documents\": [{
      \"type\": \"base64\",
      \"content\": \"$(base64 -i factura.pdf)\",
      \"mime_type\": \"application/pdf\",
      \"filename\": \"factura.pdf\"
    }]
  }"

byte[] bytes = File.ReadAllBytes("factura.pdf");
string content = Convert.ToBase64String(bytes);

var document = new {
    type = "base64",
    content = content,
    mime_type = "application/pdf",
    filename = "factura.pdf"
};

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

byte[] bytes = Files.readAllBytes(Path.of("factura.pdf"));
String content = Base64.getEncoder().encodeToString(bytes);

Texto

Envía texto plano directamente. Es útil para pasar instrucciones adicionales o contexto junto con otros documentos, o para procesar texto que ya tienes extraído.

{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/factura.pdf"
    },
    {
      "type": "text",
      "text": "La moneda de la factura es USD. El NIF del proveedor es ES12345678A."
    }
  ]
}

En este ejemplo, el primer documento es el archivo real y el segundo proporciona contexto adicional que ayuda a Matil a extraer los datos con más precisión.

Múltiples documentos

Puedes enviar varios documentos en una sola petición. Matil los procesa juntos como una unidad.

{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/factura-pagina1.pdf"
    },
    {
      "type": "url",
      "url": "https://example.com/factura-pagina2.pdf"
    }
  ]
}

Metadata por documento

Cada documento acepta un objeto metadata opcional para tu propio seguimiento:

{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/factura.pdf",
      "metadata": {"source": "email", "sender": "proveedor@example.com"}
    }
  ]
}

API Reference

Endpoints

URL

Base64

Codificar un archivo a base64

Texto

Múltiples documentos

Metadata por documento

​URL

​Base64

​Codificar un archivo a base64

​Texto

​Múltiples documentos

​Metadata por documento

URL

Base64

Codificar un archivo a base64

Texto

Múltiples documentos

Metadata por documento