Referencia de integración

Conecta tus sistemas. Conserva el contexto.

Esta es la arquitectura objetivo de integración: consola y API aplicarían las mismas reglas. Los endpoints descritos no están disponibles en esta web; su implementación y validación se acuerdan en cada despliegue.

  • ERP / Gestión Catálogos y lotes
  • Calidad / Cumplimiento Señales y reportes
  • Producción / Etiquetado Impresión y activación
  • Analítica Exportación e informes
Esquema conceptual de integración

Alcance de la conexión

Definir. Conectar. Validar.

  1. Acordar el alcance

    Datos, responsables y permisos de cada sistema.

  2. Conectar la operación

    Emisión e impresión; activación al finalizar producción.

  3. Validar con evidencia

    Pruebas de lectura, datos y trazabilidad de cambios.

Emitir y activar

Son dos tiempos porque la fábrica funciona así: los códigos se imprimen mientras se produce, y los datos definitivos del lote solo existen cuando la corrida termina.

La operación conjunta de emisión y activación se contempla solo para producto cuya producción ya terminó, con impresión confirmada y ficha completa de lote y vencimiento. Conocer esos datos por adelantado no permite activar unidades antes de terminar la producción.

Emitir exige una cabecera de idempotencia. Un reintento por corte de red no genera una segunda tirada ni consume el saldo dos veces: devuelve exactamente la misma emisión.

Endpoints propuestos del ciclo de emisión
POST /v1/issuances
     Genera identificadores para un producto. Activación conjunta solo
     con producción finalizada, impresión confirmada y ficha completa.

POST /v1/issuances/{id}/activate
     Completa la ficha, que es lo que activa los códigos. Cuatro modos:
     rango declarado · límites escaneados · sesión de escaneo · total

POST /v1/issuances/{id}/reassign
     Corrige la ficha de un rango. Queda en auditoría.

GET  /v1/issuances/{id}/labels
     Descarga paginada, o continua para tiradas grandes.

Cuatro formas de activar, ordenadas por certeza

La asignación entre códigos y lote asume que la planta consumió las etiquetas en orden, y el mundo físico mezcla rollos. Por eso hay más de un método.

  • Rango declarado

    Se declara desde dónde hasta dónde, con su lote y su vencimiento. Funciona en plantas con consumo ordenado, bajo responsabilidad declarada.

  • Límites escaneados · recomendado

    Al abrir la corrida se lee la etiqueta de la primera unidad; al cerrarla, la de la última. El sistema deriva el rango realmente observado y absorbe los desfases y las mermas.

  • Sesión de escaneo

    Se abre una sesión para un lote y todo código leído durante ella queda asignado. La asignación deja de ser una suposición y pasa a ser una observación.

  • Auditoría de muestreo

    Como control de cierre de producción, se escanean unidades al azar de cada lote y se compara la ficha asignada con lo impreso. Las diferencias quedan para revisión del responsable.

Corregir la ficha es libre mientras el rango no tenga consultas públicas: el error se queda en fábrica. Si ya se consultó en el mercado, la corrección exige aprobación y abre un caso, porque el pasaporte ya mostró datos y el cambio debe ser defendible.

Consultar y vincular

En modo serial, un serial repetido dentro del mismo producto, o un segundo intento de vincular el mismo código, se rechaza y abre una señal. El índice inverso de serial a código es lo que después permite una garantía por unidad o una retirada quirúrgica.

La especificación completa se publica como OpenAPI, y la versión va en la ruta: lo que funciona hoy seguirá funcionando cuando aparezca la siguiente.

Endpoints de consulta y de modo serial
GET  /v1/verify/{code}
     Consulta pública: estado y pasaporte. Anónima, con límite de tasa.
     Prevista para integradores: farmacias y equipos de control.

GET  /v1/labels/{code}
     Consulta una etiqueta propia, con más detalle que la pública.

POST /v1/labels/bind
     Modo serial: vincula un código con el serial del fabricante, 1 a 1.

POST /v1/labels/void
     Anula rangos, con motivo. Queda en auditoría.

Webhooks: issuance.issued · label.alert

Cómo llega el resultado

Recibo de emisión
Emisión, rango, estado de la ficha, su referencia y una huella del contenido
La huella permite comprobar la integridad de lo que recibió la imprenta.
Su propia referencia
El número de orden o de corrida que usted use
Viaja en la emisión y es filtrable: la conciliación con su sistema de gestión es directa.
Descarga
CSV · XLSX · imágenes · PDF de imposición
Toda descarga queda en auditoría: las etiquetas son identidades unitarias.
Línea de producción
Lenguaje nativo de impresora térmica
Para etiquetar a la velocidad de la máquina, sin pasar por un PDF.
Correlativo visible
Un número por producto
Internamente el código lleva emisión y posición; en pantalla se habla en un correlativo que no se repite.

Identidades y permisos

La cuenta de un emisor autoriza la creación de identidades unitarias. La asimetría con el público es deliberada.

  • El público no tiene cuenta

    Consultar y preparar un reporte local no piden cuenta. Esta web permite descargar código, tipo y descripción, sin correo ni ubicación. No envía el reporte ni modifica el registro; entréguelo a la organización responsable.

  • La consola exige segundo factor

    Correo corporativo y contraseña con segundo factor obligatorio, y clave de acceso opcional para quien quiera resistencia a suplantación. Nadie entra con solo una contraseña.

  • Sin inicio de sesión social

    La identidad de un emisor es corporativa. Un correo personal no debe controlar una cuenta que emite.

  • Identidad de máquina

    Las integraciones usan clave de API con firma de la solicitud, alcances concretos y rotación. Revocable por clave y por dispositivo.

Qué sigue funcionando cuando algo falla

Un sistema de identificación no puede detener la producción ni el comercio. Eso deja de ser una aspiración y se convierte en un requisito de diseño.

  • Imprimir no depende de la conexión

    El rango se descarga una vez y el proceso local alimenta la impresora, con cola propia y reporte de consumo al reconectar.

  • La consulta pública y la emisión son planos separados

    La consulta debe seguir respondiendo aunque la emisión esté en mantenimiento. No comparten camino.

  • Abierto al leer, cerrado al escribir

    Si el limitador de tasa se degrada, la consulta se sirve. Las escrituras y la autenticación, al contrario, fallan cerradas.

Antes de integrar

El formato del identificador y las especificaciones de impresión están en la referencia de la etiqueta. Si quiere entender por qué el diseño toma estas decisiones, la página de precedentes recorre los sistemas que ya lo intentaron.

Ver la etiqueta y el código Por qué este diseño