Registar a proveniência a partir do seu ERP

Os sistemas empresariais têm acesso a eventos que o DICE nunca presencia: uma receção de mercadorias no SAP, a aprovação de uma inspeção no seu MES, uma venda concluída na sua plataforma de comércio. As Transações declaradas permitem que a sua integração registe esses momentos no histórico de um Registo à medida que ocorrem — cada um como uma entrada permanente e atribuída, que acompanha a proveniência do item e pode aparecer na respetiva Página pública.

Este guia liga um ERP (a mesma estrutura é adequada para um WMS, MES ou qualquer sistema de registo) a POST /api/v1/events/declare, com autenticação como uma Conta de Serviço e atribuição de cada entrada ao operador humano que realizou a ação no seu sistema.

Nota

Uma entrada declarada é uma afirmação atribuída da sua organização — nunca um facto verificado pela plataforma. O DICE regista quem fez a afirmação e quando, apresenta-a assinalada como declarada e nunca a apresenta como algo que a plataforma tenha observado. É também permanente: é partilhada com os proprietários subsequentes juntamente com o restante histórico do Registo e não pode ser eliminada, apenas retirada — e uma retirada é uma segunda entrada visível, não uma eliminação.

Visão geral do fluxo

1. A sua integração troca a credencial da Conta de Serviço por um bearer token de curta duração (Autenticação).
2. Ocorre algo no seu sistema — uma saída de mercadorias, uma inspeção, o encerramento de uma reparação.
3. A sua integração chama POST /api/v1/events/declare com o id do Registo, um título e a hora e o local da afirmação, enviando a identidade do operador no cabeçalho Dust-Ctx-Declared-Actor.
4. A entrada aparece no Registo de transações do Registo no DICE, assinalada como Declarada e atribuída à Conta de Serviço que atuou em nome do seu operador.

Pré-requisitos

• Uma Conta de Serviço com uma chave de API ou um cliente OAuth — consulte Autenticação. A Conta de Serviço necessita de acesso de edição aos Registos nos quais irá escrever (conceda-lhe acesso à Equipa proprietária).
• O id da sua organização para o cabeçalho Dust-Ctx-Org-Id e o id da Equipa, caso a Conta de Serviço deva atuar como uma Equipa específica — consulte Convenções dos pedidos.
• Os ids dos Registos dos itens envolvidos. Normalmente, uma integração resolve-os pesquisando o campo que partilha com o seu sistema — um número de série, lote ou número de encomenda — através de GET /api/v1/threads (consulte o guia da API de Registos).

Declarar uma transação

Uma chamada regista uma entrada num Registo:

curl

curl -fsS "https://apid.dustid.io/api/v1/events/declare" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H 'Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP", "displayName": "Jane Doe"}' \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "0b9e7c9a-2f9d-4d8a-9a51-1c2e57ab8d10",
    "title": "Incoming inspection passed",
    "note": "Visual and dimensional inspection against PO 4500012345.",
    "kind": "inspection",
    "edtf": "2026-08-06",
    "location": { "name": "Plant 1710, Springfield" }
  }'

TypeScript

const response = await fetch("https://apid.dustid.io/api/v1/events/declare", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Dust-Ctx-Org-Id": orgId,
    "Dust-Ctx-Declared-Actor": JSON.stringify({
      id: "JDOE",
      system: "SAP",
      displayName: "Jane Doe",
    }),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    threadId: "0b9e7c9a-2f9d-4d8a-9a51-1c2e57ab8d10",
    title: "Incoming inspection passed",
    note: "Visual and dimensional inspection against PO 4500012345.",
    kind: "inspection",
    edtf: "2026-08-06",
    location: { name: "Plant 1710, Springfield" },
  }),
});
if (!response.ok) throw new Error(`declare failed: ${response.status}`);
const claim = await response.json();

Campos do pedido — todos são opcionais, exceto threadId, mas uma declaração totalmente vazia é rejeitada:

Campo	Tipo	Notas
threadId	UUID	O Registo ao qual pertence a entrada. Requer acesso de edição.
title	string ≤ 80	Título curto — aquilo que os feeds e as páginas apresentam como título da entrada.
note	string ≤ 4000	Descrição em texto livre do que aconteceu.
kind	string ≤ 64	Classificação aberta: sale, inspection, repair, service, … o seu vocabulário. A predefinição é other.
edtf	string ≤ 64	Quando aconteceu, com a precisão que realmente conhece — consulte abaixo. Omita para o registar com a data e hora atuais.
location	object	O local declarado: { "name": string, "latitude"?: number, "longitude"?: number }. name é o valor apresentado.
resIds	UUID[] ≤ 25	Evidência: ids de ficheiros já anexados ao Registo que documentam a entrada — um relatório de inspeção, um certificado. Os ids de ficheiros que não estejam anexados a esse Registo são rejeitados.

A resposta devolve a afirmação materializada — kind, title, note e um objeto when estruturado que contém a cadeia display, a precisão e os limites da afirmação.

Indicar o momento com a precisão conhecida

edtf aceita um subconjunto de EDTF (ISO 8601-2), para que a afirmação tenha exatamente a precisão de que o seu sistema dispõe — um ano, um mês, um dia, um intervalo ou uma aproximação:

Afirmação	edtf	Apresentada como
Um dia exato	2026-07-14	14 de jul. de 2026
Um mês	2026-07	Julho de 2026
Um ano	1968	1968
Um intervalo fechado	1968/1970	1968–1970
Aproximadamente	1835~	Cerca de 1835
Antes de uma data	../1970-03	Antes de março de 1970
Depois de uma data	2019/..	Depois de 2019

A afirmação é apresentada em todo o lado com a precisão que indicou — um intervalo 1968/1970 nunca é reduzido a uma data exata inventada. Envie a precisão de que realmente dispõe, não uma estimativa artificial com carimbo de data/hora à meia-noite.

Dica

Normalmente, os documentos do ERP incluem uma data de lançamento, não um carimbo de data/hora. Publique a data (2026-08-06), não um instante inventado — o registo é mais fiel e apresenta-se melhor no Registo e na respetiva Página pública.

Atribuir o operador humano

Uma Conta de Serviço autentica o seu sistema. O cabeçalho Dust-Ctx-Declared-Actor identifica a pessoa que nele realizou a ação, em cada pedido:

Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP", "displayName": "Jane Doe", "role": "Quality Inspector"}

id é obrigatório; system, displayName e role são opcionais; o valor JSON deve ter menos de 1 KB (codifique-o para URI se contiver caracteres não ASCII). O interveniente declarado é registado literalmente em todas as entradas escritas pelo pedido e apresentado no histórico como atribuição declarada — fornecida pela sua integração, não verificada pelo DICE e sem qualquer efeito nas permissões. Um administrador da organização pode torná-lo obrigatório; nesse caso, os pedidos de escrita que não o incluam são rejeitados com 403 ATTRIBUTION_REQUIRED. Semântica completa: Atribuição do interveniente declarado.

Para a proveniência declarada, vale a pena tratar este cabeçalho como obrigatório no seu próprio código: «Inspecionado — aprovado» é uma afirmação muito mais sólida quando inclui «Jane Doe, inspetora de qualidade» do que quando inclui apenas «Conector SAP».

Declarar para um lote completo

Quando um evento empresarial afeta muitos itens — uma receção de mercadorias com 200 unidades serializadas, uma inspeção ao nível do lote — declare-o uma vez para todos:

curl -fsS "https://apid.dustid.io/api/v1/events/declare/batch" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H 'Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP"}' \
  -H "Content-Type: application/json" \
  -d '{
    "threadIds": ["0b9e7c9a-…", "4f1d22c0-…", "9a8b11de-…"],
    "title": "Incoming inspection passed",
    "kind": "inspection",
    "edtf": "2026-08-06",
    "location": { "name": "Plant 1710, Springfield" }
  }'

• threadIds aceita entre 1 e 500 ids de Registos; a escrita é integral ou nula e requer acesso de edição a todos os Registos do lote.
• A mesma afirmação é registada em todos os Registos — não existe variação por Registo num lote. Os dados que diferem por item (série, lote, resultados de medições) devem ficar nos campos do Registo, não na afirmação.
• A resposta inclui um operationId partilhado. Guarde-o: é o identificador para corrigir o lote (consulte abaixo).

Dica

O endpoint de lote também funciona com um único id de Registo e, ao contrário do endpoint de entrada única, devolve um operationId. Se a sua integração puder vir a necessitar de corrigir uma entrada através de código, declarar através do endpoint de lote e guardar o operationId juntamente com o documento de origem proporciona-lhe um identificador duradouro.

Preencher retroativamente várias entradas de uma só vez

/declare/batch escreve uma afirmação em vários Registos. Quando tiver muitas afirmações diferentes para publicar — um preenchimento retroativo do histórico, uma migração de um sistema baseado em folhas de cálculo, os eventos de um dia no chão de fábrica — utilize /declare/rows. Cada linha é escrita em todos os Registos em threadIds, e todas partilham um único operationId:

curl -fsS "https://apid.dustid.io/api/v1/events/declare/rows" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H 'Dust-Ctx-Declared-Actor: {"id": "JDOE", "system": "SAP"}' \
  -H "Content-Type: application/json" \
  -d '{
    "threadIds": ["0b9e7c9a-…"],
    "rows": [
      { "title": "Inspected", "kind": "inspection", "edtf": "2024-03-01", "location": { "name": "Geneva" } },
      { "title": "Sealed for shipment", "kind": "shipment", "edtf": "2024-03-04" },
      { "title": "Customs cleared", "edtf": "2024-03-11" }
    ]
  }'

• Até 100 linhas e 500 Registos, com um limite de 2 000 entradas no total (threadIds.length × rows.length) por pedido. Divida os preenchimentos retroativos maiores.
• Integral ou nulo em todo o pedido: uma única data não reconhecida rejeita todas as linhas, em vez de deixar um preenchimento retroativo parcial de entradas que só podem ser retiradas individualmente.
• As linhas não incluem anchor nem resIds de evidência — ambos são elementos de uma única afirmação. Utilize /declare nesses casos.
• /declare/batch é o caso de uma linha deste endpoint; continue a utilizá-lo quando se tratar realmente de uma única afirmação.

Este é o mesmo endpoint para o qual a importação CSV do próprio DICE publica. Se os seus clientes estiverem a preencher o histórico manualmente, em vez de o fazerem a partir de um sistema, encaminhe-os para Registar eventos passados em vez de criar uma integração.

Corrigir um erro

As entradas declaradas são imutáveis — não podem ser editadas nem eliminadas. A correção é uma retirada: uma segunda entrada atribuída que indica que a primeira estava errada. A original permanece no histórico assinalada como retirada, e ambas seguem com o registo para os proprietários subsequentes — errata, nunca eliminação.

Para retirar tudo o que um lote escreveu (por exemplo, se a receção de mercadorias tiver sido revertida no seu ERP), publique o operationId guardado:

curl -fsS "https://apid.dustid.io/api/v1/events/retract/by-operation" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "7c3f0f9e-5b7a-4a4f-8f7d-2f1d0e6a9b21",
    "reason": "Goods receipt reversed (movement type 102)."
  }'

Esta ação retira todas as entradas ainda ativas escritas pela operação — as entradas já retiradas individualmente são ignoradas — e requer acesso de edição a todos os Registos envolvidos. Em alternativa, uma entrada individual é retirada através do respetivo id de evento: POST /api/v1/events/{event_id}/retract, com um reason opcional. Os ids dos eventos são obtidos a partir do histórico do Registo (GET /api/v1/events?threadId=…).

Depois da retirada, registe uma entrada corrigida através de uma nova declaração — esse par, entrada errada mais correção, é a representação fiel do registo.

Cuidado

Uma Página pública publica um instantâneo, pelo que uma nova entrada ou uma retirada só chega à página quando esta é republicada. Quando o design da página utiliza a política de passaporte dinâmico, uma declaração ou retirada bem-sucedida volta a publicá-la automaticamente com base na versão que já apresenta. Caso contrário, a página continua a apresentar o instantâneo anterior, é indicada como estando desatualizada relativamente ao respetivo registo e é atualizada na publicação seguinte. Em qualquer dos casos, a afirmação retirada é apresentada rasurada e assinalada como retirada, em vez de desaparecer — a proveniência publicada nunca é reescrita silenciosamente.

Modos de falha

Resposta	Significado
400 INVALID_DATA	O valor edtf está fora do subconjunto suportado ou não corresponde a uma data de calendário real, a declaração está vazia ou um id de evidência não está anexado a esse Registo.
400 INVALID_REQUEST	Corpo malformado — por exemplo, um campo que excede o respetivo limite de comprimento.
403 ATTRIBUTION_REQUIRED	A política da Conta de Serviço exige um interveniente declarado e o pedido não incluiu nenhum.
404 NOT_FOUND	Um id de Registo que o autor da chamada não consegue ver ou que não existe. No endpoint de lote, basta um id nestas condições para que todo o lote falhe.

Os corpos dos erros seguem o contrato padrão — consulte Convenções dos pedidos e Erros e resultados de digitalização para conhecer todos os códigos, respetivos estados e orientações de repetição.

Próximos passos

• Autenticação e chaves de API — Contas de Serviço, troca de tokens e semântica do interveniente declarado.
• Erros e resultados de digitalização — o contrato completo de falhas, incluindo o comportamento de renovação para 401.
• Guia da API de Registos — resolver as séries e encomendas do seu sistema para ids de Registos.
• Registar eventos passados — a mesma funcionalidade tal como é apresentada aos seus operadores no DICE.
• Páginas públicas — como as entradas declaradas aparecem no passaporte público do item.