Documentação da API

Introdução

A API do Urdume é uma API REST sobre HTTPS. Os pedidos levam JSON no corpo (Content-Type: application/json) e as respostas são sempre JSON. O envio de documentos usa multipart/form-data.

Endereço base

https://urdume.site/api/v1

• Todos os objetos têm "id" (identificador com 26 caracteres) e "object" (o tipo: product, batch, document, passport…).
• As datas são números inteiros em Unix time (segundos, UTC).
• Para alterar um objeto usa-se POST no endereço do objeto, só com os campos a mudar.
• Cada resposta traz o cabeçalho Request-Id: indique-o se precisar de ajuda do suporte.

Autenticação

Cada pedido leva uma chave secreta no cabeçalho Authorization. As chaves criam-se no painel, em Programadores, e o valor completo só é mostrado uma vez.

curl https://urdume.site/api/v1/products \
  -H "Authorization: Bearer sk_test_…"

• Chaves sk_live_ trabalham com os dados reais; chaves sk_test_ com dados de teste.
• A chave identifica a empresa: não é preciso (nem possível) indicar a empresa no pedido.
• Guarde as chaves no servidor (variáveis de ambiente). Nunca as coloque em código que corre no browser ou numa aplicação móvel.
• Se uma chave for exposta, revogue-a no painel e crie outra: a revogação é imediata.

Modo de teste

Com uma chave sk_test_ tudo funciona como em produção, mas sobre dados separados: os produtos, documentos e passaportes de teste nunca se misturam com os reais e não contam para os limites do plano.

• Todos os objetos têm "livemode": true nos dados reais e false nos de teste.
• A página pública de um passaporte de teste diz claramente que é um passaporte de teste, e não ocupa o endereço GS1 do produto.
• As chaves de teste funcionam em qualquer plano. As chaves de produção exigem um plano com API (Pro ou Enterprise).
• No painel, o interruptor "Dados de teste" mostra os dados criados em modo de teste.

Erros

Os erros usam os códigos HTTP habituais e um corpo JSON com o tipo, um código estável, uma mensagem para pessoas e, quando se aplica, o parâmetro em causa.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_value",
    "message": "Indique uma percentagem entre 0 e 100.",
    "param": "data.recycled_content"
  }
}

Programe a sua integração com base em "code" (estável) e não no texto de "message", que pode mudar.

Listas e paginação

As listas devolvem os objetos mais recentes primeiro, dentro de um objeto "list". Use "limit" (1 a 100, por omissão 10) e, para a página seguinte, "starting_after" com o id do último objeto recebido.

curl "https://urdume.site/api/v1/products?limit=50&starting_after=01J8Z…" \
  -H "Authorization: Bearer sk_test_…"

{
  "object": "list",
  "data": [ { "id": "01J8Y…", "object": "product", … } ],
  "has_more": true,
  "url": "/api/v1/products"
}

Idempotência

Para repetir um POST em segurança (por exemplo depois de uma falha de rede), envie o cabeçalho Idempotency-Key com um valor único criado por si, como um UUID. Durante 24 horas, repetir o mesmo pedido com a mesma chave devolve a resposta original, sem criar nada em duplicado.

curl https://urdume.site/api/v1/passports \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 6f1c1a52-8a0e-4c0e-9a57-2f6d1a3b9c10" \
  -H "Content-Type: application/json" \
  -d '{"product": "01J8Z…"}'

• As respostas repetidas trazem o cabeçalho Idempotent-Replayed: true.
• Usar a mesma chave com um pedido diferente dá 409 (idempotency_key_reused).
• Se o primeiro pedido ainda estiver a ser processado, a repetição recebe 409 (idempotency_key_in_use): tente de novo um pouco depois.

Limite de pedidos

Cada chave pode fazer até 100 pedidos por minuto. Acima disso a API responde 429 com o cabeçalho Retry-After (segundos a aguardar). Em importações grandes, espace os pedidos e respeite esse valor.

Produtos

Um produto é um modelo de artigo (por exemplo, "T-shirt básica, ref. TS-100"). Os dados do passaporte ficam em "data", com uma chave por campo do modelo de campos (ver Modelos de campos). Os valores escritos pela API ficam marcados no painel com a origem "API".

curl https://urdume.site/api/v1/products \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "T-shirt básica",
    "reference": "TS-100",
    "gtin": "4006381333931",
    "data": {
      "brand": "A Minha Marca",
      "country_making": "PT",
      "fibre_composition": [
        {"fibre": "cotton", "percent": 95},
        {"fibre": "elastane", "percent": 5}
      ]
    }
  }'

A resposta inclui "completeness": quantos campos obrigatórios estão preenchidos e quais faltam ("missing") para poder emitir o passaporte.

Lotes

Um lote é uma produção concreta de um produto. Pode ter valores próprios nos campos que o modelo define "por lote" (por exemplo a fábrica ou a data de fabrico), que se sobrepõem aos do produto no passaporte do lote.

Documentos

Envie fichas técnicas, faturas, certificados e relatórios de ensaio (PDF, JPEG, PNG ou WebP, até 20 MB). Os ficheiros ficam cifrados. Pode pedir logo a extração dos dados com IA.

curl https://urdume.site/api/v1/documents \
  -H "Authorization: Bearer sk_test_…" \
  -F "file=@ficha-tecnica.pdf" \
  -F "kind=tech_sheet" \
  -F "product=01J8Z…" \
  -F "extract=true"

• kind: tech_sheet (ficha técnica), invoice (fatura), certificate (certificado), test_report (relatório de ensaio), declaration (declaração) ou other.
• A extração corre em segundo plano: o documento passa por "status": "queued" e "processing" e termina em "review" (há sugestões para validar) ou "failed". Nessa altura recebe o webhook document.extracted (ou document.extraction_failed); em alternativa, consulte GET /documents/{id}.
• As sugestões da IA aparecem em "extraction.suggestions", com a confiança e a citação do documento.
• A API nunca aplica sugestões sozinha: uma pessoa com o papel Validador confirma os valores no painel, e só então passam para o produto.

Passaportes

Um passaporte é emitido para um produto (modelo) ou para um lote, quando todos os campos obrigatórios estão preenchidos. Cada versão publicada é imutável e tem o SHA-256 do seu conteúdo.

Se faltarem campos obrigatórios, a resposta é 400 com o código passport_missing e a lista dos campos em falta na mensagem.

Artigos (números de série)

Um artigo é uma peça concreta, com o seu número de série, o seu endereço e o seu QR Code, por baixo do passaporte de um modelo ou de um lote. Mostra o conteúdo desse passaporte e o histórico da própria peça. Os artigos não têm versões: quando o passaporte recebe uma versão nova, todas as peças a mostram.

curl https://urdume.site/api/v1/passports/01J8Z…/items \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: producao-2027-03-lote-7" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 500, "prefix": "TS24-"}'

{
  "object": "item_run",
  "id": "01J9A…",
  "passport": "01J8Z…",
  "created_count": 500,
  "first_serial": "TS24-000001",
  "last_serial": "TS24-000500",
  "items_url": "/api/v1/passports/01J8Z…/items?run=01J9A…"
}

• A série é única por produto, sem distinguir maiúsculas de minúsculas. Se alguma já existir, nada é criado (409, serial_taken).
• Cada artigo tem "url": o endereço a gravar no QR Code e no NFC dessa peça. Com GTIN, segue o GS1 Digital Link (/01/{gtin}/21/{série}).
• Os artigos criados por mês contam para o limite do plano. Em modo de teste não contam, mas há um teto de 1000 por mês.
• Use sempre Idempotency-Key ao criar séries geradas: repetir o pedido sem ela cria outra série.

Eventos pós-venda

Reparações, revendas e reciclagem, registadas numa peça (artigo) ou num passaporte de modelo ou lote. Os eventos publicados aparecem na página pública. O conteúdo de um evento não pode ser alterado nem apagado: um erro corrige-se anulando o evento.

• Os eventos registados por parceiros com link (reparadores, recicladores…) e por consumidores na página pública (se a empresa ligar essa opção em Definições › Empresa) chegam com "status": "pending" e só ficam públicos depois de aprovados por uma pessoa, no painel. Recebe o webhook lifecycle_event.recorded quando chegam.
• "source" diz quem registou: "brand" (painel), "api", "third_party" (parceiro com link) ou "consumer" (quem tem a peça, na página pública; fica sempre "pending").
• Os anexos nunca aparecem em público: a página e o JSON públicos dizem só se o evento tem comprovativo ("evidence"). Um anexo apagado no painel fica com "removed": true e o conteúdo deixa de existir.

Sessões alojadas (como o Stripe Checkout)

A forma mais simples de ligar a sua loja: o seu servidor cria uma sessão para uma referência, indicando quem vai preencher ("operator"), e abre o endereço "url" num separador. É uma página própria do Urdume, como o Stripe Checkout: sem conta Urdume e sem o painel, só com os passos para completar os dados, emitir o passaporte e levar o QR Code. No fim, a pessoa carrega em "Concluir e voltar" e regressa ao "success_url". O seu site não precisa de guardar nada: o passaporte fica sempre em "public_url".

Criar a sessão e abrir "url" (redirecionamento ou novo separador)

curl https://urdume.site/api/v1/passport_sessions \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "TS-100",
    "name": "T-shirt básica",
    "operator": {"name": "Ana Silva", "email": "ana@loja.exemplo.pt"},
    "success_url": "https://loja.exemplo.pt/admin/produto/100?dpp={SESSION_ID}",
    "cancel_url": "https://loja.exemplo.pt/admin/produto/100",
    "serials": ["TS100-01", "TS100-02"]
  }'

{
  "id": "01J9C…",
  "object": "passport_session",
  "status": "open",
  "url": "https://urdume.site/sessao/01J9C…/x7Kq…",
  "operator": {"name": "Ana Silva", "email": "ana@loja.exemplo.pt"},
  "reference": "TS-100",
  "public_url": "https://urdume.site/r/a-sua-marca/TS-100",
  "passport": null,
  "expires": 1790086400
}

• O "url" é um segredo: abra-o só para a pessoa indicada em "operator" (redirecionamento ou novo separador; nunca o mostre em páginas públicas nem o envie por email). Fica preso ao primeiro browser que o abre e deixa de funcionar quando a sessão termina.
• A sessão conclui-se uma vez, quando o passaporte fica emitido (ou atualizado). GET /passport_sessions/{id} devolve o estado (open, completed ou expired) e "outcome": issued (passaporte novo), version (nova versão) ou unchanged (os dados já estavam publicados).
• Ao concluir recebe o webhook passport_session.completed, com "passport", "passport_url", "outcome" e "items_created". Use-o para atualizar o seu sistema mesmo que a pessoa feche o separador sem voltar.
• Emitir exige uma pessoa identificada: a página pede a quem preenche que confirme os dados em nome da sua empresa, e o registo de atividade guarda o nome indicado em "operator".

Endereço pela referência

Cada empresa tem um identificador público (ver Programadores). O passaporte de um produto fica sempre em /r/{identificador}/{referência} e o de uma peça em /r/{identificador}/{referência}/{série}. O Urdume reencaminha para a página pública do passaporte. Use estes endereços no seu site, nos QR Codes e no NFC: não mudam e não obrigam a guardar IDs do Urdume.

O seu identificador: GET /account

curl https://urdume.site/api/v1/account -H "Authorization: Bearer sk_test_…"

{
  "object": "account",
  "name": "A Sua Marca, Lda.",
  "handle": "a-sua-marca",
  "reference_url": "https://urdume.site/r/a-sua-marca/"
}

Exemplos

https://urdume.site/r/a-sua-marca/TS-100
https://urdume.site/r/a-sua-marca/TS-100/TS100-01
https://urdume.site/r/a-sua-marca/TS-100?modo=teste

• A referência pode ter letras, números, ".", "_", "~" e "-" (até 80). Referências com outros caracteres não têm endereço curto.
• Enquanto o passaporte não for emitido, o endereço responde 404.
• "?modo=teste" procura nos dados de teste (criados com chaves sk_test_).

Portal incorporável

Mostre o estado de um produto dentro do seu ERP ou PLM, sem a sua equipa mudar de aplicação: os dados que faltam para o passaporte, os documentos (com envio de ficheiros) e os passaportes emitidos. O seu servidor cria uma sessão curta para um produto; a sua página embute o componente do Urdume com o client_secret dessa sessão.

1. No seu servidor: criar a sessão

curl https://urdume.site/api/v1/portal_sessions \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"product": "01J8Z…", "origin": "https://erp.a-sua-empresa.pt"}'

{
  "id": "01J9B…",
  "object": "portal_session",
  "product": "01J8Z…",
  "origin": "https://erp.a-sua-empresa.pt",
  "allow_upload": true,
  "client_secret": "ps_01J9B…_secret_…",
  "url": "https://urdume.site/embed/01J9B…",
  "expires": 1790003600
}

2. Na sua página: embutir o componente

<div id="urdume"></div>
<script src="https://urdume.site/assets/js/urdume-embed.js"></script>
<script>
  // "session" é a resposta do passo 1, entregue pelo seu servidor a esta página
  Urdume.mount('#urdume', { url: session.url, clientSecret: session.client_secret });
</script>

• A sessão dura 60 minutos e serve só para esse produto. Crie uma nova em cada carregamento da sua página.
• Crie a sessão sempre no servidor: a chave sk_… nunca pode chegar ao browser. O client_secret pode, porque só dá acesso a este produto e por pouco tempo.
• Sem o carregador, pode criar o iframe à mão com o endereço "url" seguido de "#" e do client_secret.
• O componente não valida sugestões da IA nem emite passaportes: esses passos exigem uma pessoa identificada e fazem-se no Urdume (o componente tem o link).
• Os documentos enviados pelo componente ficam registados como vindos da API.

Modelos de campos

GET /templates devolve os modelos de campos disponíveis, com os grupos, as chaves, os tipos e as opções de cada campo. Use-o para saber que chaves pode enviar em "data" e que valores são aceites.

Webhooks

Em vez de perguntar à API se algo mudou, registe um endereço HTTPS no painel (Programadores › Webhooks) e o Urdume envia-lhe um pedido POST sempre que acontece um dos eventos que escolheu.

O que o seu sistema recebe

POST /webhooks/urdume HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: Urdume-Webhooks/1.0
Urdume-Signature: t=1790000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Urdume-Event-Id: 01J8ZK3V6W9QX4T2M7N5B1C0DE
Urdume-Event-Type: passport.issued
Urdume-Delivery-Id: 01J8ZK3V7A2B3C4D5E6F7G8H9J

{
  "id": "01J8ZK3V6W9QX4T2M7N5B1C0DE",
  "object": "event",
  "type": "passport.issued",
  "api_version": "v1",
  "created": 1790000000,
  "livemode": true,
  "data": { "object": { "id": "01J8Z…", "object": "passport", … } }
}

Confirme sempre a assinatura antes de confiar no conteúdo. O cabeçalho Urdume-Signature traz o momento do envio (t) e a assinatura (v1): o HMAC-SHA256, com o segredo do endereço (whsec_…), do texto "t" + "." + corpo do pedido tal como foi recebido.

Verificar a assinatura (PHP)

<?php
$secret = getenv('URDUME_WEBHOOK_SECRET');            // whsec_…
$body = file_get_contents('php://input');                 // o corpo exato, antes de qualquer json_decode
$header = $_SERVER['HTTP_URDUME_SIGNATURE'] ?? '';

$parts = [];
foreach (explode(',', $header) as $part) {
    [$key, $value] = array_pad(explode('=', $part, 2), 2, '');
    $parts[$key] = $value;
}
$timestamp = (int) ($parts['t'] ?? 0);
$expected = hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (abs(time() - $timestamp) > 300 || !hash_equals($expected, $parts['v1'] ?? '')) {
    http_response_code(400);                               // assinatura inválida ou pedido antigo
    exit;
}

$event = json_decode($body, true);
// … guardar $event['id'] e tratar o evento (de preferência em segundo plano) …
http_response_code(200);

Verificar a assinatura (Node.js)

const crypto = require('crypto');

// body: o corpo em bruto (Buffer ou string), não o objeto já interpretado
function verify(body, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${body}`).digest('hex');
  const recent = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || '');
  return recent && a.length === b.length && crypto.timingSafeEqual(a, b);
}

• Responda com um código 2xx em menos de 10 segundos. Trate o evento depois de responder, se demorar.
• Qualquer outra resposta (incluindo redirecionamentos, que não são seguidos) conta como falha. Repetimos até 8 vezes, com intervalos crescentes: 1 min, 5 min, 30 min, 2 h, 5 h, 10 h e 24 h.
• O mesmo evento pode chegar mais do que uma vez: guarde o "id" dos eventos já tratados e ignore as repetições.
• A ordem de chegada não é garantida. Se precisar do estado atual, leia o objeto pela API.
• Recuse pedidos com o momento (t) a mais de 5 minutos da hora atual: impede que um pedido capturado seja reenviado mais tarde.
• O endereço tem de ser HTTPS e público. Endereços de redes internas são recusados.
• Se muitas entregas seguidas esgotarem todas as tentativas, o endereço é desligado e fica assinalado no painel. No painel pode ver cada entrega, reenviá-la e enviar um evento de teste ("ping").
• Os endereços de produção só recebem eventos dos dados reais; os de teste, dos dados de teste.