> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matil.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Entrada de documentos

> Cómo formatear documentos en tus peticiones a la API.

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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/factura.pdf"
    }
  ]
}
```

<Warning>
  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.
</Warning>

## Base64

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`. |

<Warning>
  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.
</Warning>

### Codificar un archivo a base64

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
  }
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
  };
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # 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\"
      }]
    }"
  ```

  ```csharp C# theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
  };
  ```

  ```java Java theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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);
  ```
</CodeGroup>

## 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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/factura.pdf",
      "metadata": {"source": "email", "sender": "proveedor@example.com"}
    }
  ]
}
```