Guía para integración

15 min

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 " [email protected] " a una lista email guarda y compara [email protected].

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": "[email protected]", "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": "[email protected]", "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.