APIs e JSON para RAIN RFID: como projetar uma arquitetura de resolução de EPC/CIN em logística

Blog
alexconnect.io

Veja exemplos práticos de JSON e APIs para decodificar e resolver EPC/CIN em RAIN RFID, integrando leitores, middleware, WMS/TMS/ERP e rastreio de ativos, pacotes e itens.

1. Introdução: por que projetar bem as APIs de resolução EPC/CIN

Em projetos com RAIN RFID, não basta apenas ler o EPC da tag: é preciso ter uma arquitetura de APIs e payloads JSON bem definida para transformar leituras brutas em contexto de negócio útil para logística, WMS, TMS e ERP.

No contexto do RAIN Alliance ISO Numbering System, o CIN (Company Identification Number) é o identificador da empresa ou entidade dona da numeração, enquanto o AFI 0xAE combinado com o Toggle bit para ISO indica que a tag está usando o sistema ISO definido pela RAIN. O CIN pode ser codificado em EBV‑8, ocupando de 1 a 4 bytes, e o restante do EPC/UII carrega os dados da aplicação (serviço, timestamp, códigos de origem/destino, IDs de ativos, etc.).

Esse cenário exige um desenho cuidadoso das APIs responsáveis por:

  • Receber as leituras brutas dos leitores
  • Fazer a decodificação técnica de EPC/CIN
  • Resolver o EPC para uma entidade de negócio (pacote, RTI, item serializado)
  • Manter um histórico de eventos para auditoria e rastreabilidade

2. Modelo lógico: os 4 blocos de uma boa arquitetura EPC/CIN

Uma arquitetura robusta de RAIN RFID com CIN costuma separar claramente quatro responsabilidades:

  1. Leitura bruta da tag
  2. Decodificação técnica (EPC, CIN, AFI, campos de aplicação)
  3. Resolução de negócio (mapear EPC → pacote, RTI, item, etc.)
  4. Histórico de eventos (timeline de leituras e mudanças de estado)

Essa separação é essencial porque a memória EPC é limitada e, como a própria documentação da RAIN destaca, ela normalmente leva apenas uma combinação compacta de CIN + campos de aplicação, e não todo o contexto logístico completo. O “resto da história” precisa vir do backend.

3. JSON de leitura bruta: o que vem do leitor/middleware

O primeiro payload relevante é o da leitura bruta, exatamente como gerado pelo leitor ou por um middleware próximo ao edge. O ideal é que esse payload inclua:

  • EPC/UII em hexadecimal (epcHex)
  • PC Word (pcWordHex)
  • CRC, antena, RSSI, timestamp, site, reader, zona, etc.

O PC Word ajuda a confirmar o comprimento de EPC, a presença de User Memory, o uso de features avançadas e, principalmente, se é tag ISO com AFI 0xAE

{
  "eventId": "01JQ2Q9N6Z2Q8M8Q9X2W3D4E5F",
  "eventType": "rfid.read",
  "timestamp": "2026-04-17T18:43:12.481Z",
  "siteId": "sp-hub-01",
  "readerId": "fx9600-doca-03",
  "antennaPort": 2,
  "readZone": "dock_outbound_03",
  "tag": {
    "epcHex": "45AE0CA50661200ECC21394A123ABC456DEF",
    "pcWordHex": "45AE",
    "crcHex": "7A91",
    "rssi": -49,
    "seenCount": 3
  }
}

Esse é o insumo que será consumido pela sua API de decodificação técnica.

4. JSON de decodificação técnica: EPC, CIN, AFI e campos de aplicação

No padrão ISO da RAIN Alliance, é crítico reconhecer que a tag está usando esse esquema, o que é feito via:

  • Toggle bit (T) = 1 → indica uso ISO
  • AFI = 0xAE → indica o sistema de numeração ISO da RAIN

A partir daí, você decodifica o CIN (em EBV‑8) e os campos de aplicação. No caso logístico de pacotes, a própria RAIN apresenta um exemplo com:

  • CIN 8 bits
  • Service level 8 bits
  • Timestamp 24 bits
  • Origin code 20 bits
  • Destination code 20 bits
  • Package identifier 48 bits

Um payload de decodificação técnica pode ficar assim:

{
  "decodeId": "dec_01JQ2QA3Y0S2A7K8R9P0M1N2B3",
  "status": "decoded",
  "tagScheme": {
    "standardFamily": "RAIN_ISO",
    "toggleBit": 1,
    "afiHex": "AE",
    "pcWordHex": "45AE",
    "epcLengthBits": 128
  },
  "cin": {
    "valueDecimal": 12,
    "valueHex": "0C",
    "encoding": "EBV-8",
    "issuingAgency": "RAIN Alliance"
  },
  "applicationData": {
    "profile": "parcel-v1",
    "serviceLevelHex": "A5",
    "timestampMinutes": 418080,
    "originCode": 60610,
    "destinationCode": 80202,
    "packageIdHex": "123ABC456DEF"
  },
  "raw": {
    "epcHex": "45AE0CA50661200ECC21394A123ABC456DEF"
  }
}

5. JSON de resolução de negócio: EPC → pacote, RTI ou item

Depois da decodificação técnica, o passo seguinte é a resolução de negócio: mapear o EPC/CIN para uma entidade real do seu domínio, como um pacote, um ativo retornável ou um item serializado.

Isso é importante porque:

  • A tag não comporta informações extensas como endereço completo ou todos os dados de pedido
  • A documentação da RAIN destaca que a memória EPC típica é limitada, embora seja suficiente para garantir unicidade em grandes volumes de itens

Um JSON de resolução de negócio pode ser:

{
  "resolutionId": "res_01JQ2QB8A7R6Y5N4M3K2J1H0G9",
  "status": "resolved",
  "entityType": "parcel",
  "entityId": "PKG-2026-04-17-000918273",
  "ownership": {
    "cin": 12,
    "namespaceOwner": "Alex Connect Logistics",
    "trustedNamespace": true
  },
  "businessContext": {
    "shipmentId": "SHP-90817263",
    "orderId": "ORD-550019",
    "serviceLevel": "overnight",
    "originFacility": "SP-GRU-01",
    "destinationFacility": "BR-REC-02",
    "currentStatus": "outbound_sorted"
  },
  "lastKnownRead": {
    "timestamp": "2026-04-17T18:43:12.481Z",
    "siteId": "sp-hub-01",
    "readerId": "fx9600-doca-03",
    "zone": "dock_outbound_03"
  }
}

6. API de decodificação: separando técnica de negócio

Uma boa prática é expor uma API específica para decodificação técnica, separada da resolução de negócio. Essa API:

  • Recebe EPC + PC Word (e opcionalmente contexto do leitor)
  • Devolve CIN, AFI, esquema e campos estruturados de aplicação

Endpoint sugerido

POST /api/v1/rain/decode

Request

{
  "epcHex": "45AE0CA50661200ECC21394A123ABC456DEF",
  "pcWordHex": "45AE",
  "readerContext": {
    "readerId": "fx9600-doca-03",
    "siteId": "sp-hub-01"
  }
}

Response

{
  "status": "ok",
  "scheme": "RAIN_ISO",
  "afiHex": "AE",
  "toggleBit": 1,
  "cin": {
    "valueDecimal": 12,
    "encoding": "EBV-8"
  },
  "fields": {
    "profile": "parcel-v1",
    "serviceLevelHex": "A5",
    "timestampMinutes": 418080,
    "originCode": 60610,
    "destinationCode": 80202,
    "packageIdHex": "123ABC456DEF"
  }
}

7. API de resolução: enriquecendo com WMS, TMS e ERP

A API de resolução consome a saída da decodificação e busca o contexto completo em WMS, TMS, ERP ou master data. Esse padrão é muito comum em arquiteturas reais, já que o EPC serve como chave compacta e rastreável, enquanto o resto do contexto vem do backend.

Endpoint sugerido

POST /api/v1/rain/resolve

Request

{
  "epcHex": "45AE0CA50661200ECC21394A123ABC456DEF",
  "pcWordHex": "45AE",
  "siteId": "sp-hub-01",
  "readTimestamp": "2026-04-17T18:43:12.481Z"
}

Response

{
  "status": "ok",
  "entityType": "parcel",
  "entityId": "PKG-2026-04-17-000918273",
  "cin": 12,
  "namespaceOwner": "Alex Connect Logistics",
  "routing": {
    "serviceLevel": "overnight",
    "origin": "SP-GRU-01",
    "destination": "BR-REC-02"
  },
  "businessState": {
    "shipmentId": "SHP-90817263",
    "customerId": "CUST-2201",
    "status": "outbound_sorted"
  }
}

8. API de associação: commissionar tags e evitar EPC órfão

Para evitar EPCs órfãos ou associações erradas, vale muito a pena ter um endpoint explícito de commissioning/association. Esse endpoint é especialmente importante para:

  • Ativos retornáveis (RTIs)
  • Itens duráveis (equipamentos, ferramentas, leitores, etc.)

Nesses casos, a associação entre tag e item precisa ser controlada, auditável e versionada.

Endpoint sugerido

POST /api/v1/rain/associations

Request

{
  "entityType": "returnable_asset",
  "entityId": "RTI-CRATE-000445991",
  "tag": {
    "epcHex": "41AE01E2404142595A313233343536303030",
    "pcWordHex": "41AE"
  },
  "cin": 123456,
  "associationMode": "commissioning",
  "performedBy": {
    "userId": "u_102",
    "stationId": "enc-station-07"
  },
  "metadata": {
    "assetType": "plastic_crate",
    "poolId": "pool-sudeste",
    "customerId": "cust-884"
  }
}

Response

json{
  "status": "associated",
  "associationId": "assoc_01JQ2QG18B6X5Y4Z3W2V1U0T9S",
  "entityType": "returnable_asset",
  "entityId": "RTI-CRATE-000445991",
  "tagState": "active",
  "version": 1,
  "associatedAt": "2026-04-17T18:46:55.000Z"
}

9. API de histórico: trilha completa do EPC

Leitores RAIN RFID geram muitos eventos ao longo da jornada de um pacote ou ativo. Uma API de histórico de EPC é extremamente útil para:

  • Auditoria
  • Cálculo de dwell time
  • Reconstrução de rotas logísticas

Endpoint sugerido

GET /api/v1/rain/tags/{epcHex}/history

Response

{
  "epcHex": "45AE0CA50661200ECC21394A123ABC456DEF",
  "entityType": "parcel",
  "entityId": "PKG-2026-04-17-000918273",
  "events": [
    {
      "timestamp": "2026-04-17T16:10:11.000Z",
      "type": "commissioned",
      "siteId": "sp-sorter-01",
      "details": {
        "stationId": "print-encode-02"
      }
    },
    {
      "timestamp": "2026-04-17T17:02:08.000Z",
      "type": "read",
      "siteId": "sp-sorter-01",
      "zone": "induction_lane_04"
    },
    {
      "timestamp": "2026-04-17T18:43:12.481Z",
      "type": "read",
      "siteId": "sp-hub-01",
      "zone": "dock_outbound_03"
    }
  ]
}

10. Estrutura JSON para RTIs (ativos retornáveis)

Em ativos retornáveis, é muito importante separar:

  • O ID permanente do ativo (quem é o pallet, caixa, rack)
  • Do ciclo logístico atual (em que viagem, cliente, pool, status ele está agora)

Isso evita confundir a identidade do ativo com a viagem corrente.

{
  "entityType": "returnable_asset",
  "entityId": "RTI-PALLET-0000098211",
  "identity": {
    "cin": 123456,
    "assetClass": "pallet_plastico",
    "serial": "0000098211"
  },
  "lifecycle": {
    "status": "in_transit",
    "poolId": "pool-nacional-01",
    "currentTripId": "TRIP-2026-004881",
    "currentCustomerId": "CUST-1039"
  },
  "tagBinding": {
    "epcHex": "41AE01E24050414C4C455430303938323131",
    "pcWordHex": "41AE",
    "boundAt": "2026-03-12T14:22:00Z",
    "bindingVersion": 4
  }
}

11. Estrutura JSON para item serializado (IT, ferramentas, etc.)

Quando o item é unitário e tem vínculo com ERP, inventário ou manutenção, faz sentido expor também a chave mestra do ativo e atributos de suporte.

{
  "entityType": "serialized_item",
  "entityId": "ASSET-IT-0029188",
  "identity": {
    "cin": 12345678,
    "assetId": "ABC123",
    "macAddress": "00-14-22-01-2C-45"
  },
  "masterData": {
    "category": "handheld_reader",
    "manufacturer": "ExampleTech",
    "model": "R6X",
    "ownerDepartment": "operacoes"
  },
  "tagBinding": {
    "epcHex": "45AEBC614E414243313233001422012C45",
    "pcWordHex": "45AE"
  }
}

12. Boas práticas ao projetar APIs EPC/CIN

Para fechar, algumas boas práticas importantes ao desenhar suas APIs para RAIN RFID com CIN:

  • Use epcHex como chave técnica, mas evite usá-lo como chave primária visível ao usuário final, mantendo a liberdade para evoluir o esquema de codificação.
  • Armazene sempre o pcWordHex, pois ele ajuda a validar comprimento, distinguir ISO vs GS1 e identificar o AFI utilizado.
  • Separe APIs de decode, resolve e associate para simplificar versionamento, troubleshooting e escalabilidade.
  • Versione o perfil de bits, usando campos como profile: "parcel-v1" ou "rti-v2", já que o mesmo CIN pode suportar múltiplos esquemas internos ao longo do tempo.
  • Em closed-loop logistics, o sistema ISO da RAIN é indicado justamente para casos como asset tracking e logística fechada onde não há padrão GS1 aplicável.

Key Takeaways

  • CIN + AFI 0xAE + Toggle bit ISO indicam o uso do sistema ISO da RAIN Alliance, no qual o CIN pode ser codificado em EBV‑8 e o restante do EPC carrega dados de aplicação.
  • Uma arquitetura bem pensada separa leitura bruta, decodificação técnica, resolução de negócio e histórico de eventos, respeitando o espaço limitado da memória EPC
  • Exemplos de JSON e APIs para decode, resolve, associations e history ajudam a integrar RAIN RFID a WMS, TMS e ERP de forma limpa e escalável.
  • Para RTIs e itens serializados, é fundamental separar identidade permanente, ciclo de vida e binding de tag, garantindo rastreio confiável ao longo dos anos.
  • Boas práticas como versionar perfis (ex.: parcel-v1) e usar o sistema ISO da RAIN em closed-loop logistics tornam sua solução mais aderente às recomendações oficiais da RAIN Alliance.

Conteúdo relacionado:

  1. RAIN CIN na logística: como usar o padrão RAIN RFID ISO para identificar ativos retornáveis, pacotes e itens
  2. Portais RFID Integrados: A Chave para uma Logística Inteligente
  3. Desbloqueando A Eficiência Na Logística E Supply Chain Com RAIN RFID: 11 – Boas Práticas em Projetos de RFID para Logística e Cadeia de Suprimentos
  4. Como a tecnologia RFID é usada no Milk Run para otimizar a Cadeia de Suprimentos
  5. Como Alterar o Tamanho do Dado Gravado na Memória EPC da Etiqueta RFID Usando ZPL
  6. Como Listar Recursivamente o Conteúdo de Arquivos e Diretórios Usando o Prompt de Comando no Windows
  7. NBIoT: Uma tecnologia revolucionária que está transformando os setores
  8. Wireshark e tcpdump: uma dupla poderosa
  9. Padrões de Codificação GTIN e SGTIN: Uma Visão Geral
  10. Desbloqueando A Eficiência Na Logística E Supply Chain Com RAIN RFID: 7 – Expedição de Produtos do Centro de Distribuição para Lojas