Esquemas

Esta página documenta los modelos de datos devueltos por la API de DocMap. Todas las respuestas usan JSON.

ExtractionRecord

Un registro de extracción representa una extracción de documento individual -- el resultado de procesar un PDF contra una plantilla.

typescript

interface ExtractionRecord {
  id: string              // Unique extraction ID
  userId: string          // Owner user ID
  templateId: string      // Template used for extraction
  templateName: string    // Human-readable template name
  fileName: string        // Original uploaded file name
  status: 'processing' | 'completed' | 'failed'
  extractedData: Record<string, unknown> | null  // Structured data or null if failed
  error: string | null    // Error message if failed, null if successful
  variables: Variable[]   // Template variable definitions used
  source: 'dashboard' | 'api'  // How the extraction was initiated
  runId: string | null    // Batch run ID, null if not part of a batch
  processingTimeMs: number | null  // Processing duration in milliseconds
  createdAt: string       // ISO 8601 timestamp
}

Descripciones de campos

Campo	Tipo	Descripción
`id`	`string`	Identificador único del registro de extracción.
`userId`	`string`	El ID del usuario propietario de esta extracción.
`templateId`	`string`	El ID de la plantilla que se usó para definir el esquema de extracción.
`templateName`	`string`	El nombre visible de la plantilla en el momento de la extracción.
`fileName`	`string`	El nombre original del archivo subido (por ejemplo, `"invoice-march.pdf"`).
`status`	`string`	`"processing"` mientras la extracción se ejecuta (modo asíncrono), `"completed"` si la extracción fue exitosa, o `"failed"` si no lo fue.
`extractedData`	`object \| null`	Los datos estructurados extraídos del documento, que coinciden con las definiciones de variables de la plantilla. `null` si la extracción falló.
`error`	`string \| null`	Una descripción de lo que salió mal. `null` si la extracción fue exitosa.
`variables`	`Variable[]`	Las definiciones de variables de la plantilla que se usaron para esta extracción. Ver Variable.
`source`	`string`	`"dashboard"` si la extracción se ejecutó desde la interfaz web, `"api"` si se ejecutó mediante la API.
`runId`	`string \| null`	Si la extracción fue parte de una ejecución por lotes, este es el ID compartido del lote. `null` para extracciones individuales.
`processingTimeMs`	`number \| null`	Cuánto tiempo tardó la extracción en milisegundos. `null` si no se registró.
`createdAt`	`string`	Marca de tiempo ISO 8601 de cuándo se creó la extracción.

Ejemplo

json

{
  "id": "ext_kp92mf7x",
  "userId": "u_abc123",
  "templateId": "tpl_inv001",
  "templateName": "Standard Invoice",
  "fileName": "acme-invoice-2024-003.pdf",
  "status": "completed",
  "extractedData": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-003",
    "invoice_date": "2024-11-15",
    "due_date": "2024-12-15",
    "total_amount": 4750.00,
    "currency": "USD",
    "line_items": [
      {
        "description": "Cloud Hosting - Pro Plan",
        "quantity": 1,
        "unit_price": 2500.00
      },
      {
        "description": "SSL Certificate (Wildcard)",
        "quantity": 3,
        "unit_price": 750.00
      }
    ]
  },
  "error": null,
  "variables": [
    { "key": "vendor_name", "type": "string", "context": "Name of the vendor or supplier", "required": true },
    { "key": "invoice_number", "type": "string", "context": "Invoice or reference number" },
    { "key": "invoice_date", "type": "date", "context": "Date the invoice was issued" },
    { "key": "due_date", "type": "date", "context": "Payment due date" },
    { "key": "total_amount", "type": "number", "context": "Total amount due" },
    { "key": "currency", "type": "string", "context": "Currency code (e.g. USD, EUR)" },
    {
      "key": "line_items",
      "type": "array",
      "context": "Individual line items on the invoice",
      "arrayType": "object",
      "fields": [
        { "key": "description", "type": "string", "context": "Item description" },
        { "key": "quantity", "type": "number", "context": "Quantity ordered" },
        { "key": "unit_price", "type": "number", "context": "Price per unit" }
      ]
    }
  ],
  "source": "api",
  "runId": null,
  "processingTimeMs": 3842,
  "createdAt": "2024-11-20T14:30:00.000Z"
}

ApiKeyPublic

La proyección pública de una clave API. El valor real de la clave y su hash nunca se devuelven después de la creación.

typescript

interface ApiKeyPublic {
  id: string              // Key ID
  userId: string          // Owner user ID
  name: string            // Label for the key
  prefix: string          // First 16 characters of the key (e.g., "dm_live_a1b2c3d4")
  expiresAt: string | null  // ISO 8601 expiration, null if never expires
  lastUsedAt: string | null // ISO 8601 last usage, null if never used
  createdAt: string       // ISO 8601 timestamp
  revoked: boolean        // Whether the key has been revoked
}

Descripciones de campos

Campo	Tipo	Descripción
`id`	`string`	Identificador único de la clave API.
`userId`	`string`	El ID del usuario propietario de esta clave.
`name`	`string`	Una etiqueta legible para la clave (por ejemplo, `"Production Server"`).
`prefix`	`string`	Los primeros 16 caracteres de la clave, útiles para identificar qué clave se está usando sin exponer el valor completo.
`expiresAt`	`string \| null`	Marca de tiempo ISO 8601 de cuándo expira la clave. `null` si la clave se creó sin expiración.
`lastUsedAt`	`string \| null`	Marca de tiempo ISO 8601 de la última vez que se usó la clave para autenticar una solicitud. `null` si nunca se ha usado.
`createdAt`	`string`	Marca de tiempo ISO 8601 de cuándo se creó la clave.
`revoked`	`boolean`	Si la clave ha sido revocada. En las respuestas de listado, las claves revocadas se filtran, por lo que esto es típicamente `false`.

Ejemplo

json

{
  "id": "key_m3x9kq72",
  "userId": "u_abc123",
  "name": "Production Server",
  "prefix": "dm_live_a1b2c3d4",
  "expiresAt": "2025-03-15T00:00:00.000Z",
  "lastUsedAt": "2025-01-10T09:22:14.000Z",
  "createdAt": "2024-12-15T10:00:00.000Z",
  "revoked": false
}

WebhookPublic

La proyección pública de un webhook. El secreto de firma nunca se devuelve después de la creación.

typescript

interface WebhookPublic {
  id: string              // Webhook ID
  userId: string          // Owner user ID
  url: string             // Registered endpoint URL
  events: WebhookEvent[]  // Subscribed events
  active: boolean         // Whether the webhook is active
  createdAt: string       // ISO 8601 timestamp
}

type WebhookEvent = 'extraction.completed' | 'extraction.failed'

Descripciones de campos

Campo	Tipo	Descripción
`id`	`string`	Identificador único del webhook.
`userId`	`string`	El ID del usuario propietario de este webhook.
`url`	`string`	El endpoint HTTPS que recibe las solicitudes POST del webhook.
`events`	`string[]`	Los eventos a los que este webhook está suscrito. Valores: `"extraction.completed"`, `"extraction.failed"`.
`active`	`boolean`	Si el webhook está activo. En las respuestas de listado, solo se devuelven webhooks activos, por lo que esto siempre es `true`.
`createdAt`	`string`	Marca de tiempo ISO 8601 de cuándo se creó el webhook.

Ejemplo

json

{
  "id": "webhook-abc123def456",
  "userId": "uid_a1b2c3d4e5f6",
  "url": "https://your-app.com/webhooks/docmap",
  "events": ["extraction.completed", "extraction.failed"],
  "active": true,
  "createdAt": "2025-01-15T10:00:00.000Z"
}

Variable

Una variable define un campo individual en una plantilla de extracción. Las variables le dicen a la IA qué datos buscar y en qué tipo devolverlos.

typescript

interface Variable {
  key: string              // Field name in extracted data
  type: 'string' | 'number' | 'date' | 'boolean' | 'object' | 'array'
  context: string          // Description/hint for the AI extractor
  required?: boolean       // Whether the field is required
  fields?: Variable[]      // Nested fields (for type: 'object')
  arrayType?: 'string' | 'number' | 'object'  // Item type (for type: 'array')
}

Descripciones de campos

Campo	Tipo	Descripción
`key`	`string`	El nombre del campo que aparecerá como clave en los datos extraídos. Debe tener al menos 1 carácter.
`type`	`string`	El tipo de dato esperado. Uno de: `string`, `number`, `date`, `boolean`, `object`, `array`.
`context`	`string`	Una descripción en lenguaje natural que ayuda a la IA a entender qué extraer para este campo. Un contexto más específico produce mejores resultados.
`required`	`boolean`	(Opcional) Si es `true`, la IA siempre intentará devolver un valor para este campo.
`fields`	`Variable[]`	(Opcional) Para `type: "object"`, define los campos anidados dentro del objeto. Esto es recursivo -- los objetos anidados pueden contener sus propios `fields`.
`arrayType`	`string`	(Opcional) Para `type: "array"`, especifica el tipo de elementos en el array. Uno de: `string`, `number`, `object`. Cuando `arrayType` es `"object"`, usa `fields` para definir la forma de cada elemento.

Estructura recursiva

Las variables admiten anidamiento arbitrario a través de la propiedad fields. Una variable object contiene variables hijas, y una variable array con arrayType: "object" también usa fields para describir cada elemento del array.

Esto te permite modelar estructuras de documentos complejas como facturas con partidas, contratos con múltiples partes, o cualquier dato jerárquico.

Ejemplo: Plantilla de factura con variables anidadas

json

[
  {
    "key": "vendor_name",
    "type": "string",
    "context": "Name of the vendor or supplier company",
    "required": true
  },
  {
    "key": "invoice_number",
    "type": "string",
    "context": "Invoice or reference number"
  },
  {
    "key": "invoice_date",
    "type": "date",
    "context": "Date the invoice was issued (YYYY-MM-DD)"
  },
  {
    "key": "total_amount",
    "type": "number",
    "context": "Total amount due including tax"
  },
  {
    "key": "billing_address",
    "type": "object",
    "context": "The billing address on the invoice",
    "fields": [
      { "key": "street", "type": "string", "context": "Street address" },
      { "key": "city", "type": "string", "context": "City name" },
      { "key": "state", "type": "string", "context": "State or province" },
      { "key": "zip", "type": "string", "context": "Postal or ZIP code" },
      { "key": "country", "type": "string", "context": "Country name or code" }
    ]
  },
  {
    "key": "line_items",
    "type": "array",
    "context": "Individual line items listed on the invoice",
    "arrayType": "object",
    "fields": [
      { "key": "description", "type": "string", "context": "Item description" },
      { "key": "quantity", "type": "number", "context": "Quantity ordered" },
      { "key": "unit_price", "type": "number", "context": "Price per unit" },
      { "key": "total", "type": "number", "context": "Line total (quantity x unit_price)" }
    ]
  },
  {
    "key": "tags",
    "type": "array",
    "context": "Keywords or categories that describe this invoice",
    "arrayType": "string"
  }
]

En este ejemplo:

billing_address es un object con cinco campos string anidados.
line_items es un array de objetos, cada uno con description, quantity, unit_price y total.
tags es un array simple de cadenas sin fields anidados.

UsageResponse

Devuelto por el endpoint GET /v1/usage. Muestra el plan actual del usuario autenticado y el uso de extracciones para el período de facturación.

typescript

interface UsageResponse {
  plan: 'free' | 'starter' | 'core' | 'pro'
  usage: number            // Extractions used this period
  limit: number            // Maximum for current plan
  periodKey: string        // Current period (e.g., "2025-01")
}

Descripciones de campos

Campo	Tipo	Descripción
`plan`	`string`	El plan actual del usuario. Uno de: `free`, `starter`, `core`, `pro`.
`usage`	`number`	El número de extracciones consumidas en el período de facturación actual.
`limit`	`number`	El número máximo de extracciones permitidas para el plan del usuario.
`periodKey`	`string`	El período de facturación actual en formato `YYYY-MM` (por ejemplo, `"2025-01"`).

Ejemplo

json

{
  "data": {
    "plan": "starter",
    "usage": 142,
    "limit": 500,
    "periodKey": "2025-01"
  }
}

TIP

El endpoint de uso devuelve los datos envueltos en un objeto data, como se muestra arriba.

ErrorResponse

Todos los errores de la API siguen una estructura consistente con un code legible por máquinas y un message legible por humanos.

typescript

interface ErrorResponse {
  error: {
    code: string           // Machine-readable error code
    message: string        // Human-readable description
  }
}

Ejemplo

json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Extraction not found"
  }
}

Consulta la referencia de Códigos de error para ver la lista completa de códigos de error, sus códigos de estado HTTP y los pasos de resolución.

Esquemas ​

ExtractionRecord ​

Descripciones de campos ​

Ejemplo ​

ApiKeyPublic ​

Descripciones de campos ​

Ejemplo ​

WebhookPublic ​

Descripciones de campos ​

Ejemplo ​

Variable ​

Descripciones de campos ​

Estructura recursiva ​

Ejemplo: Plantilla de factura con variables anidadas ​

UsageResponse ​

Descripciones de campos ​

Ejemplo ​

ErrorResponse ​

Ejemplo ​

Esquemas

ExtractionRecord

Descripciones de campos

Ejemplo

ApiKeyPublic

Descripciones de campos

Ejemplo

WebhookPublic

Descripciones de campos

Ejemplo

Variable

Descripciones de campos

Estructura recursiva

Ejemplo: Plantilla de factura con variables anidadas

UsageResponse

Descripciones de campos

Ejemplo

ErrorResponse

Ejemplo