# Produtos API > Mantenha o catálogo da sua loja no Emailit para grades de produtos, recomendações e itens de pedidos. URL base: `https://api.emailit.com/v2`. Autentique-se com `Authorization: Bearer `. ## Criar ou atualizar um produto — POST /products > Adicione um produto ao seu catálogo, ou atualize-o, identificado pelo ID do produto na sua loja. Alfa: aberto apenas à equipe do Emailit. # Criar ou atualizar um produto Adiciona um produto ao seu catálogo ou o atualiza, se já existir um produto com o mesmo `id`. O `id` é o ID do produto na sua loja, então você pode enviar o mesmo produto de novo sempre que ele mudar. Requer uma chave de API com escopo `full` ou `events`. Com uma chave `events`, a resposta traz apenas `object`, `id` e `external_id`. > **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce). `id` é sempre obrigatório, e `title` é obrigatório para um produto novo. Os campos só são gravados quando você os envia, então um produto que você envia de novo só com um preço novo mantém o título, as categorias, a imagem e o resto. Para enviar muitos produtos de uma vez, use [Criar ou atualizar produtos em massa](/pt/docs/api-reference/products/batch/). As grades de produtos, as recomendações e os itens de pedidos nos e-mails leem o catálogo. Consulte [Produtos, cupons e o carrinho](/pt/docs/campaigns/products-and-coupons/). `POST /products` ## Corpo da requisição - `id` (string | number, obrigatório): O ID do produto na sua loja, com até 255 caracteres. Os números são armazenados como strings. Armazenado como `external_id`. Você também pode enviá-lo como `external_id`. - `title` (string): Nome do produto, com até 500 caracteres. Você também pode enviá-lo como `name`. Obrigatório para um produto novo. - `sku` (string): Unidade de manutenção de estoque (SKU), com até 255 caracteres. - `description` (string): Descrição do produto, com até 10.000 caracteres. - `url` (string): Página do produto na sua loja. Uma URL `http` ou `https`, com até 2.048 caracteres. - `image_url` (string): Imagem do produto. Uma URL `http` ou `https`, com até 2.048 caracteres. - `price` (number | string): Preço atual, como número ou string numérica, por exemplo `"89.00"`. Não pode ser negativo. Armazenado com até 4 casas decimais. - `compare_at_price` (number | string): Preço antes de um desconto, no mesmo formato de `price`. Quando ele é maior que `price`, o produto conta como em promoção. - `currency` (string): Código ISO 4217 de três letras, como `USD` ou `EUR`. Letras minúsculas são aceitas. Os e-mails formatam os preços do produto nessa moeda, ou em USD quando ela não está definida. - `categories` (string[]): Até 50 nomes de categorias, cada um com até 191 caracteres. Os duplicados são removidos. - `brand` (string): Nome da marca, com até 191 caracteres. - `inventory_quantity` (integer | null): Unidades em estoque. `null` significa que você não controla o estoque. As grades de produtos nos e-mails deixam de fora os produtos com estoque `0`. - `status` (string): `active` ou `archived`. Os produtos novos são `active`. Os produtos arquivados ficam ocultos em [Listar produtos](/pt/docs/api-reference/products/list/) por padrão e ficam de fora das grades de produtos. - `metadata` (object): Os seus próprios dados de chave e valor, com até 16 KB em JSON. Enviar `metadata` substitui o objeto armazenado. ## Retorno `201 Created` com o [objeto de produto](/pt/docs/api-reference/products/get/) quando o produto é novo, ou `200 OK` quando um produto existente foi atualizado. Retorna `422` quando um campo é inválido. **Requisição** `POST /products` **cURL** ```bash curl -X POST https://api.emailit.com/v2/products \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/json" \ -d '{ "id": "8123456789", "title": "Trail running shoe", "sku": "TRS-BLU-42", "url": "https://shop.example.com/products/trail-running-shoe", "image_url": "https://shop.example.com/images/trail-running-shoe.jpg", "price": 89, "compare_at_price": 119, "currency": "USD", "categories": ["Shoes", "Running"], "brand": "Acme Outdoors", "inventory_quantity": 34 }' ``` **201** ```json { "object": "product", "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA", "external_id": "8123456789", "sku": "TRS-BLU-42", "title": "Trail running shoe", "description": null, "url": "https://shop.example.com/products/trail-running-shoe", "image_url": "https://shop.example.com/images/trail-running-shoe.jpg", "price": 89, "compare_at_price": 119, "currency": "USD", "categories": [ "Shoes", "Running" ], "brand": "Acme Outdoors", "inventory_quantity": 34, "status": "active", "metadata": {}, "created_at": "2026-10-08T14:21:07.512Z", "updated_at": "2026-10-08T14:21:07.512Z" } ``` **422** ```json { "message": "Validation failed. price: must not be negative", "errors": { "price": [ "must not be negative" ] } } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/products/create/ ## Obter um produto — GET /products/{id} > Obtenha um produto do seu catálogo pelo ID dele no Emailit ou pelo ID do produto na sua loja. Alfa: aberto apenas à equipe do Emailit. # Obter um produto Obtém um produto pelo ID dele no Emailit ou pelo ID do produto na sua loja. Requer uma chave de API com escopo `full`. > **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce). `GET /products/{id}` ## Parâmetros de caminho - `id` (string, obrigatório): O ID do produto (`prd_...`) ou o ID do produto na sua loja (`external_id`). Codifique para URL os IDs da loja que contêm caracteres especiais. ## O objeto de produto - `object` (string): Sempre `product`. - `id` (string): ID do produto no Emailit (`prd_...`). - `external_id` (string): O ID do produto na sua loja: o `id` que você enviou. Os itens de pedidos e de carrinhos se referem aos produtos por esse ID. - `sku` (string | null): Unidade de manutenção de estoque (SKU). - `title` (string): Nome do produto. - `description` (string | null): Descrição do produto. - `url` (string | null): Página do produto na sua loja. - `image_url` (string | null): Imagem do produto. - `price` (number | null): Preço atual. - `compare_at_price` (number | null): Preço antes de um desconto. Um produto está em promoção quando `compare_at_price` é maior que `price`. - `currency` (string | null): Código ISO 4217 de três letras dos preços. - `categories` (string[]): Nomes das categorias. - `brand` (string | null): Nome da marca. - `inventory_quantity` (integer | null): Unidades em estoque. `null` significa que o estoque não é controlado. As grades de produtos nos e-mails deixam de fora os produtos com estoque `0`. - `status` (string): `active` ou `archived`. As grades de produtos nos e-mails deixam de fora os produtos arquivados. - `metadata` (object): Os seus próprios dados de chave e valor. - `created_at` (string): Quando o produto foi adicionado, em ISO 8601 UTC. - `updated_at` (string): Quando o produto mudou pela última vez, em ISO 8601 UTC. **Requisição** `GET /products/{id}` **cURL** ```bash curl https://api.emailit.com/v2/products/prd_3r6HHUGUSl8yjYDscEA6aYA8wrA \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "object": "product", "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA", "external_id": "8123456789", "sku": "TRS-BLU-42", "title": "Trail running shoe", "description": "Lightweight shoe with a grippy sole for wet trails.", "url": "https://shop.example.com/products/trail-running-shoe", "image_url": "https://shop.example.com/images/trail-running-shoe.jpg", "price": 89, "compare_at_price": 119, "currency": "USD", "categories": [ "Shoes", "Running" ], "brand": "Acme Outdoors", "inventory_quantity": 34, "status": "active", "metadata": { "color": "blue" }, "created_at": "2026-10-02T08:15:22.418Z", "updated_at": "2026-10-08T14:21:07.512Z" } ``` **404** ```json { "error": "Product not found", "message": "Product not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/products/get/ ## Atualizar um produto — POST /products/{id} > Altere alguns campos de um produto do seu catálogo. Alfa: aberto apenas à equipe do Emailit. # Atualizar um produto Atualiza um produto que já está no seu catálogo. Só mudam os campos que você enviar. O ID do produto na sua loja não pode mudar: um `id` no corpo é ignorado. Requer uma chave de API com escopo `full` ou `events`. Com uma chave `events`, a resposta traz apenas `object`, `id` e `external_id`. > **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce). Para criar produtos e atualizá-los com a mesma chamada, use [Criar ou atualizar um produto](/pt/docs/api-reference/products/create/). `POST /products/{id}` ## Parâmetros de caminho - `id` (string, obrigatório): O ID do produto (`prd_...`) ou o ID do produto na sua loja. ## Corpo da requisição Qualquer um dos campos de [Criar ou atualizar um produto](/pt/docs/api-reference/products/create/), exceto `id`: `title`, `sku`, `description`, `url`, `image_url`, `price`, `compare_at_price`, `currency`, `categories`, `brand`, `inventory_quantity`, `status` e `metadata`. As mesmas regras se aplicam. `categories` e `metadata` são substituídos por inteiro. ## Retorno `200 OK` com o [objeto de produto](/pt/docs/api-reference/products/get/) atualizado. Retorna `404` se nenhum produto corresponder a `id` e `422` quando um campo é inválido. **Requisição** `POST /products/{id}` **cURL** ```bash curl -X POST https://api.emailit.com/v2/products/8123456789 \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/json" \ -d '{ "price": 79, "inventory_quantity": 20 }' ``` **200** ```json { "object": "product", "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA", "external_id": "8123456789", "sku": "TRS-BLU-42", "title": "Trail running shoe", "description": "Lightweight shoe with a grippy sole for wet trails.", "url": "https://shop.example.com/products/trail-running-shoe", "image_url": "https://shop.example.com/images/trail-running-shoe.jpg", "price": 79, "compare_at_price": 119, "currency": "USD", "categories": [ "Shoes", "Running" ], "brand": "Acme Outdoors", "inventory_quantity": 20, "status": "active", "metadata": { "color": "blue" }, "created_at": "2026-10-02T08:15:22.418Z", "updated_at": "2026-10-09T10:02:41.205Z" } ``` **404** ```json { "error": "Product not found", "message": "Product not found." } ``` **422** ```json { "message": "Validation failed. image_url: must be an http(s) URL", "errors": { "image_url": [ "must be an http(s) URL" ] } } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/products/update/ ## Listar produtos — GET /products > Liste os produtos do seu catálogo, dos mais recentes para os mais antigos, com filtros de busca, categoria e status. Alfa: aberto apenas à equipe do Emailit. # Listar produtos Lista os produtos do seu catálogo, dos mais recentes para os mais antigos. Sem `status`, só os produtos ativos são listados. Requer uma chave de API com escopo `full`. > **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce). `GET /products` ## Parâmetros de consulta - `page` (integer): Número da página para a paginação (mínimo: 1, padrão: 1). - `limit` (integer): Número de produtos a retornar (mínimo: 1, máximo: 100, padrão: 25). - `search` (string): Busca sem diferenciar maiúsculas de minúsculas no título, no ID do produto na sua loja (`external_id`) ou no SKU. - `category` (string): Só os produtos desta categoria. O nome precisa corresponder exatamente, incluindo maiúsculas e minúsculas. - `status` (string): `active` (padrão), `archived` ou `all`. Use `all` quando filtrar pela chave `status` abaixo, porque o padrão já limita a lista aos produtos ativos. - `ids` (string): Lista separada por vírgulas de até 100 IDs de produto. Cada um pode ser o ID no Emailit (`prd_...`) ou o ID do produto na sua loja. - `match` (string): `all` (padrão) exige que todos os filtros `key.condition` correspondam. `or` aceita qualquer um deles. Consulte [Filtragem](/pt/docs/api-reference/filtering/). - `sort` (string): Chave de ordenação: `created_at` (padrão), `updated_at`, `title` ou `price`. - `order` (string): Direção da ordenação: `asc` ou `desc` (padrão). ## Filtros Chaves de filtro e de ordenação: consulte [Filtragem](https://emailit.com/pt/docs/api-reference/filtering/). Neste endpoint, `order` só aceita `asc` ou `desc`. Passe a chave de ordenação em `sort`, por exemplo `sort=price&order=asc`. ## Retorno Uma página de [objetos de produto](/pt/docs/api-reference/products/get/) em `data`, com `total_records`, `next_page_url` e `previous_page_url`. As URLs de página levam só `page` e `limit`, então adicione a sua busca e os seus filtros de novo quando segui-las. **Requisição** `GET /products` **cURL** ```bash curl "https://api.emailit.com/v2/products?category=Running&sort=price&order=asc&limit=25" \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "data": [ { "object": "product", "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA", "external_id": "8123456789", "sku": "TRS-BLU-42", "title": "Trail running shoe", "description": "Lightweight shoe with a grippy sole for wet trails.", "url": "https://shop.example.com/products/trail-running-shoe", "image_url": "https://shop.example.com/images/trail-running-shoe.jpg", "price": 89, "compare_at_price": 119, "currency": "USD", "categories": [ "Shoes", "Running" ], "brand": "Acme Outdoors", "inventory_quantity": 34, "status": "active", "metadata": { "color": "blue" }, "created_at": "2026-10-02T08:15:22.418Z", "updated_at": "2026-10-08T14:21:07.512Z" } ], "total_records": 1, "next_page_url": null, "previous_page_url": null } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/products/list/ ## Criar ou atualizar produtos em massa — POST /products/batch > Envie até 1.000 produtos em uma requisição. Cada um é criado ou atualizado pelo ID do produto na sua loja. Alfa: aberto apenas à equipe do Emailit. # Criar ou atualizar produtos em massa Envie até 1.000 produtos em uma requisição, por exemplo para importar o seu catálogo ou para sincronizá-lo periodicamente. Cada produto segue as regras de [Criar ou atualizar um produto](/pt/docs/api-reference/products/create/): ele é criado ou atualizado pelo `id`, um produto novo precisa de um `title` e os campos só são gravados quando você os envia. Requer uma chave de API com escopo `full` ou `events`. Com uma chave `events`, a resposta traz apenas `object`, `id` e `external_id`. > **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce). Os produtos inválidos são ignorados e listados em `rejected`; os outros são armazenados. A requisição retorna `200` mesmo assim. `POST /products/batch` ## Corpo da requisição - `products` (object[], obrigatório): De 1 a 1.000 produtos, cada um com os campos de [Criar ou atualizar um produto](/pt/docs/api-reference/products/create/). ## Retorno - `created` (integer): Número de produtos novos. - `updated` (integer): Número de produtos existentes que foram atualizados. - `rejected` (object[]): Produtos que não foram armazenados. Cada item tem o `index` do produto no seu array `products` e `errors`, indexado pelo caminho do campo, como `products.3.price`. Retorna `422` se `products` estiver vazio ou tiver mais de 1.000 itens. **Requisição** `POST /products/batch` **cURL** ```bash curl -X POST https://api.emailit.com/v2/products/batch \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/json" \ -d '{ "products": [ { "id": "8123456789", "title": "Trail running shoe", "price": 89, "currency": "USD", "categories": ["Shoes", "Running"] }, { "id": "8123456790", "title": "Merino running socks", "price": 18, "currency": "USD", "categories": ["Accessories"] }, { "id": "8123456791", "price": 49, "currency": "USD" } ] }' ``` **200** ```json { "created": 1, "updated": 1, "rejected": [ { "index": 2, "errors": { "products.2.title": [ "is required" ] } } ] } ``` **422** ```json { "message": "Validation failed. products: Send 1 to 1000 products.", "errors": { "products": [ "Send 1 to 1000 products." ] } } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/products/batch/ ## Listar categorias de produtos — GET /products/categories > Liste as categorias dos produtos ativos do seu catálogo, com o número de produtos em cada uma. Alfa: aberto apenas à equipe do Emailit. # Listar categorias de produtos Lista as categorias usadas pelos produtos ativos, em ordem alfabética, com o número de produtos ativos em cada uma. Os produtos arquivados não são contados. Retorna até 1.000 categorias e não tem paginação. Requer uma chave de API com escopo `full`. > **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce). As categorias vêm do campo `categories` de cada produto. Use um nome de categoria com o parâmetro `category` de [Listar produtos](/pt/docs/api-reference/products/list/). `GET /products/categories` **Requisição** `GET /products/categories` **cURL** ```bash curl https://api.emailit.com/v2/products/categories \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "data": [ { "name": "Accessories", "products": 18 }, { "name": "Running", "products": 12 }, { "name": "Shoes", "products": 27 } ] } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/products/categories/ ## Excluir um produto — DELETE /products/{id} > Remova um produto do seu catálogo. Alfa: aberto apenas à equipe do Emailit. # Excluir um produto Remove um produto do seu catálogo. Os pedidos que o contêm mantêm os itens deles, que armazenam o próprio título, preço e ID do produto. Para ocultar um produto sem excluí-lo, defina o `status` dele como `archived`. Requer uma chave de API com escopo `full`. > **O e-commerce está em alfa:** O e-commerce está aberto apenas à equipe do Emailit enquanto o testamos. As outras requisições retornam `403` com `error: "commerce_alpha"`. As chaves de API funcionam apenas em workspaces que pertencem à equipe do Emailit. Consulte [Quem pode usar o e-commerce](/pt/docs/commerce/#who-can-use-commerce). Se o [script de rastreamento](/pt/docs/commerce/connect-your-shop/#the-tracking-script) registrar uma visualização de um produto excluído com o título dele, o produto é adicionado de novo ao catálogo a partir dos dados da página. `DELETE /products/{id}` ## Parâmetros de caminho - `id` (string, obrigatório): O ID do produto (`prd_...`) ou o ID do produto na sua loja. **Requisição** `DELETE /products/{id}` **cURL** ```bash curl -X DELETE https://api.emailit.com/v2/products/prd_3r6HHUGUSl8yjYDscEA6aYA8wrA \ -H "Authorization: Bearer your_api_key" ``` **200** ```json { "object": "product", "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA", "deleted": true } ``` **404** ```json { "error": "Product not found", "message": "Product not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/products/delete/