API Reference

La API de Autodeb permite integrar el procesamiento de débitos automáticos en tu plataforma. Todos los endpoints requieren autenticación Bearer Token.

Principios de diseño

API-first

Toda la funcionalidad accesible vía REST. SDK y webhooks incluidos.

Procesamiento inteligente

Reintentos automáticos, validación de datos y manejo de errores.

Infraestructura segura

TLS 1.3, AES-256, auditoría completa y alta disponibilidad.

Notificaciones

Webhooks, SMS y emails automáticos en cada evento.

Observabilidad

Dashboard en tiempo real, logs estructurados y métricas.

Integraciones

Nequi, Daviplata y Bre-B desde un único endpoint.

Autenticación

Todos los endpoints requieren autenticación via Bearer Token en el header Authorization.

cURL

curl --request GET \
  --url https://api.autodeb.com/v1/charges \
  --header 'Authorization: Bearer adb_sk_live_xxxx' \
  --header 'Content-Type: application/json'

Códigos de estado

Autodeb usa códigos de estado HTTP estándar para indicar éxito o fallo en las solicitudes.

CódigoEstadoDescripción

200OKLa solicitud fue exitosa.

201CreatedEl recurso fue creado exitosamente.

400Bad RequestDatos inválidos o campos requeridos faltantes.

401UnauthorizedToken de autorización inválido o expirado.

403ForbiddenSin permisos para esta operación.

404Not FoundEl recurso solicitado no existe.

422UnprocessableEl cobro fue rechazado por el rail financiero.

429Too Many RequestsRate limit excedido. Espera antes de reintentar.

500Server ErrorError interno del servidor. Contactar soporte.

Crear cobro

Crea un nuevo cobro automático sobre el número de celular y rail especificado.

POST /v1/charges

Crea un cobro inmediato o programado

Headers requeridos

HeaderTipoReq.Descripción

Authorizationstring●Bearer Token: Bearer adb_sk_live_xxx

Content-Typestring●Debe ser application/json

Idempotency-Keystring○UUID único para prevenir cobros duplicados.

Campos del request

CampoTipoReq.Descripción

phonestring●Número celular del usuario. Formato colombiano: 10 dígitos sin indicativo. Ej: 3015678901

amountinteger●Monto en centavos (COP). Mínimo 100. Ej: 180000 = $180,000 COP

currencystring●Moneda ISO 4217. Actualmente solo COP

railstring●Rail financiero: nequi | daviplata | breb

descriptionstring○Descripción del cobro para el usuario (max 140 chars).

referencestring○Referencia interna de tu sistema para conciliación.

scheduled_datestring○Fecha programada ISO 8601: 2025-08-15. Si no se envía, se procesa inmediatamente.

notify_smsboolean○Enviar notificación SMS al usuario. Default: false

notify_emailstring○Email del usuario para notificación. Si se envía, activa el email automático.

JSON

{
  "phone": "3015678901",
  "amount": 180000,
  "currency": "COP",
  "rail": "nequi",
  "description": "Cuota mensual servicio premium",
  "reference": "INV-2025-001",
  "notify_sms": true,
  "notify_email": "usuario@ejemplo.com"
}

JSON

{
  "id": "chg_9k3xmr7fbp",
  "object": "charge",
  "status": "processing",
  "phone": "3015678901",
  "amount": 180000,
  "currency": "COP",
  "rail": "nequi",
  "description": "Cuota mensual servicio premium",
  "reference": "INV-2025-001",
  "created_at": "2025-07-15T10:23:45Z",
  "processed_at": null,
  "error_code": null,
  "error_message": null
}

cURL

curl --request POST \
  --url https://api.autodeb.com/v1/charges \
  --header 'Authorization: Bearer adb_sk_live_xxxx' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --data '{
    "phone": "3015678901",
    "amount": 180000,
    "currency": "COP",
    "rail": "nequi",
    "description": "Cuota mensual servicio premium"
  }'

JavaScript

const response = await fetch('https://api.autodeb.com/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer adb_sk_live_xxxx',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({
    phone: '3015678901',
    amount: 180000,
    currency: 'COP',
    rail: 'nequi',
    description: 'Cuota mensual servicio premium'
  })
});
const charge = await response.json();
console.log(charge.id); // "chg_9k3xmr7fbp"

Consultar cobro

Recupera el estado actual y detalles de un cobro específico por su ID.

GET /v1/charges/{charge_id}

Consulta el estado de un cobro

Path parameters

CampoTipoReq.Descripción

charge_idstring●ID del cobro. Formato: chg_xxxxxxxxxx

JSON

{
  "id": "chg_9k3xmr7fbp",
  "object": "charge",
  "status": "succeeded",
  "phone": "3015678901",
  "amount": 180000,
  "currency": "COP",
  "rail": "nequi",
  "reference": "INV-2025-001",
  "created_at": "2025-07-15T10:23:45Z",
  "processed_at": "2025-07-15T10:23:46Z",
  "rail_transaction_id": "NEQ-TXN-789456123",
  "error_code": null,
  "error_message": null,
  "retries": 0
}

cURL

curl --request GET \
  --url https://api.autodeb.com/v1/charges/chg_9k3xmr7fbp \
  --header 'Authorization: Bearer adb_sk_live_xxxx'

JavaScript

const res = await fetch(
  `https://api.autodeb.com/v1/charges/${chargeId}`,
  { headers: { 'Authorization': 'Bearer adb_sk_live_xxxx' } }
);
const charge = await res.json();
// charge.status === 'succeeded' | 'processing' | 'failed'

Crear suscripción recurrente

Crea una suscripción automática que ejecutará cobros recurrentes según el ciclo configurado.

POST /v1/subscriptions

Crea una suscripción recurrente

Campos del request

CampoTipoReq.Descripción

phonestring●Número celular del suscriptor. 10 dígitos.

amountinteger●Monto en COP del cobro recurrente.

currencystring●Moneda: COP

railstring●Rail financiero: nequi | daviplata | breb

intervalstring●Frecuencia: daily | weekly | monthly | custom

interval_daysinteger○Requerido si interval=custom. Días entre cobros.

start_datestring●Fecha del primer cobro. Formato ISO 8601: 2025-08-01

end_datestring○Fecha de fin de la suscripción (opcional). Indefinida si no se envía.

max_chargesinteger○Número máximo de cobros. Sin límite si no se envía.

JSON

{
  "phone": "3015678901",
  "amount": 50000,
  "currency": "COP",
  "rail": "nequi",
  "interval": "monthly",
  "start_date": "2025-08-01",
  "end_date": "2026-08-01",
  "max_charges": 12,
  "description": "Plan Premium mensual"
}

JSON

{
  "id": "sub_9k2mxa4ry1",
  "object": "subscription",
  "status": "active",
  "phone": "3015678901",
  "amount": 50000,
  "currency": "COP",
  "rail": "nequi",
  "interval": "monthly",
  "start_date": "2025-08-01",
  "end_date": "2026-08-01",
  "next_charge_date": "2025-08-01",
  "charges_count": 0,
  "max_charges": 12,
  "created_at": "2025-07-15T10:30:00Z"
}

cURL

curl --request POST \
  --url https://api.autodeb.com/v1/subscriptions \
  --header 'Authorization: Bearer adb_sk_live_xxxx' \
  --header 'Content-Type: application/json' \
  --data '{"phone":"3015678901","amount":50000,"currency":"COP","rail":"nequi","interval":"monthly","start_date":"2025-08-01"}'

JavaScript

const sub = await fetch('https://api.autodeb.com/v1/subscriptions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer adb_sk_live_xxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone: '3015678901',
    amount: 50000,
    currency: 'COP',
    rail: 'nequi',
    interval: 'monthly',
    start_date: '2025-08-01'
  })
}).then(r => r.json());
// sub.id === "sub_9k2mxa4ry1"

Estado de procesamiento

Consulta el estado de procesamiento de un lote de cobros (batch).

GET /v1/batches/{batch_id}

Estado de un lote de cobros

JSON

{
  "id": "batch_a7f2k9m3",
  "object": "batch",
  "status": "completed",
  "total": 100,
  "succeeded": 94,
  "failed": 5,
  "processing": 1,
  "success_rate": 94.0,
  "created_at": "2025-07-15T09:00:00Z",
  "completed_at": "2025-07-15T09:02:15Z",
  "charges": [
    {
      "id": "chg_9k3xmr7fbp",
      "phone": "3015678901",
      "status": "succeeded",
      "amount": 180000
    }
  ]
}

cURL

curl --request GET \
  --url https://api.autodeb.com/v1/batches/batch_a7f2k9m3 \
  --header 'Authorization: Bearer adb_sk_live_xxxx'

Cancelar suscripción

Cancela una suscripción activa. No se procesarán más cobros a partir de este momento.

DELETE /v1/subscriptions/{subscription_id}

Cancela una suscripción activa

Campos del request (body opcional)

CampoTipoReq.Descripción

reasonstring○Razón de cancelación para auditoría. Ej: user_request

cancel_at_period_endboolean○Si true, cancela al fin del ciclo actual. Default: false (inmediato).

JSON

{
  "id": "sub_9k2mxa4ry1",
  "object": "subscription",
  "status": "cancelled",
  "cancelled_at": "2025-07-15T14:22:00Z",
  "reason": "user_request",
  "charges_count": 3,
  "last_charge_date": "2025-07-01"
}

cURL

curl --request DELETE \
  --url https://api.autodeb.com/v1/subscriptions/sub_9k2mxa4ry1 \
  --header 'Authorization: Bearer adb_sk_live_xxxx' \
  --header 'Content-Type: application/json' \
  --data '{"reason": "user_request"}'

JavaScript

const result = await fetch(
  `https://api.autodeb.com/v1/subscriptions/${subscriptionId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer adb_sk_live_xxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ reason: 'user_request' })
  }
).then(r => r.json());
// result.status === 'cancelled'

Webhooks

Configura un endpoint en tu servidor para recibir eventos en tiempo real cuando el estado de un cobro o suscripción cambia.

JSON — Evento webhook

{
  "event_id": "evt_m3k9xr2p",
  "event_type": "charge.succeeded",
  "created_at": "2025-07-15T10:23:46Z",
  "data": {
    "id": "chg_9k3xmr7fbp",
    "object": "charge",
    "status": "succeeded",
    "amount": 180000,
    "currency": "COP"
  }
}

Tipos de eventos

EventoTipoDescripción

charge.processingchargeEl cobro entró al rail financiero.

charge.succeededchargeEl débito fue ejecutado exitosamente.

charge.failedchargeEl cobro fue rechazado. Incluye error_code.

subscription.activatedsubscriptionLa suscripción fue activada.

subscription.cancelledsubscriptionLa suscripción fue cancelada.

batch.completedbatchEl lote de cobros terminó de procesarse.