Primeros pasos

Esta guía te acompaña en la configuración de tu entorno y la realización de tu primera solicitud de extracción con la API de DocMap.

Requisitos previos

Antes de comenzar, asegúrate de tener:

1. Una cuenta de DocMap -- Regístrate en docmap.io si aún no lo has hecho.
2. Al menos una plantilla de extracción -- Crea una plantilla en el Panel de control que defina los campos que deseas extraer de tus documentos.

TIP

Las plantillas definen la estructura de los datos que deseas extraer. Por ejemplo, una plantilla de factura podría incluir campos como vendor_name, invoice_number, total_amount y un array line_items. Puedes crear y gestionar plantillas desde el panel de control antes de realizar cualquier llamada a la API.

URL base

Todas las solicitudes a la API se realizan a:

https://api.docmap.io

Todos los endpoints están prefijados con /v1/. Por ejemplo, el endpoint de extracciones es:

https://api.docmap.io/v1/extractions/run

Crear una clave API

1. Ve a Panel de control > Configuración > Claves API.
2. Haz clic en Crear clave API.
3. Dale a tu clave un nombre descriptivo (por ejemplo, "Servidor de producción" o "Desarrollo local").
4. Elige un período de expiración.
5. Copia la clave inmediatamente -- solo se muestra una vez y no se puede recuperar después.

WARNING

Almacena tu clave API de forma segura. Solo se mostrará una vez en el momento de la creación. Si la pierdes, necesitarás crear una nueva.

Tu clave API tendrá el formato dm_live_... y se usa en el encabezado Authorization de cada solicitud.

Tu primera solicitud

Verifica tu configuración comprobando el endpoint de salud de la API:

curl

curl https://api.docmap.io/health

TypeScript

const res = await fetch('https://api.docmap.io/health')
const data = await res.json()
console.log(data) // { status: "ok" }

Python

import requests
res = requests.get('https://api.docmap.io/health')
print(res.json())  # {"status": "ok"}

Si todo funciona correctamente, recibirás:

{ "status": "ok" }

Ejecuta tu primera extracción

Con tu clave API y una plantilla lista, puedes extraer datos estructurados de un PDF. Codifica tu archivo PDF como una cadena base64 y envíalo al endpoint /v1/extractions/run.

curl

curl -X POST https://api.docmap.io/v1/extractions/run \
  -H "Authorization: Bearer dm_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "your-template-id",
    "fileName": "invoice.pdf",
    "pdfBase64": "JVBERi0xLjQ...",
    "mimeType": "application/pdf"
  }'

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

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: 'your-template-id',
    fileName: 'invoice.pdf',
    pdfBase64: 'JVBERi0xLjQ...', // base64-encoded PDF
    mimeType: 'application/pdf',
  }),
})

const data = await response.json()
console.log(data)

Python

import requests
import base64

api_key = "dm_live_your_api_key"

# Read and encode the PDF
with open("invoice.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.docmap.io/v1/extractions/run",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "templateId": "your-template-id",
        "fileName": "invoice.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

print(response.json())

Respuesta de ejemplo

Una extracción exitosa devuelve los datos extraídos que coinciden con los campos de tu plantilla:

{
  "id": "ext_abc123",
  "templateId": "your-template-id",
  "fileName": "invoice.pdf",
  "status": "completed",
  "data": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-001",
    "invoice_date": "2024-11-15",
    "total_amount": 1250.00,
    "currency": "USD",
    "line_items": [
      {
        "description": "Widget A",
        "quantity": 10,
        "unit_price": 125.00
      }
    ]
  },
  "createdAt": "2024-11-20T14:30:00.000Z"
}

Consulta tu uso

Monitorea tu uso de la API para mantenerte dentro de los límites de tu plan:

curl

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

TypeScript

const res = await fetch('https://api.docmap.io/v1/usage', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})
const usage = await res.json()
console.log(usage)

Python

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

Próximos pasos

Ahora que has realizado tu primera extracción, explora el resto de la documentación:

• Autenticación -- Aprende sobre claves API y mejores prácticas de seguridad.
• Referencia de la API -- Referencia completa de todos los endpoints disponibles.