Enviar catálogo de produtos

Esta rota envia o cadastro dos produtos da loja de um usuário final. O estoque não entra, apenas o cadastro. Com o catálogo, a IA conhece o produto antes da primeira venda, e o usuário pode fazer perguntas como “o que acha da garrafa térmica que acabei de cadastrar?”, “o preço da pochete está bom?”, “quais produtos não venderam nada este mês?” ou “como estão os produtos que lancei?“.

A IA responde com base no cadastro (preço, preço “de”, custo, categoria, descrição e data do cadastro) e, quando o produto já foi vendido, também com base nos pedidos.

curl -X PUT "https://api.diligensai.com.br/api/v1/products" \
  -H "X-API-Key: $DILIGENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "loja-123",
    "products": [{
      "id": "P-12",
      "sku": "GAR-TER-500",
      "name": "Garrafa térmica",
      "status": "active",
      "category": "Acessórios",
      "price_cents": 12990,
      "cost_cents": 5000,
      "created_at": "2026-09-28T10:00:00-03:00",
      "updated_at": "2026-09-28T10:00:00-03:00"
    }]
  }'

const response = await fetch('https://api.diligensai.com.br/api/v1/products', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.DILIGENS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    external_id: 'loja-123',
    products: [{
      id: 'P-12',
      sku: 'GAR-TER-500',
      name: 'Garrafa térmica',
      status: 'active',
      category: 'Acessórios',
      price_cents: 12990,
      cost_cents: 5000,
      created_at: '2026-09-28T10:00:00-03:00',
      updated_at: '2026-09-28T10:00:00-03:00',
    }],
  }),
});
const { batch_id, received } = await response.json();

import os
import requests

response = requests.put(
    "https://api.diligensai.com.br/api/v1/products",
    headers={"X-API-Key": os.environ["DILIGENS_API_KEY"]},
    json={
        "external_id": "loja-123",
        "products": [{
            "id": "P-12",
            "sku": "GAR-TER-500",
            "name": "Garrafa térmica",
            "status": "active",
            "category": "Acessórios",
            "price_cents": 12990,
            "cost_cents": 5000,
            "created_at": "2026-09-28T10:00:00-03:00",
            "updated_at": "2026-09-28T10:00:00-03:00",
        }],
    },
    timeout=30,
)
response.raise_for_status()

<?php
$body = [
    'external_id' => 'loja-123',
    'products' => [[
        'id' => 'P-12',
        'sku' => 'GAR-TER-500',
        'name' => 'Garrafa térmica',
        'status' => 'active',
        'category' => 'Acessórios',
        'price_cents' => 12990,
        'cost_cents' => 5000,
        'created_at' => '2026-09-28T10:00:00-03:00',
        'updated_at' => '2026-09-28T10:00:00-03:00',
    ]],
];

$ch = curl_init('https://api.diligensai.com.br/api/v1/products');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('DILIGENS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);
$result = json_decode(curl_exec($ch), true);

{ "batch_id": "0199a3c2-7f1e-7b6a-9d1c-2f4e8a6b1c3d", "received": 2 }

{
  "status": 400,
  "code": "COMMON_002",
  "message": "Dados inválidos",
  "details": [{ "field": "products[3].price_cents", "message": "Deve ser no mínimo 0" }]
}

Sincronização e webhook

O mesmo endpoint atende aos dois momentos da integração, assim como no PUT /orders:

• Sincronização do catálogo: Pagine todos os produtos do usuário e envie lotes de até 500, respeitando o limite de chamadas.
• Webhook: A cada produto criado ou alterado, envie um lote com 1 produto. Quando um produto for excluído no seu sistema, envie-o com status: "archived". Não existe rota de exclusão.

A rota responde com o status 202 assim que o lote é validado, e a gravação acontece em segundo plano, como no PUT /orders. Não reenvie um lote que recebeu 202.

Vínculo com os pedidos

O id do produto enviado aqui é o mesmo items[].product_id dos itens do PUT /orders. É esse id que liga as vendas ao produto do catálogo: sem ele nos itens, a IA não sabe quais produtos do catálogo foram vendidos. As duas sincronizações são independentes, e não importa qual chega primeiro.

Cada id corresponde ao que você vende com ele. Se o seu sistema tem variações (tamanho, cor) com id próprio, envie cada variação como um produto, com o variant_name e o parent_id (o produto pai).

Regras

• Um lote tem de 1 a 500 produtos, sempre do mesmo usuário final (external_id), e o body tem no máximo 5 MB. Se o usuário final ainda não existir, ele é criado.
• Valores em centavos, sempre inteiros. Datas em RFC 3339 com fuso. Datas mais de 1 hora no futuro são recusadas com o status 400 COMMON_002.
• Envie sempre o produto completo, com o estado atual. O cadastro é substituído por inteiro a cada envio, e um campo que não for enviado fica vazio.
• updated_at é obrigatório e deve ser a data da última alteração do produto no seu sistema, e não o horário do envio. A Diligens só grava o produto se essa data for mais recente que a do registro existente; portanto, reenviar não duplica dados. Para corrigir um produto, reenvie-o com um updated_at mais recente.
• Envie sempre o created_at, a data do cadastro no seu sistema. É com ela que a IA sabe que um produto é novo e ainda não teve tempo de vender. Sem ela, o produto não aparece entre os lançamentos.
• Sem status, o produto entra como active.
• O lote é tudo ou nada: Se a gravação falhar, nenhum produto do lote é gravado, e a Diligens tenta gravar o lote inteiro de novo. Reenviar também é seguro.

Corpo da requisição

Veja a seguir um exemplo com todos os campos de um produto:

{
  "external_id": "loja-123",
  "products": [
    {
      "id": "P-12",
      "parent_id": "P-PAI-12",
      "sku": "GAR-TER-500",
      "gtin": "7891234567895",
      "name": "Garrafa térmica",
      "variant_name": "500 ml / Preta",
      "description": "Aço inox com parede dupla: gelada por 24h e quente por 12h.",
      "status": "active",
      "product_type": "physical",
      "category": "Acessórios",
      "brand": "Trama",
      "unit": "un",
      "price_cents": 12990,
      "compare_at_price_cents": 15990,
      "cost_cents": 5000,
      "url": "https://loja.exemplo.com/garrafa-termica",
      "tags": ["inox", "lançamento"],
      "created_at": "2026-09-28T10:00:00-03:00",
      "updated_at": "2026-09-28T10:00:00-03:00"
    }
  ]
}

Resposta

Erros

Um campo inválido rejeita o lote inteiro. Os erros gerais (401, 402, 403, 429) estão descritos em Erros.