> ## 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.
# Crea Batch
> Avvia un nuovo batch. Ricevi un `id` che puoi utilizzare per tracciare il progresso del batch come mostrato [qui](/api-reference/batches/info). Nota: Il tempo di elaborazione è costante indipendentemente dalla dimensione del batch
**Ricevi una notifica al completamento:** Passa il parametro `webhook` con l'URL del tuo endpoint per ricevere un HTTP POST quando il batch è completato. Vedi [Webhooks](/api-reference/common/webhooks) per i dettagli.
**Allega dati personalizzati:** Usa il parametro `metadata` per memorizzare coppie chiave-valore. Supportato a due livelli:
* **Livello batch** — nel corpo della richiesta
* **Livello elemento** — su ciascun elemento nell'array `items`
Vedi [Metadata](/api-reference/common/metadata) per i dettagli.
## OpenAPI
````yaml it/openapi/batches.json POST /v1/batches
openapi: 3.0.3
info:
title: API dei Batch
version: 1.0.0
servers:
- url: https://api.olostep.com
security: []
paths:
/v1/batches:
post:
summary: Avvia un nuovo batch
description: Inizia un nuovo processo batch con i parametri specificati.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
custom_id:
type: string
description: Un identificatore unico interno per l'url.
url:
type: string
format: uri
description: URL dell'elemento.
metadata:
allOf:
- $ref: '#/components/schemas/Metadata'
description: >-
Metadata a livello di elemento. Allega coppie
chiave-valore a singoli elementi per tracciamento,
filtraggio o correlazione con i tuoi sistemi interni.
required:
- custom_id
- url
description: Array di elementi da elaborare nel batch.
country:
type: string
description: >-
Paese per l'esecuzione del batch. Fornisci in codici ISO
3166-1 alpha-2 come US(USA), IN(India), ecc.
parser:
type: object
properties:
id:
type: string
description: Parser da utilizzare per il batch.
required:
- id
description: >-
Puoi usare questo parametro per specificare il parser da
utilizzare. I parser sono utili per estrarre contenuti
strutturati dalle pagine web. Olostep ha alcuni parser
integrati per le pagine web più comuni, e puoi anche creare
i tuoi parser.
links_on_page:
type: object
properties:
include_links:
type: array
items:
type: string
description: >-
Filtra i link estratti usando i pattern glob. I pattern
si confrontano con il percorso URL del link. Nota: un
singolo `*` non attraversa `/`, quindi "/blog/*"
corrisponde a "/blog/post-1" ma NON all'indice "/blog"
stesso (o "/blog?tag=x", poiché le stringhe di query non
fanno parte del percorso). Per includere anche l'indice,
usa "/blog*" o "{/blog,/blog/**}".
exclude_links:
type: array
items:
type: string
description: >-
Filtra i link estratti usando i pattern glob. I pattern
si confrontano con il percorso URL del link. Nota: un
singolo `*` non attraversa `/`, quindi "/blog/*"
corrisponde a "/blog/post-1" ma NON all'indice "/blog"
stesso.
description: >-
Ottieni tutti i link presenti su ogni pagina nel batch. I
link sono sempre restituiti come URL assoluti.
metadata:
$ref: '#/components/schemas/Metadata'
webhook:
type: string
format: uri
description: >-
URL HTTPS per ricevere una richiesta POST quando il batch è
completato. Deve essere un URL pubblicamente accessibile
usando il protocollo `http://` o `https://`. Non può puntare
a localhost o indirizzi IP privati. Vedi
[Webhooks](/api-reference/common/webhooks) per il formato
del payload e il comportamento di retry.
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: Batch avviato con successo.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: ID del Batch
object:
type: string
description: Il tipo di oggetto. "batch" per questo endpoint.
status:
type: string
description: '`in_progress` o `completed`'
created:
type: number
description: Epoch creato
total_urls:
type: number
description: Conteggio degli URL nel batch
completed_urls:
type: number
description: Conteggio degli URL completati
parser:
type: string
country:
type: string
metadata:
$ref: '#/components/schemas/Metadata'
webhook:
type: string
description: URL del webhook per ricevere la notifica di completamento
credits_consumed:
type: integer
nullable: true
description: >-
Numero di crediti consumati da questa richiesta. Popolato
dopo il completamento dell'esecuzione. I crediti sono la
fonte di verità per la fatturazione.
cost_usd:
type: number
nullable: true
description: >-
Costo stimato in USD per questa richiesta. Popolato dopo
il completamento dell'esecuzione. Calcolato dai crediti
consumati e dal tuo piano tariffario — 99% accurato, ma
credits_consumed è il valore autorevole.
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: >-
Richiesta errata a causa di parametri errati o mancanti. Vedi [Bad
Request](/api-reference/errors/bad_request) per i dettagli.
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: Richiesta Errata
detail: >-
The 'items' array is required and must contain at least one
item.
created: 1704067200
metadata: {}
'401':
description: >-
Le credenziali di autenticazione sono mancanti o non valide. Vedi
[Unauthorized](/api-reference/errors/unauthorized) per i dettagli.
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: Non autorizzato
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: >-
Pagamento richiesto - crediti esauriti. Vedi [Payment
Required](/api-reference/errors/payment_required) per i dettagli.
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: Pagamento Richiesto
detail: >-
You have consumed all available credits. Please upgrade your
plan from the dashboard: https://www.olostep.com/auth/
created: 1704067200
metadata: {}
'403':
description: >-
Vietato - accesso negato a questa funzione. Vedi
[Forbidden](/api-reference/errors/forbidden) per i dettagli.
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: Vietato
detail: >-
You don't have access to this feature. Please reach out to
info@olostep.com to get approved
created: 1704067200
metadata: {}
'409':
description: >-
Conflitto di idempotenza - una richiesta con questa chiave è in
corso. Vedi [Errore di
Idempotenza](/api-reference/errors/idempotency_error) per i
dettagli.
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: Errore di Idempotenza
detail: >-
A request with this idempotency key is currently being
processed. Please wait and retry.
created: 1704067200
metadata: {}
'422':
description: >-
Entità non elaborabile - violazione delle regole aziendali. Vedi
[Entità Non Elaborabile](/api-reference/errors/unprocessable_entity)
per i dettagli.
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: Entità Non Elaborabile
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: >-
Errore interno del server. Vedi [Internal
Error](/api-reference/errors/internal_error) per i dettagli.
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: Errore Interno del Server
detail: An unexpected error occurred
created: 1704067200
metadata: {}
security:
- Authorization: []
components:
schemas:
Metadata:
type: object
description: >-
Insieme di coppie chiave-valore per memorizzare informazioni aggiuntive
su un oggetto. Segue l'approccio di Stripe con regole di validazione:
massimo 50 chiavi, chiave massimo 40 caratteri (senza parentesi quadre),
valore massimo 500 caratteri, tutti i valori memorizzati come stringhe.
additionalProperties:
type: string
maxLength: 500
description: >-
Valore dei metadati (max 500 caratteri). Numeri e booleani sono
automaticamente convertiti in stringhe.
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: Risposta di errore Dettagli Problema RFC 7807
properties:
id:
type: string
description: Identificatore univoco dell'errore
object:
type: string
enum:
- error
description: Sempre 'error'
code:
type: string
description: Codice di errore leggibile dalla macchina
type:
type: string
format: uri
description: Riferimento URI che identifica il tipo di problema
status:
type: integer
description: Codice di stato HTTP
title:
type: string
description: Breve riassunto leggibile dall'uomo
detail:
type: string
description: Spiegazione leggibile dall'uomo
created:
type: integer
description: Timestamp Unix
metadata:
$ref: '#/components/schemas/Metadata'
errors:
type: array
description: Array opzionale di dettagli aggiuntivi sull'errore
items: {}
required:
- id
- object
- code
- type
- status
- title
- detail
- created
securitySchemes:
Authorization:
type: http
scheme: bearer
description: >-
Intestazione di autenticazione Bearer del tipo Bearer , dove
è il tuo token di autenticazione.
````