Using the REST API

Search criteria and filters

Quase todos os endpoints de listagem aceitam o query parameter searchCriteria, que permite filtros complexos, ordenação e paginação.

Structure

searchCriteria[filter_groups][<g>][filters][<f>][field]
searchCriteria[filter_groups][<g>][filters][<f>][value]
searchCriteria[filter_groups][<g>][filters][<f>][condition_type]

Operators (condition_type)

• eq — equal (default)
• neq — not equal
• like — SQL LIKE (use % wildcards)
• in / nin — in / not in a comma-separated list
• gt / lt — greater / less than
• gteq / lteq — greater/less or equal
• from / to — range (use two filters on the same field)
• notnull / null — NOT NULL / IS NULL

Filter groups — AND vs OR

• Filtros dentro de um mesmo group usam OR entre si.
• Filter groups entre si usam AND.

Pagination & sorting

searchCriteria[pageSize]=20
searchCriteria[currentPage]=1
searchCriteria[sortOrders][0][field]=created_at
searchCriteria[sortOrders][0][direction]=DESC

Dica (PT-BR): limite pageSize a valores razoáveis (<=100). Queries muito grandes podem causar timeout e bloquear o banco.

Asynchronous endpoints

Qualquer endpoint POST/PUT/DELETE pode rodar de forma assíncrona acrescentando /async ao prefixo /V1:

POST /rest/async/V1/products
POST /rest/async/default/V1/products

Response:

{
    "bulk_uuid": "19fa8a1d-8c2b-43ad-9f9b-b2f7cb738a1e",
    "request_items": [
        { "id": 0, "data_hash": null, "status": "accepted" }
    ],
    "errors": false
}

Use o bulk_uuid para consultar o status em:

GET /rest/V1/bulk/{bulk_uuid}/status

Dica (PT-BR): operações async exigem que a fila de mensagens esteja rodando (bin/magento queue:consumers:start async.operations.all).

Bulk endpoints

Para enviar múltiplas operações paralelas em uma única request, use o prefixo /async/bulk:

POST /rest/async/bulk/V1/products
POST /rest/async/bulk/V1/customers

O body é um array de objetos (ao invés do objeto único usado em requests normais).

Exemplo: criar 3 produtos de uma vez

[
    { "product": { "sku": "sku1", ... } },
    { "product": { "sku": "sku2", ... } },
    { "product": { "sku": "sku3", ... } }
]

Cada operação é processada independentemente — falha em uma não aborta as outras. Consulte o status agregado em GET /V1/bulk/{bulk_uuid}/status.

Retorna o progresso de uma operação assíncrona ou em lote.

Response fields: bulk_id, description, start_time, user_id, operation_count, operations_list com o status individual de cada item (open, complete, retriable_error, not_retriable_error).