> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Crear Lote
> Inicia un nuevo lote. Recibes un `id` que puedes usar para rastrear el progreso del lote como se muestra [aquí](/api-reference/batches/info). Nota: El tiempo de procesamiento es constante independientemente del tamaño del lote
**Recibe notificaciones al completar:** Pasa el parámetro `webhook` con la URL de tu endpoint para recibir un HTTP POST cuando el lote se complete. Consulta [Webhooks](/api-reference/common/webhooks) para más detalles.
**Adjunta datos personalizados:** Usa el parámetro `metadata` para almacenar pares clave-valor. Se admite en dos niveles:
* **Nivel de lote** — en el cuerpo de la solicitud
* **Nivel de elemento** — en cada elemento del array `items`
Consulta [Metadata](/api-reference/common/metadata) para más detalles.
## OpenAPI
````yaml es/openapi/batches.json POST /v1/batches
openapi: 3.0.3
info:
title: API de Lotes
version: 1.0.0
servers:
- url: https://api.olostep.com
security: []
paths:
/v1/batches:
post:
summary: Iniciar un nuevo lote
description: Inicia un nuevo proceso de lote con los parámetros especificados.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
custom_id:
type: string
description: Un identificador único interno para la url.
url:
type: string
format: uri
description: URL del elemento.
metadata:
allOf:
- $ref: '#/components/schemas/Metadata'
description: >-
Metadata a nivel de elemento. Adjunta pares
clave-valor a elementos individuales para seguimiento,
filtrado o correlación con tus sistemas internos.
required:
- custom_id
- url
description: Array de elementos a procesar en el lote.
country:
type: string
description: >-
País para la ejecución del lote. Proporciona en códigos ISO
3166-1 alfa-2 como US(USA), IN(India), etc.
parser:
type: object
properties:
id:
type: string
description: Parser a ser utilizado para el lote.
required:
- id
description: >-
Puedes usar este parámetro para especificar el parser a
utilizar. Los parsers son útiles para extraer contenido
estructurado de páginas web. Olostep tiene algunos parsers
integrados para las páginas web más comunes, y también
puedes crear tus propios parsers.
links_on_page:
type: object
properties:
include_links:
type: array
items:
type: string
description: >-
Filtra los enlaces extraídos usando patrones glob. Los
patrones coinciden con la ruta del URL del enlace. Nota:
un solo `*` no cruza `/`, así que "/blog/*" coincide con
"/blog/post-1" pero NO con el índice "/blog" en sí (o
"/blog?tag=x", ya que las cadenas de consulta no son
parte de la ruta). Para incluir también el índice, usa
"/blog*" o "{/blog,/blog/**}".
exclude_links:
type: array
items:
type: string
description: >-
Filtra los enlaces extraídos usando patrones glob. Los
patrones coinciden con la ruta del URL del enlace. Nota:
un solo `*` no cruza `/`, así que "/blog/*" coincide con
"/blog/post-1" pero NO con el índice "/blog" en sí.
description: >-
Obtén todos los enlaces presentes en cada página del lote.
Los enlaces siempre se devuelven como URLs absolutas.
metadata:
$ref: '#/components/schemas/Metadata'
webhook:
type: string
format: uri
description: >-
URL HTTPS para recibir una solicitud POST cuando el lote se
complete. Debe ser un URL públicamente accesible usando el
protocolo `http://` o `https://`. No puede apuntar a
localhost o direcciones IP privadas. Consulta
[Webhooks](/api-reference/common/webhooks) para el formato
de carga útil y el comportamiento de reintento.
required:
- items
example:
items:
- custom_id: product-123
url: https://example.com/product/123
metadata:
source: catalog_sync
priority: high
- custom_id: product-456
url: https://example.com/product/456
country: US
metadata:
batch_name: Q1 Product Sync
initiated_by: automation
responses:
'200':
description: Lote iniciado con éxito.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: ID del Lote
object:
type: string
description: El tipo de objeto. "batch" para este endpoint.
status:
type: string
description: '`in_progress` o `completed`'
created:
type: number
description: Época creada
total_urls:
type: number
description: Conteo de URLs en el lote
completed_urls:
type: number
description: Conteo de URLs completadas
parser:
type: string
country:
type: string
metadata:
$ref: '#/components/schemas/Metadata'
webhook:
type: string
description: >-
URL del webhook para recibir la notificación de
finalización
credits_consumed:
type: integer
nullable: true
description: >-
Número de créditos consumidos por esta solicitud. Se
completa después de que la ejecución finaliza. Los
créditos son la fuente de verdad para la facturación.
cost_usd:
type: number
nullable: true
description: >-
Costo estimado en USD para esta solicitud. Se completa
después de que la ejecución finaliza. Calculado a partir
de los créditos consumidos y tu tarifa de plan — 99%
preciso, pero credits_consumed es el valor autoritativo.
example:
id: batch_abc123def456
object: batch
status: in_progress
created: 1704067200
total_urls: 2
completed_urls: 0
country: US
metadata:
batch_name: Q1 Product Sync
initiated_by: automation
'400':
description: >-
Solicitud incorrecta debido a parámetros incorrectos o faltantes.
Consulta [Bad Request](/api-reference/errors/bad_request) para más
detalles.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: validation_error
type: https://docs.olostep.com/api-reference/errors/bad_request
status: 400
title: Solicitud Incorrecta
detail: >-
The 'items' array is required and must contain at least one
item.
created: 1704067200
metadata: {}
'401':
description: >-
Las credenciales de autenticación faltan o son inválidas. Consulta
[Unauthorized](/api-reference/errors/unauthorized) para más
detalles.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: invalid_api_key
type: https://docs.olostep.com/api-reference/errors/unauthorized
status: 401
title: No autorizado
detail: >-
Your API key is invalid. Try double-checking it or reaching
out to info@olostep.com if you're facing issues.
created: 1704067200
metadata: {}
'402':
description: >-
Pago requerido - créditos agotados. Consulta [Payment
Required](/api-reference/errors/payment_required) para más detalles.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: credits_exhausted
type: https://docs.olostep.com/api-reference/errors/payment_required
status: 402
title: Pago Requerido
detail: >-
You have consumed all available credits. Please upgrade your
plan from the dashboard: https://www.olostep.com/auth/
created: 1704067200
metadata: {}
'403':
description: >-
Prohibido - acceso denegado a esta función. Consulta
[Forbidden](/api-reference/errors/forbidden) para más detalles.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: access_denied
type: https://docs.olostep.com/api-reference/errors/forbidden
status: 403
title: Prohibido
detail: >-
You don't have access to this feature. Please reach out to
info@olostep.com to get approved
created: 1704067200
metadata: {}
'409':
description: >-
Conflicto de idempotencia: una solicitud con esta clave está en
progreso. Consulta [Error de
Idempotencia](/api-reference/errors/idempotency_error) para más
detalles.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: idempotency_key_in_progress
type: >-
https://docs.olostep.com/api-reference/errors/idempotency_error
status: 409
title: Error de Idempotencia
detail: >-
A request with this idempotency key is currently being
processed. Please wait and retry.
created: 1704067200
metadata: {}
'422':
description: >-
Entidad no procesable: violación de regla de negocio. Consulta
[Entidad No Procesable](/api-reference/errors/unprocessable_entity)
para más detalles.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: idempotency_key_reuse
type: >-
https://docs.olostep.com/api-reference/errors/unprocessable_entity
status: 422
title: Entidad No Procesable
detail: >-
A request with this idempotency key was already made with
different parameters. Idempotency keys must be unique per
request.
created: 1704067200
metadata: {}
'500':
description: >-
Error interno del servidor. Consulta [Internal
Error](/api-reference/errors/internal_error) para más detalles.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Error'
example:
id: error_abc123
object: error
code: internal_server_error
type: https://docs.olostep.com/api-reference/errors/internal_error
status: 500
title: Error Interno del Servidor
detail: An unexpected error occurred
created: 1704067200
metadata: {}
security:
- Authorization: []
components:
schemas:
Metadata:
type: object
description: >-
Conjunto de pares clave-valor para almacenar información adicional sobre
un objeto. Sigue el enfoque de Stripe con reglas de validación: máximo
50 claves, clave máximo 40 caracteres (sin corchetes), valor máximo 500
caracteres, todos los valores almacenados como cadenas.
additionalProperties:
type: string
maxLength: 500
description: >-
Valor de metadatos (máximo 500 caracteres). Los números y booleanos se
convierten automáticamente a cadenas.
maxProperties: 50
example:
order_id: '12345'
customer_name: John Doe
priority: high
processed: 'true'
x-validation-rules:
max_keys: 50
key_max_length: 40
key_forbidden_chars:
- '['
- ']'
value_max_length: 500
value_types:
- string
- number (coerced)
- boolean (coerced)
Error:
type: object
description: Respuesta de error de Detalles del Problema RFC 7807
properties:
id:
type: string
description: Identificador único de error
object:
type: string
enum:
- error
description: Siempre 'error'
code:
type: string
description: Código de error legible por máquina
type:
type: string
format: uri
description: Referencia URI que identifica el tipo de problema
status:
type: integer
description: Código de estado HTTP
title:
type: string
description: Resumen corto y legible por humanos
detail:
type: string
description: Explicación legible por humanos
created:
type: integer
description: Marca de tiempo Unix
metadata:
$ref: '#/components/schemas/Metadata'
errors:
type: array
description: Array opcional de detalles adicionales del error
items: {}
required:
- id
- object
- code
- type
- status
- title
- detail
- created
securitySchemes:
Authorization:
type: http
scheme: bearer
description: >-
Encabezado de autenticación Bearer de la forma Bearer , donde
es tu token de autenticación.
````