Suscriptores (Customers)

---

• Suscriptores (Customers)
  • ¿Qué es un suscriptor?
  • Listar suscriptores
  • Buscar un suscriptor
  • Cuándo deja de servir un subscriber_id
  • Crear suscriptor
  • Actualizar suscriptor
  • Metadata
  • Eliminar suscriptor
  • Alias customer

¿Qué es un suscriptor?

Un suscriptor es tu cliente dentro de nuestro sistema: guarda su identidad y sus datos de facturación, y es a quien después le asocias un plan para crear la suscripción.

Créalo una sola vez y reutilízalo: un mismo suscriptor puede tener varias suscripciones y varias tarjetas guardadas, con una marcada como predeterminada (default_payment_method).

Nota

Nombre alternativo (estilo Stripe). Cada ruta de esta página existe también bajo customer, con el mismo comportamiento y la misma respuesta:

Nombre original	Alias
GET /api/v1/subscriptions/subscriber	GET /api/v1/subscriptions/customer
GET /api/v1/subscriptions/subscriber/{emailOrId}	GET /api/v1/subscriptions/customer/{emailOrId}
POST /api/v1/subscriptions/subscriber	POST /api/v1/subscriptions/customer
PUT /api/v1/subscriptions/subscriber/{id}	PUT /api/v1/subscriptions/customer/{id}
DELETE /api/v1/subscriptions/subscriber/{id}	DELETE /api/v1/subscriptions/customer/{id}

Precaución

El correo es único por sucursal, no por comercio. El mismo cliente en dos sucursales son dos suscriptores distintos.

Listar suscriptores

Descripción: Devuelve todos los suscriptores de las sucursales a las que tienes acceso.

GET /api/v1/subscriptions/subscriber

Precaución

Este listado no está paginado, no viene envuelto en data y no separa por ambiente: es el arreglo completo de suscriptores, en snake_case. Si tienes muchos clientes, la respuesta puede ser grande.

GEThttps://sag.efipay.co/api/v1/subscriptions/subscriber

Token de acceso

ProbarCopiar como cURL

Puedes filtrar por tu metadata con coincidencia exacta: GET /api/v1/subscriptions/subscriber?filter[metadata][crm_id]=C-881.

curl -X GET \
'/api/v1/subscriptions/subscriber' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'

Consejo

Respuesta satisfactoria

200OK

[
    {
        "id": "9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f",
        "identification_type": "CC",
        "id_number": "1020304050",
        "name": "Ana",
        "last_name": "Gómez",
        "email": "ana@ejemplo.com",
        "phone_code": 57,
        "cellphone_number": "3001234567",
        "billing_address": "Calle 100 # 20-30",
        "billing_city": "Bogotá",
        "billing_country": "Colombia",
        "metadata": { "crm_id": "C-881" },
        "office_id": 1,
        "commerce_id": 42,
        "created_at": "2026-07-31 10:15:00"
    }
]

Buscar un suscriptor

Descripción: Devuelve un suscriptor por su id, su correo o su número de documento. El mismo endpoint acepta las tres cosas, así que no necesitas guardar nuestro id si ya tienes cualquiera de los otros dos.

GET /api/v1/subscriptions/subscriber/{emailOrId}

Puedes buscar por	Ejemplo
Id (uuid)	/subscriber/9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f
Correo	/subscriber/ana@ejemplo.com
Documento	/subscriber/1020304050

Nota

La búsqueda queda acotada a tu comercio y a las sucursales a las que tenga acceso el usuario del token. Un documento que exista en otro comercio devuelve 404.

GEThttps://sag.efipay.co/api/v1/subscriptions/subscriber/ana@ejemplo.com

Token de acceso

ProbarCopiar como cURL

curl -X GET \
'/api/v1/subscriptions/subscriber/ana@ejemplo.com' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'

Consejo

Respuesta satisfactoria

200OK

{
    "id": "9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f",
    "identification_type": "CC",
    "id_number": "1020304050",
    "name": "Ana",
    "last_name": "Gómez",
    "email": "ana@ejemplo.com",
    "phone_code": 57,
    "cellphone_number": "3001234567",
    "billing_address": "Calle 100 # 20-30",
    "billing_city": "Bogotá",
    "billing_country": "Colombia",
    "default_payment_method_id": "9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e81",
    "balance": 0,
    "currency": "COP",
    "active": true,
    "office_id": 1,
    "commerce_id": 42,
    "created_at": "2026-07-31 10:15:00"
}

Peligro

No existe, o no pertenece a una sucursal a la que tengas acceso

404Not Found

Cuándo deja de servir un subscriber_id

Un id que guardaste y que funcionaba puede empezar a devolver 422 al crear una suscripción. Hay tres causas y cada una tiene su propio mensaje en errors.subscriber_id:

Mensaje	Qué pasó	Cómo se arregla
«El suscriptor pertenece a la sucursal N y estás enviando office=M»	El suscriptor vive en otra sede	Manda el office de su sede, o crea el suscriptor en la sede que estás usando
«El suscriptor fue eliminado»	Alguien lo borró. La fila sigue existiendo, por eso el id “parece” válido	Créalo de nuevo
«El suscriptor pertenece a otro comercio»	El token es de otro comercio	Revisa el token
«No existe un suscriptor con ese id»	El id nunca existió	Revisa el id

Peligro

La causa más común es la sucursal. El suscriptor y el plan deben ser de la misma sede que el office que mandas al crear la suscripción. Los tres tienen que coincidir; si no, el 422 llega aunque el id sea correcto.

Lo que no invalida un suscriptor:

• El paso del tiempo. Un subscriber_id no caduca.
• Tokenizar o cambiar la tarjeta. Las tarjetas cuelgan del suscriptor; cambiarlas no lo toca.
• El ambiente. A diferencia de planes y suscripciones, los suscriptores no tienen eje prueba/producción: el mismo suscriptor sirve para ambos.

Consejo

Si dudas de un id guardado, confírmalo antes de cobrar con GET /api/v1/subscriptions/subscriber/{id}. Un 200 te devuelve además su office_id, que es el que debes mandar como office.

Crear suscriptor

Descripción: Registra un cliente. Los datos de facturación son obligatorios porque viajan a la red en cada cobro recurrente.

POST /api/v1/subscriptions/subscriber

Nombre del campo	Descripción	Reglas
identification_type	Tipo de documento. Ver enumeraciones	['required', 'string', 'in:CC,CE,TI,PPT,DNI,NIT,Pasaporte,Otro']
id_number	Número de documento. No puede ser un número de tarjeta: lo rechazamos a propósito	['required', 'numeric', 'digits_between:5,15']
name	Nombres del cliente	['required', 'string', 'max:255']
last_name	Apellidos del cliente	['required', 'string', 'max:255']
email	Correo del cliente. Único dentro de la sucursal	['required', 'email', 'max:255', 'unique:subscribers,email']
phone_code	Indicativo del país, sin + (Colombia: 57)	['required', 'integer', 'min_digits:1', 'max_digits:3']
cellphone_number	Celular. Se valida como número real del país que resulte de phone_code	['required', 'numeric', 'phone']
billing_address	Dirección de facturación	['required', 'string', 'max:255']
billing_city	Ciudad de facturación	['required', 'string', 'max:255']
billing_country	País de facturación. Ver lista de países	['required', 'string', 'max:255']
office	Sucursal a la que pertenece el suscriptor. Debe ser una de tus sucursales	['required', 'exists:offices,id']
metadata	Tus pares clave-valor. Ver Metadata	['sometimes', 'nullable', 'metadata']

POSThttps://sag.efipay.co/api/v1/subscriptions/subscriber

Token de accesoCuerpo de la petición{ "identification_type": "CC", "id_number": "1020304050", "name": "Ana", "last_name": "Gómez", "email": "ana@ejemplo.com", "phone_code": "57", "cellphone_number": "3001234567", "billing_address": "Calle 100 # 20-30", "billing_city": "Bogotá", "billing_country": "Colombia", "office": 1 }

ProbarCopiar como cURL

curl -X POST \
'/api/v1/subscriptions/subscriber' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "identification_type": "CC",
    "id_number": "1020304050",
    "name": "Ana",
    "last_name": "Gómez",
    "email": "ana@ejemplo.com",
    "phone_code": "57",
    "cellphone_number": "3001234567",
    "billing_address": "Calle 100 # 20-30",
    "billing_city": "Bogotá",
    "billing_country": "Colombia",
    "office": 1
}'

Consejo

Suscriptor creado

201Created

{
    "saved": true,
    "subscriber": {
        "id": "9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f",
        "name": "Ana",
        "lastName": "Gómez",
        "email": "ana@ejemplo.com",
        "phoneCode": 57,
        "cellphoneNumber": "3001234567",
        "billingAddress": "Calle 100 # 20-30",
        "billingCity": "Bogotá",
        "billingCountry": "Colombia",
        "metadata": null,
        "active": true,
        "subscriptionsCount": 0,
        "activeSubscriptionsCount": 0,
        "inactiveSubscriptionsCount": 0,
        "createdAt": "2026-07-31 10:15:00"
    }
}

Peligro

Correo repetido en la misma sucursal

422Unprocessable Entity

{
    "message": "El campo email ya está en uso.",
    "errors": {
        "email": ["El campo email ya está en uso."]
    },
    "error": {
        "type": "invalid_request_error",
        "code": "validation_failed",
        "message": "El campo email ya está en uso.",
        "param": "email"
    }
}

Actualizar suscriptor

Descripción: Cambia los datos de un suscriptor. Envía solo los campos que quieres cambiar; los que omitas se quedan como estaban. El tipo y número de documento no se modifican, ni la sucursal.

PUT /api/v1/subscriptions/subscriber/{subscriber-id}

Nombre del campo	Descripción	Reglas
name	Nombres del cliente	['sometimes', 'required', 'string', 'max:255']
last_name	Apellidos del cliente	['sometimes', 'required', 'string', 'max:255']
email	Nuevo correo. Único dentro de la misma sucursal, ignorando a este suscriptor	['sometimes', 'required', 'email', 'max:255', 'unique:subscribers,email']
phone_code	Indicativo del país	['sometimes', 'required', 'integer', 'min_digits:1', 'max_digits:3']
cellphone_number	Celular. Aquí no se valida contra el formato del país, a diferencia de crear	['sometimes', 'required', 'numeric']
billing_address	Dirección de facturación	['sometimes', 'required', 'string', 'max:255']
billing_city	Ciudad de facturación	['sometimes', 'required', 'string', 'max:255']
billing_country	País de facturación	['sometimes', 'required', 'string', 'max:255']
metadata	Se combina con la existente. Una clave con "" o null se borra; metadata: null borra todo. Ver Metadata	['sometimes', 'nullable', 'metadata']

PUThttps://sag.efipay.co/api/v1/subscriptions/subscriber/your-subscriber-id

Token de accesoCuerpo de la petición{ "email": "ana.gomez@ejemplo.com", "cellphone_number": "3009876543" }

ProbarCopiar como cURL

curl -X PUT \
'/api/v1/subscriptions/subscriber/9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "email": "ana.gomez@ejemplo.com",
    "cellphone_number": "3009876543"
}'

Consejo

Respuesta satisfactoria

200OK

{
    "saved": true,
    "subscriber": {
        "id": "9b0f2a13-2c44-4a1a-9f2e-1d3b4c5d6e7f",
        "name": "Ana",
        "lastName": "Gómez",
        "email": "ana.gomez@ejemplo.com",
        "cellphoneNumber": "3009876543",
        "subscriptionsCount": 2,
        "activeSubscriptionsCount": 1,
        "inactiveSubscriptionsCount": 1,
        "createdAt": "2026-07-31 10:15:00"
    }
}

Metadata

metadata guarda tus propias referencias del cliente (id en tu CRM, segmento…), al estilo de Stripe. Mismas reglas que en suscripciones:

Límite	Valor
Claves	Hasta 50, de 1 a 40 caracteres [A-Za-z0-9_-]
Valor	Texto o número, hasta 500 caracteres. Se guarda como texto
Al actualizar	Las claves se combinan; "" o null borra una clave; metadata: null borra todo

Llega en los GET, en el listado y en los webhooks de suscripción, dentro de subscription.subscriber.metadata. Un valor inválido responde 422 con error.code: "validation_failed" y error.param: "metadata".

Eliminar suscriptor

Descripción: Elimina un suscriptor.

DELETE /api/v1/subscriptions/subscriber/{subscriber-id}

Precaución

No podrás eliminar un suscriptor que tenga una suscripción activa. Cancélala primero, o déjala terminar.

DELETEhttps://sag.efipay.co/api/v1/subscriptions/subscriber/your-subscriber-id

Token de accesoCuerpo de la petición

ProbarCopiar como cURL

Consejo

Respuesta satisfactoria

200OK

{
    "deleted": true
}

Peligro

El suscriptor tiene una suscripción activa

400Bad Request

{
    "message": "Este suscriptor no puede ser eliminado ya que tiene una suscripción activa"
}

Alias customer

Las mismas operaciones, con el nombre de Stripe. Comportamiento, parámetros y respuestas son idénticos a los de arriba; solo cambia el segmento de la ruta.

Listar — GET /api/v1/subscriptions/customer

GEThttps://sag.efipay.co/api/v1/subscriptions/customer

Token de acceso

ProbarCopiar como cURL

Buscar por correo o id — GET /api/v1/subscriptions/customer/{emailOrId}

GEThttps://sag.efipay.co/api/v1/subscriptions/customer/ana@ejemplo.com

Token de acceso

ProbarCopiar como cURL

Crear — POST /api/v1/subscriptions/customer

POSThttps://sag.efipay.co/api/v1/subscriptions/customer

Token de accesoCuerpo de la petición{ "identification_type": "CC", "id_number": "1020304050", "name": "Ana", "last_name": "Gómez", "email": "ana@ejemplo.com", "phone_code": "57", "cellphone_number": "3001234567", "billing_address": "Calle 100 # 20-30", "billing_city": "Bogotá", "billing_country": "Colombia", "office": 1 }

ProbarCopiar como cURL

Actualizar — PUT /api/v1/subscriptions/customer/{customer-id}

PUThttps://sag.efipay.co/api/v1/subscriptions/customer/your-subscriber-id

Token de accesoCuerpo de la petición{ "email": "ana.gomez@ejemplo.com", "cellphone_number": "3009876543" }

ProbarCopiar como cURL

Eliminar — DELETE /api/v1/subscriptions/customer/{customer-id}

DELETEhttps://sag.efipay.co/api/v1/subscriptions/customer/your-subscriber-id

Token de accesoCuerpo de la petición

ProbarCopiar como cURL