Pular para o conteúdo
Docs

Produtos

Mantenha o catálogo da sua loja no Emailit para grades de produtos, recomendações e itens de pedidos.

URL basehttps://api.emailit.com/v2AutenticaçãoErrosLimites de requisições

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.

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.

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.

POST/products

Corpo da requisição

idstring | numberObrigató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.

titlestring

Nome do produto, com até 500 caracteres. Você também pode enviá-lo como name. Obrigatório para um produto novo.

skustring

Unidade de manutenção de estoque (SKU), com até 255 caracteres.

descriptionstring

Descrição do produto, com até 10.000 caracteres.

urlstring

Página do produto na sua loja. Uma URL http ou https, com até 2.048 caracteres.

image_urlstring

Imagem do produto. Uma URL http ou https, com até 2.048 caracteres.

pricenumber | 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_pricenumber | string

Preço antes de um desconto, no mesmo formato de price. Quando ele é maior que price, o produto conta como em promoção.

currencystring

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.

categoriesstring[]

Até 50 nomes de categorias, cada um com até 191 caracteres. Os duplicados são removidos.

brandstring

Nome da marca, com até 191 caracteres.

inventory_quantityinteger | 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.

statusstring

active ou archived. Os produtos novos são active. Os produtos arquivados ficam ocultos em Listar produtos por padrão e ficam de fora das grades de produtos.

metadataobject

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 quando o produto é novo, ou 200 OK quando um produto existente foi atualizado. Retorna 422 quando um campo é inválido.

POST/products
Terminal
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
  }'
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"
}

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.

GET/products/{id}

Parâmetros de caminho

idstringObrigató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

objectstring

Sempre product.

idstring

ID do produto no Emailit (prd_...).

external_idstring

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.

skustring | null

Unidade de manutenção de estoque (SKU).

titlestring

Nome do produto.

descriptionstring | null

Descrição do produto.

urlstring | null

Página do produto na sua loja.

image_urlstring | null

Imagem do produto.

pricenumber | null

Preço atual.

compare_at_pricenumber | null

Preço antes de um desconto. Um produto está em promoção quando compare_at_price é maior que price.

currencystring | null

Código ISO 4217 de três letras dos preços.

categoriesstring[]

Nomes das categorias.

brandstring | null

Nome da marca.

inventory_quantityinteger | 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.

statusstring

active ou archived. As grades de produtos nos e-mails deixam de fora os produtos arquivados.

metadataobject

Os seus próprios dados de chave e valor.

created_atstring

Quando o produto foi adicionado, em ISO 8601 UTC.

updated_atstring

Quando o produto mudou pela última vez, em ISO 8601 UTC.

GET/products/{id}
Terminal
curl https://api.emailit.com/v2/products/prd_3r6HHUGUSl8yjYDscEA6aYA8wrA \
  -H "Authorization: Bearer your_api_key"
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"
}

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.

Para criar produtos e atualizá-los com a mesma chamada, use Criar ou atualizar um produto.

POST/products/{id}

Parâmetros de caminho

idstringObrigató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, 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 atualizado. Retorna 404 se nenhum produto corresponder a id e 422 quando um campo é inválido.

POST/products/{id}
Terminal
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 }'
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"
}

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.

GET/products

Parâmetros de consulta

pageinteger

Número da página para a paginação (mínimo: 1, padrão: 1).

limitinteger

Número de produtos a retornar (mínimo: 1, máximo: 100, padrão: 25).

searchstring

Busca sem diferenciar maiúsculas de minúsculas no título, no ID do produto na sua loja (external_id) ou no SKU.

categorystring

Só os produtos desta categoria. O nome precisa corresponder exatamente, incluindo maiúsculas e minúsculas.

statusstring

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.

idsstring

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.

matchstring

all (padrão) exige que todos os filtros key.condition correspondam. or aceita qualquer um deles. Consulte Filtragem.

sortstring

Chave de ordenação: created_at (padrão), updated_at, title ou price.

orderstring

Direção da ordenação: asc ou desc (padrão).

Filtros

Os filtros de listagem são um único nível de parâmetros de consulta key.condition=value. Consulte Filtragem para match, order, direction e a lista de condições por tipo.

Chaves de filtro

ChaveTipoCondiçõesObservações
titlestringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
external_idstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
skustringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
brandstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
currencystringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
pricenumberexact, not_exact, gt, gte, lt, lte, empty, not_empty
inventory_quantitynumberexact, not_exact, gt, gte, lt, lte, empty, not_empty
statusenumexact, not_exactValores: active, archived
created_atdateexact, before, after, empty, not_empty
updated_atdateexact, before, after, empty, not_empty

Chaves de ordenação

Este endpoint ordena com sort definido como uma destas chaves e order definido como asc ou desc (aqui, order=<key> retorna 400): created_at, updated_at, title, price

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 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.

GET/products
Terminal
curl "https://api.emailit.com/v2/products?category=Running&sort=price&order=asc&limit=25" \
  -H "Authorization: Bearer your_api_key"
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
}

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: 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.

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

productsobject[]Obrigatório

De 1 a 1.000 produtos, cada um com os campos de Criar ou atualizar um produto.

Retorno

createdinteger

Número de produtos novos.

updatedinteger

Número de produtos existentes que foram atualizados.

rejectedobject[]

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.

POST/products/batch
Terminal
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" }
    ]
  }'
JSON
{
  "created": 1,
  "updated": 1,
  "rejected": [
    {
      "index": 2,
      "errors": {
        "products.2.title": [
          "is required"
        ]
      }
    }
  ]
}

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.

As categorias vêm do campo categories de cada produto. Use um nome de categoria com o parâmetro category de Listar produtos.

GET/products/categories
GET/products/categories
Terminal
curl https://api.emailit.com/v2/products/categories \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "data": [
    {
      "name": "Accessories",
      "products": 18
    },
    {
      "name": "Running",
      "products": 12
    },
    {
      "name": "Shoes",
      "products": 27
    }
  ]
}

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.

Se o script de rastreamento 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

idstringObrigatório

O ID do produto (prd_...) ou o ID do produto na sua loja.

DELETE/products/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/products/prd_3r6HHUGUSl8yjYDscEA6aYA8wrA \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "object": "product",
  "id": "prd_3r6HHUGUSl8yjYDscEA6aYA8wrA",
  "deleted": true
}

Esta página foi útil?

Obrigado pelo feedback.

Obrigado, lemos todas as mensagens.

Esc

Populares

↑↓para navegar↵para abrirEscpara fechar