Introduction

Nota (PT-BR): conteúdo técnico em inglês (fiel ao repositório AdobeDocs/commerce-webapi). Esta seção cobre apenas os recursos disponíveis na edição Open Source.

Introduction to Magento 2 REST API

Magento provides REST endpoints that give access to admin, integration, customer and guest operations. Web services expose much of the same functionality that is available in the storefront and Admin panel.

Base URL

All REST endpoints share the same prefix:

https://<magento_host>/rest/<store_code>/V1/<resource>

Where:

• <magento_host> — your Magento domain.
• <store_code> — store view code. Use default, all or any store code configured in the admin. Can be omitted for default store.
• V1 — API version. Currently the only version.
• <resource> — resource path (e.g. products, customers, orders).

Request headers

• Authorization: Bearer <token> — obrigatório em endpoints protegidos.
• Content-Type: application/json — ao enviar corpo JSON.
• Accept: application/json — responses são JSON por padrão.

Types of REST endpoints

• Synchronous — resposta imediata. Padrão para a maioria das chamadas.
• Asynchronous — endpoint acrescenta o prefixo /async. Útil para operações longas.
• Bulk — endpoint acrescenta o prefixo /async/bulk. Processa um array de operações em paralelo.

Common HTTP Status Codes

• 200 OK — Successful GET/PUT/POST request.
• 201 Created — Resource created.
• 204 No Content — Successful DELETE.
• 400 Bad Request — Invalid parameters, validation errors.
• 401 Unauthorized — Missing or invalid token.
• 403 Forbidden — Token is valid but lacks permission for this resource.
• 404 Not Found — Resource does not exist.
• 500 Internal Server Error — Server error. Verifique os logs em var/log.

Error response format

{
    "message": "The product that was requested doesn't exist. Verify the product and try again.",
    "parameters": {
        "fieldName": "sku",
        "fieldValue": "sku-inexistente"
    }
}

Algumas respostas incluem o array errors com mensagens localizadas por campo. Dica (PT-BR): sempre trate a chave message primeiro — é a mais consistente entre versões.