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

# Quickstart

> Haz tu primera llamada a la API de Matil en menos de 5 minutos.

Esta guia te lleva paso a paso para hacer tu primera petición de procesamiento de documentos. Al final, habrás enviado un documento y recibido datos estructurados.

## Qué necesitas

1. Una cuenta en Matil — [regístrate aquí](https://admin.matil.ai)
2. Una API key
3. Un deployment ID

Aun no los tienes? Sigue los pasos a continuación.

## Obtener tu API key

<Steps>
  <Step title="Abre el dashboard">
    Inicia sesión en el [Dashboard de Matil](https://admin.matil.ai) y ve a **Settings > API Keys**.
  </Step>

  <Step title="Crea una nueva clave">
    Haz clic en **Create New Key**. Dale un nombre descriptivo (por ejemplo, "Desarrollo" o "Producción").
  </Step>

  <Step title="Copia la clave">
    Copia tu API key inmediatamente — no se mostrará de nuevo.
  </Step>
</Steps>

<Note>
  Guarda tu API key en una varíable de entorno. Nunca la escribas directamente en tu código fuente ni la subas a control de versiones.
</Note>

## Encontrar tu deployment ID

Ve a **Deployments** en el dashboard. Selecciona el deployment que quieras usar y copia su ID.

Un deployment ID es un UUID como: `01234567-89ab-cdef-0123-456789abcdef`

<Tip>
  Si aún no tienes un deployment, créalo primero en el dashboard. Un deployment define que datos quieres extraer y de qué tipo de documento.
</Tip>

## Hacer tu primera petición

Envía un documento a tu deployment:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.matil.ai/v3/deployments/{tu-deployment-id}" \
    -H "x-api-key: tu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "documents": [
        {
          "type": "url",
          "url": "https://ejemplo.com/factura.pdf"
        }
      ]
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  API_KEY = "tu-api-key"
  DEPLOYMENT_ID = "tu-deployment-id"

  response = requests.post(
      f"https://api.matil.ai/v3/deployments/{DEPLOYMENT_ID}",
      headers={
          "x-api-key": API_KEY,
          "Content-Type": "application/json"
      },
      json={
          "documents": [
              {
                  "type": "url",
                  "url": "https://ejemplo.com/factura.pdf"
              }
          ]
      }
  )

  result = response.json()
  print(f"Entry ID: {result['entry_id']}")
  print(f"Status: {result['status']}")
  print(f"Datos extraídos: {result['data']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const API_KEY = "tu-api-key";
  const DEPLOYMENT_ID = "tu-deployment-id";

  const response = await fetch(
    `https://api.matil.ai/v3/deployments/${DEPLOYMENT_ID}`,
    {
      method: "POST",
      headers: {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        documents: [
          {
            type: "url",
            url: "https://ejemplo.com/factura.pdf"
          }
        ]
      })
    }
  );

  const result = await response.json();
  console.log("Entry ID:", result.entry_id);
  console.log("Status:", result.status);
  console.log("Datos extraídos:", result.data);
  ```
</CodeGroup>

## Entender la respuesta

Una respuesta exitosa se ve así:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "entry_id": "01934b1a-89ab-7def-0123-456789abcdef",
  "resource_type": "structure",
  "resource_id": "01934b1a-1234-7abc-0000-111122223333",
  "resource_version_number": 1,
  "data": {
    "numero_factura": "FAC-2024-001",
    "fecha": "2024-01-15",
    "total": 150.00
  },
  "errors": null,
  "status": "completed",
  "time_ms": 2340,
  "price": 0.05
}
```

| Campo                     | Descripción                                                             |
| ------------------------- | ----------------------------------------------------------------------- |
| `entry_id`                | ID único de este resultado. Úsalo para consultar o corregir la entrada. |
| `resource_type`           | Siempre `"structure"`.                                                  |
| `resource_id`             | La estructura utilizada para la extracción.                             |
| `resource_version_number` | La versión de la estructura aplicada.                                   |
| `data`                    | Los datos extraídos, estructurados como JSON.                           |
| `errors`                  | Errores de validación, si los hay. `null` cuando todo es correcto.      |
| `status`                  | `completed`, `completed_with_errors` o `failed`.                        |
| `time_ms`                 | Tiempo de procesamiento en milisegundos.                                |
| `price`                   | Coste de esta petición.                                                 |

## Siguientes pasos

<CardGroup cols={2}>
  <Card title="Deployments" href="/es/guides/deployments">
    Entiende cómo los deployments conectan estructuras con llamadas API.
  </Card>

  <Card title="Formatos de documento" href="/es/guides/documents">
    Conoce todas las formas de enviar documentos a Matil.
  </Card>

  <Card title="Modos de procesamiento" href="/es/api-reference/processing">
    Procesamiento síncrono, asíncrono y por lotes.
  </Card>

  <Card title="Manejo de errores" href="/es/api-reference/error-handling">
    Gestiona los errores correctamente en tu integración.
  </Card>
</CardGroup>