Límites de uso y tarifas

Límites mensuales de extracciones

Cada plan incluye un número fijo de extracciones por mes calendario. El uso se reinicia el primer día de cada mes (UTC).

Plan	Extracciones mensuales	Precio
Free	25	$0
Starter	350	-
Core	2,500	-
Pro	10,000	-

TIP

Consulta docmap.io/#pricing para ver los precios actuales de los planes y la comparación de características.

Consultar tu uso

Consulta el endpoint /v1/usage para ver tu plan actual, el conteo de uso y el límite para el período de facturación activo:

curl

curl https://api.docmap.io/v1/usage \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const response = await fetch("https://api.docmap.io/v1/usage", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await response.json();

console.log(`Plan: ${data.plan}`);
console.log(`Usage: ${data.usage} / ${data.limit}`);
console.log(`Period: ${data.periodKey}`);

Python

import requests

response = requests.get(
    "https://api.docmap.io/v1/usage",
    headers={"Authorization": f"Bearer {api_key}"},
)

data = response.json()["data"]

print(f"Plan: {data['plan']}")
print(f"Usage: {data['usage']} / {data['limit']}")
print(f"Period: {data['periodKey']}")

Respuesta de ejemplo:

{
  "data": {
    "plan": "core",
    "usage": 1847,
    "limit": 2500,
    "periodKey": "2025-07"
  }
}

Campo	Descripción
plan	Tu plan actual: free, starter, core o pro
usage	Número de extracciones usadas en el período de facturación actual
limit	Máximo de extracciones permitidas para tu plan
periodKey	Período de facturación actual en formato YYYY-MM

Manejar el límite excedido

Cuando se alcanza tu límite mensual, cualquier llamada a POST /v1/extractions/run devuelve un estado 429 con el código de error USAGE_LIMIT_EXCEEDED:

{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Monthly extraction limit reached (25/25). Upgrade your plan for more extractions."
  }
}

Tienes dos opciones:

1. Mejorar tu plan. Ve a Configuración > Facturación en el panel de control de DocMap. Tu nuevo límite se aplica inmediatamente.
2. Esperar al próximo período de facturación. El uso se reinicia automáticamente el primero de cada mes (UTC).

WARNING

No reintentes errores 429 USAGE_LIMIT_EXCEEDED. A diferencia de los errores del servidor, estos no se resolverán por sí solos. Verifica el endpoint /v1/usage para ver tu conteo y límite actual antes de realizar solicitudes por lotes.

Aquí se muestra cómo manejar esto de forma elegante en tu código:

async function runExtraction(templateId: string, fileName: string, pdfBase64: string) {
  const response = await fetch("https://api.docmap.io/v1/extractions/run", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ templateId, fileName, pdfBase64, mimeType: "application/pdf" }),
  });

  if (response.status === 429) {
    const { error } = await response.json();
    if (error.code === "USAGE_LIMIT_EXCEEDED") {
      console.error("Monthly extraction limit reached. Upgrade your plan or wait until next month.");
      // Optionally check current usage
      const usageResponse = await fetch("https://api.docmap.io/v1/usage", {
        headers: { Authorization: `Bearer ${apiKey}` },
      });
      const { data: usage } = await usageResponse.json();
      console.log(`Current usage: ${usage.usage}/${usage.limit} (${usage.plan} plan)`);
      return null;
    }
  }

  const { data } = await response.json();
  return data;
}

Avisos de uso

DocMap envía automáticamente una notificación por correo electrónico cuando tu uso alcanza el 80% de tu límite mensual. Esto te da tiempo para mejorar tu plan antes de que las extracciones se detengan.

• El aviso se envía una vez por período de facturación -- no recibirás correos repetidos
• El correo incluye tu conteo de uso actual, el límite y un enlace directo para mejorar tu plan
• Solo el propietario de la cuenta recibe los correos de aviso de uso

TIP

Monitorea tu uso de forma programática llamando a GET /v1/usage antes de iniciar operaciones por lotes grandes. Esto te permite verificar si tienes suficiente capacidad restante.

Límites de tasa de solicitudes

Además de los límites mensuales de extracciones, las tasas excesivas de solicitudes pueden ser limitadas para proteger la estabilidad del servicio. Para evitar la limitación:

• Añade retardos entre solicitudes por lotes. Cuando proceses muchos archivos, añade un pequeño retardo (por ejemplo, 200--500ms) entre llamadas consecutivas a la API en lugar de enviarlas todas simultáneamente.
• Usa límites de concurrencia. Si procesas archivos en paralelo, limita la concurrencia a 5--10 solicitudes simultáneas.
• Monitorea los tiempos de respuesta. Si los tiempos de respuesta aumentan significativamente, reduce tu tasa de solicitudes.

// Process files with controlled concurrency
async function processFilesWithLimit(files: string[], concurrency = 5) {
  const results = [];

  for (let i = 0; i < files.length; i += concurrency) {
    const batch = files.slice(i, i + concurrency);

    const batchResults = await Promise.all(
      batch.map((file) => runExtraction("tmpl_abc123", file, encode(file)))
    );

    results.push(...batchResults);

    // Brief pause between batches
    if (i + concurrency < files.length) {
      await new Promise((resolve) => setTimeout(resolve, 500));
    }
  }

  return results;
}