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