--- title: Guía para integración slug: list-guia-para-integradores createdAt: 2026-06-16T18:37:33.870Z --- 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. :::BlockQuote 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 :::BlockQuote *# 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" ::: :::BlockQuote \{ "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 :::BlockQuote 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:\ 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). | :::BlockQuote \{ "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. :::BlockQuote 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 :::BlockQuote 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 :::BlockQuote 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:\. | 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 :::BlockQuote 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. |