Receitas de integração

Todas as receitas usam métodos do perfil público. Elas não criam pedidos, alteram registros nem enviam mensagens.

Sincronizar catálogo por páginas

Esta é uma leitura paginada, não um feed de alterações: não há filtro de data de atualização nem snapshot consistente neste contrato. Mudanças de catálogo durante a leitura podem deslocar os offsets; faça upsert pela chave estável e reconcilie periodicamente.

1. Chame products.list com limit:60 e offset:0.
2. Processe result.items por codigo ou id, conforme a chave estável definida para sua integração.
3. Se result.next_cursor não for null, converta-o em número e envie como próximo offset.
4. Encerre quando next_cursor for null.
5. Não use total como cursor e não presuma que preço ou estoque sejam sempre preenchidos.

let offset = 0;
for (;;) {
  const page = await sysled.call("products.list", { limit: 60, offset });
  await saveProducts(page.items);
  if (page.next_cursor == null) break;
  const nextOffset = Number(page.next_cursor);
  if (!Number.isSafeInteger(nextOffset) || nextOffset <= offset) {
    throw new Error("Cursor de catálogo inválido ou sem progresso");
  }
  offset = nextOffset;
}

disponivel é a decisão pronta de compra na revisão documentada. estoque, reservado e disponivel_qtd têm significados diferentes.

Paginar mensagens de uma conversa autorizada

Esta receita exige messages.list da revisão 8319cf51 no backend. Mantenha um token com o escopo exato e vinculado à empresa correta; obtenha o conversation_id por um fluxo autorizado.

1. Faça a primeira chamada com conversation_id e limit:50, sem before.
2. Processe somente os campos necessários de result.messages, deduplicando por id na mesma empresa/conversa. total é o tamanho do lote; total_count é a contagem do histórico não excluído, não um cursor.
3. Quando hasMore:true, exija next_cursor como string não vazia e envie seu valor exatamente em before da próxima chamada, mantendo empresa e conversation_id. Não converta esse cursor em número nem o decodifique/reconstrua.
4. Encerre com hasMore:false e next_cursor:null. Interrompa em cursor repetido, campos ausentes/incoerentes ou no limite de páginas definido para sua integração; não reinicie indefinidamente em caso de erro.
5. Trate 400 BAD_REQUEST como entrada/cursor inválido e 404 NOT_FOUND como conversa inacessível ou âncora ausente desse histórico. Não reutilize cursores entre empresas ou conversas.

O cursor legado por UUID continua aceito, mas prefira sempre o next_cursor retornado. Novas mensagens e exclusões podem ocorrer durante a leitura: não há promessa de snapshot consistente. Limite a coleta ao necessário, aplique prazo de retenção e não registre conteúdo, URLs de mídia ou cursores em logs/tickets. delivered_at e read_at podem ser nulos; ausência de timestamp não comprova entrega nem leitura.

Consultar tarefas pendentes

Use tasks.list com completed:false, página iniciada em 1 e limite até 100. Se filtrar por owner_type, envie também owner_id. O total documentado é o tamanho do lote, não necessariamente o total global; pare quando a página retornar menos itens que o limite.

Consultar funil e etapas

1. pipelines.list retorna os funis acessíveis.
2. Escolha um id da resposta.
3. stages.list com esse pipeline_id retorna as etapas.
4. Em pipelines.get, trate found:false como ausência normal, ainda que o HTTP seja 200.

Calcular frete sem criar pedido

Envie CEP de oito dígitos e itens identificados por sku ou codigo:

{
  "cep": "01001000",
  "itens": [{ "sku": "DEMO-01", "qtd": 2 }]
}

shop.frete.calcular pode consultar geocodificação e manter cache técnico do CEP. O resultado é cotação: não cria pedido, não reserva estoque e não altera regra comercial.

Validar desconto

shop.desconto.validar calcula cupom e automáticos para os itens informados. Preço enviado pelo cliente é ignorado. Trate a resposta como estimativa e recalcule no fluxo comercial autorizado antes de concluir a venda.

Minimizar dados pessoais

leads.list e messages.list podem retornar dados pessoais, conteúdo e mídia. Use filtros, limite pequeno, retenção curta e acesso restrito. Não copie respostas integrais para logs ou tickets de suporte.