Do rolo à leitura

Primeiros passos

1. Peça etiquetas para nós. Diga quantas unidades e para qual produto. Do painel você mesmo pode registrar o pedido: ele chega até nós, geramos os códigos e mandamos imprimir.
2. Cadastre o produto e o lote. Enquanto a impressão corre. Nome, apresentação, número do lote e validade se for o caso.
3. Receba o rolo e confirme. Marcar como recebido é o que coloca o rolo sob a sua custódia, e registra quando.
4. Aplique e ative. Você aplica as etiquetas no envase e ativa a faixa no painel. Até esse momento nenhuma daquelas unidades autentica.
5. Acompanhe as leituras. Aparecem ao vivo, com país, estado e horário. Os alertas se geram sozinhos.

A ordem do passo 4 importa: ativar antes de aplicar significa que um rolo perdido no caminho tem unidades que autenticam. Ative quando a etiqueta já estiver no produto.

O que o comprador vê

Ele escaneia o QR com a câmera do celular e abre uma página no navegador. Não há aplicativo para instalar e nenhum dado é pedido. A página pesa menos de 30 KB para carregar na gôndola com um traço de sinal.

Rolos e etiquetas

Os códigos são gerados por nós e viajam cifrados até a gráfica. Você nunca precisa manipular um arquivo com milhões de códigos, e quem imprime nunca vê a que cliente pertencem: o código não leva a marca dentro.

Cada rolo traz uma faixa de séries e um estado. O estado é o que se audita quando algo não fecha.

Se um rolo for roubado, marque como roubado no painel. Todas as suas unidades deixam de autenticar na hora, inclusive as já ativadas, e cada tentativa de verificá-las fica registrada com país e horário — que é como se rastreia por onde saíram.

Produtos, lotes e ativação

Um produto é o que você vende; um lote é uma corrida de produção desse produto; uma unidade é uma embalagem com a sua etiqueta. Alertas, recall e relatórios trabalham sobre o lote, então vale manter o lote do painel igual ao do seu sistema de produção.

A ativação é feita de três formas, todas pelo painel:

• Por faixa — da série X à Y. É o normal quando se consome um rolo inteiro.
• Por rolo — a faixa completa de um rolo recebido, em um clique.
• Por unidade — para reposições e amostras.

Cada ativação fica no registro de auditoria com quem fez e quando. Esse registro é encadeado por hash: não dá para editar depois sem que apareça, que é exatamente o que um auditor pede.

Recall de lote

Você marca o lote como recolhido e a próxima leitura de qualquer unidade dele mostra o alerta sanitário no lugar de "produto verificado". Leva segundos para propagar no mundo todo e não exige reimprimir nem recolher nada.

É reversível: se o recall foi preventivo e é suspenso, o lote volta a verificar normalmente. As duas operações ficam auditadas.

Anomalias e casos

São onze regras olhando o fluxo de leituras. As que mais disparam na prática:

• Releitura — uma mesma unidade verificada muitas vezes, sobretudo de lugares diferentes.
• Impossibilidade geográfica — duas leituras tão distantes que ninguém poderia ter viajado entre elas.
• Desvio de território — produto destinado a um mercado aparecendo em outro. É vazamento de canal, não falsificação, e os dois se distinguem.
• Rajada de lote — um pico de leituras concentrado num lote e numa região.
• Rolo roubado — qualquer tentativa sobre uma faixa denunciada.

Cada alerta chega com a evidência —quais unidades, onde, quando— e pode virar um caso: com responsável, notas, anexos e uma resolução ao fechar. O caso é o que depois se mostra a um advogado, à aduana ou a um distribuidor.

Usuários e papéis

Os dados de cada marca ficam isolados no banco, não na aplicação: mesmo que um erro de programação pedisse dados de outra empresa, o banco não devolveria.

API

Verificação pública. É a mesma que a página do QR usa. Não leva autenticação —precisa funcionar do celular de qualquer comprador— e não revela a que marca o código pertence.

GET https://xyvona.com/api/v/K7M2QX9J4TB8WNPC5RDA

{
  "result": "genuine",
  "message": "Producto verificado.",
  "product_id": 412,
  "batch_id": 88
}

Quando a unidade já foi vista antes, a resposta acrescenta first_seen e first_country. Quando não verifica, o corpo é só result e message: não se vaza se o código não existe, se não está ativado ou se o rolo foi roubado, porque essa diferença é exatamente o que um falsificador precisa para calibrar.

API do painel. Tudo o que o painel faz tem endpoint. Autentica com uma chave que você gera, com escopo próprio, exibida uma única vez.

curl https://xyvona.com/capi/api/v1/batches \
  -H "X-API-Key: $XYVONA_API_KEY"

Guarde a chave assim que for gerada: não a mostramos de novo e não conseguimos recuperá-la. Se perder, ela é revogada e outra é emitida — que é o que deve acontecer quando uma credencial some.

Webhooks

Você registra uma URL e avisamos quando um alerta é gerado, filtrando por severidade mínima e por tipo. As retentativas usam espera crescente e cada entrega fica registrada, para consultar quando a sua equipe disser "não chegou nada".

POST https://tu-sistema.com/hooks/xyvona
X-Xyvona-Signature: t=1755820800,v1=9f86d081...

{
  "version": 1,
  "type": "alert.created",
  "tenant_id": 7,
  "alert": {
    "alert_type": "geo_impossible",
    "severity": "high",
    "severity_level": 4,
    "status": "open",
    "unit_id": 90210,
    "batch_id": 88,
    "created_at": "2026-08-21T14:03:11+00:00",
    "evidence": { "km": 8410, "hours": 1.5 }
  }
}

Verifique a assinatura antes de confiar no corpo: é HMAC-SHA256 sobre «timestamp.corpo» com o segredo que damos ao registrar a URL. Rejeite o que chegar com mais de cinco minutos e compare a assinatura em tempo constante.

Dados, exportação e retenção

• Os dados são seus. Leituras, unidades, lotes, alertas e casos se exportam em CSV quando você quiser, sem pedir por e-mail.
• Geolocalização, IP e impressão digital do dispositivo são apagados em 90 dias. Não é configurável: é requisito legal.
• O IP nunca é guardado em claro. É usado para resolver o país e substituído por um hash com sal rotativo antes de qualquer escrita.
• O código completo nunca aparece num registro. Nem no nosso, nem no que você exporta.
• Tudo trafega e é armazenado cifrado, em infraestrutura com certificação internacional de segurança da informação, com chaves próprias da XYVONA e cópias de resguardo.
• Em farmacêutica o portal do comprador vem desligado e não pode ser ligado: associar uma pessoa identificada aos medicamentos que ela escaneou é dado de saúde.

Falta algo aqui?

Escreva para nós e acrescentamos. Se você fez a pergunta, outra pessoa está fazendo também.