Guía para integración

una guía práctica para trabajar con listas a través de la api las listas te permiten mantener conjuntos reutilizables de valores — emails, identificaciones, teléfonos, números de tarjeta o texto libre — que tu cuenta usa para tomar decisiones (por ejemplo, listas de permitidos / bloqueados para reglas de riesgo, o conjuntos de opciones para formularios) ideas clave una lista pertenece a tu cuenta sólo ves y modificás tus propias listas cada lista tiene un tipo (email, identificación, teléfono, número de tarjeta, texto, otros) el tipo define cómo se limpian y comparan los valores los ítems son los valores dentro de una lista cada ítem puede llevar una label (etiqueta) opcional, un objeto data libre, tu propia reference y un expiresat opcional las referencias son tu clave de idempotencia si enviás una reference que vos controlás, podés reintentar sin crear duplicados los números de tarjeta nunca se guardan al agregar una tarjeta sólo se conserva una huella segura más {bin, last4, length} — el número completo se descarta los borrados son reversibles por diseño eliminar un ítem lo marca como borrado; no se elimina físicamente autenticación cada request se autentica con tus credenciales de api, enviadas como headers header valor x api key tu api key x access token tu access token content type application/json (para requests post) las operaciones aplican a la cuenta asociada a tus credenciales en los ejemplos de abajo, reemplazá la url base de la api que te provea tu plataforma si usás una integración con marca propia tipos de lista tipo para qué usarlo cómo se normalizan los valores email direcciones de email trim y minúsculas identification identificaciones / documentos trim y minúsculas phone teléfonos sólo dígitos card number números de tarjeta se guarda una huella segura + {bin, last4, length}; el número completo nunca se conserva text texto libre trim entity listas de entidades comercios o tarjeta habientes trim other cualquier otra cosa se guarda tal cual se envía como los valores se normalizan, no necesitás pre‑formatearlos — enviar " foo\@example com " a una lista email guarda y compara foo\@example com endpoints path base /p/list todas las respuestas usan el envoltorio { "result" true|false, "data" } obtener tus listas \# todas tus listas activas curl https //api sugaway com/p/list \\ h "x api key $api key" h "x access token $access token" # sólo listas de un tipo curl "https //api sugaway com/p/list?type=email" \\ h "x api key $api key" h "x access token $access token" { "result" true, "data" \[ { "uid" "list\ ab12cd", "name" "emails bloqueados", "type" "email", "reference" "emails bloqueados", "status" "active", "updated" "2026 06 15t12 00 00 000z", "created" "2026 06 01t09 00 00 000z" } ] } query param notas type opcional filtra por un único tipo usá el uid de la lista o tu propia reference para direccionarla en las siguientes llamadas obtener una lista y sus ítems curl "https //api sugaway com/p/list/list\ ab12cd?search=foo\&page=1\&limit=25" \\ h "x api key $api key" h "x access token $access token" podés pasar el uid de la lista o un token ref \<tu reference> en la url query param default notas search — busca ítems por valor enviás el valor en claro (p ej un email o un número de tarjeta); la comparación se encarga de la normalización por vos page 1 número de página (empieza en 1) limit 25 ítems por página (máx 100) { "result" true, "data" { "list" { "uid" "list\ ab12cd", "name" "emails bloqueados", "type" "email", "reference" "emails bloqueados", "status" "active", "updated" "2026 06 15t12 00 00 000z", "created" "2026 06 01t09 00 00 000z" }, "items" \[ { "uid" "litem 9f8e7d", "value" "foo\@example com", "label" "reportado por soporte", "data" {}, "status" "active", "createdat" "2026 06 10t08 30 00 000z" } ] } } para listas card number el value del ítem (la huella segura) no se devuelve; igual recibís label, data (con bin / last4) y status las listas grandes se entregan en partes (streaming) pero se parsean como un documento json normal — no requieren manejo especial del cliente crear una lista curl x post https //api sugaway com/p/list \\ h "x api key $api key" h "x access token $access token" \\ h "content type application/json" \\ d '{ "name" "emails bloqueados", "type" "email", "reference" "emails bloqueados" }' campo requerido notas name sí nombre visible type sí uno de los tipos de lista reference no tu propia clave para la lista se genera automáticamente si la omitís devuelve la lista creada agregar un ítem a una lista curl x post https //api sugaway com/p/list/list\ ab12cd/item \\ h "x api key $api key" h "x access token $access token" \\ h "content type application/json" \\ d '{ "value" "foo\@example com", "label" "reportado por soporte", "reference" "caso 1234" }' la url acepta el uid de la lista o ref \<tu reference> campo requerido notas value sí el valor a guardar se limpia automáticamente según el tipo de lista para tarjetas, enviá el número completo — se convierte en huella y se descarta label no una nota humana data no cualquier metadata extra que quieras conservar con el ítem reference no tu clave de idempotencia / externa se genera si la omitís expiresat no una fecha que quieras asociar al ítem agregar es idempotente si ya existe un ítem activo con la misma reference o el mismo valor en la lista, se devuelve ese ítem existente y no se duplica nada en el tipo "entity" se debe enviar como valor la referencia en el formato "ref\ xxxxxxx" o bien el uid del entity "ent\ xxxxxxxxxx" eliminar un ítem curl x delete https //api sugaway com/p/list/list\ ab12cd/item/litem 9f8e7d \\ h "x api key $api key" h "x access token $access token" marca el ítem como borrado (queda registrado) y devuelve el ítem tal como estaba antes de eliminarlo bueno saber idempotencia enviá siempre una reference que vos controlés al agregar ítems, así los reintentos no crean duplicados seguridad de tarjetas (pci) podés enviar números de tarjeta completos — se convierten en una huella segura y sólo se retiene {bin, last4, length} el número completo nunca se guarda ni se devuelve buscá como pensás enviá el valor en claro al buscar; la api aplica la misma normalización que usó al guardar (así una búsqueda de tarjeta compara por huella, una de email es case‑insensitive, etc ) paginación el tamaño de página tiene un tope de 100 iterá con page para leer listas grandes borrado lógico los ítems eliminados se conservan para trazabilidad; simplemente dejan de estar activos expiresat es informativo se guarda con el ítem pero no lo elimina automáticamente decidí en tu propio flujo si un ítem expirado debería seguir contando aislamiento sólo podés acceder a tus propias listas; direccionar una lista que no es tuya se rechaza códigos de error los errores vuelven como { "result" false, } con uno de estos códigos código significado list\ invalid type el type que enviaste no es uno de los tipos de lista permitidos list\ invalid value el value del ítem falta o está vacío list\ invalid list no se encontró la lista api\ security violation intentaste operar sobre una lista que no pertenece a tu cuenta