Quickstart

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

Una cuenta en Matil — regístrate aquí
Una API key
Un deployment ID

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

Obtener tu API key

Abre el dashboard

Inicia sesión en el Dashboard de Matil y ve a Settings > API Keys.

Crea una nueva clave

Haz clic en Create New Key. Dale un nombre descriptivo (por ejemplo, “Desarrollo” o “Producción”).

Copia la clave

Copia tu API key inmediatamente — no se mostrará de nuevo.

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.

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

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.

Hacer tu primera petición

Envía un documento a tu deployment:

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"
      }
    ]
  }'

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']}")

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);

Entender la respuesta

Una respuesta exitosa se ve así:

{
  "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

Deployments

Entiende cómo los deployments conectan estructuras con llamadas API.

Formatos de documento

Conoce todas las formas de enviar documentos a Matil.

Modos de procesamiento

Procesamiento síncrono, asíncrono y por lotes.

Manejo de errores

Gestiona los errores correctamente en tu integración.

Primeros pasos

Conceptos

Qué necesitas

Obtener tu API key

Encontrar tu deployment ID

Hacer tu primera petición

Entender la respuesta

Siguientes pasos

Deployments

Formatos de documento

Modos de procesamiento

Manejo de errores

​Qué necesitas

​Obtener tu API key

​Encontrar tu deployment ID

​Hacer tu primera petición

​Entender la respuesta

​Siguientes pasos

Deployments

Formatos de documento

Modos de procesamiento

Manejo de errores

Qué necesitas

Obtener tu API key

Encontrar tu deployment ID

Hacer tu primera petición

Entender la respuesta

Siguientes pasos