Introducción

SAI es la API REST oficial de Avanzar Soluciones que permite a la plataforma ECOllect consultar obligaciones financieras de clientes y registrar los pagos efectuados con trazabilidad completa.

La integración cubre dos submódulos de cobranza con tipos de contrato diferenciados en el CRM Bitrix24:

Alianza Jurídica — tipo_contrato 34056
Lidera — tipo_contrato 13597

Base URL

https://sai.desarrollo.avanzarsoluciones.com

Headers requeridos

Headers

Authorization: Api-Key <prefix>.<secret>
Content-Type: application/json
Accept: application/json

Autenticación

Cada request debe incluir una API Key con scope autorizado para el endpoint que se consume. La key se entrega a través del portal administrativo y se muestra una sola vez al crearla.

Importante: el backend almacena únicamente el hash SHA-512 de la key. Si la pierdes, debe revocarse y generarse una nueva — no es recuperable.

Formato del header

cURL

curl -X POST "https://sai.desarrollo.avanzarsoluciones.com/ecollect/api/ContractTypeOptions" \
  -H "Authorization: Api-Key DMeixmeN.k4j8s9d2f1g7h3l5n6m0p2q4r6t8v0w2" \
  -H "Content-Type: application/json"

Verificación rápida

Si la API Key es válida, cualquier endpoint del scope devuelve 200 OK. Si está fuera del scope autorizado devuelve 403 Forbidden. Si la key es inválida o expirada devuelve 401 Unauthorized.

Códigos de error

Todas las respuestas de error devuelven un cuerpo JSON con el formato:

JSON

{
  "detail": "Mensaje legible para humano",
  "errors": { "campo": ["mensaje específico"] }
}

Código	Significado
200	Consulta exitosa
201	Recurso creado correctamente
400	Payload inválido o validación fallida
401	API Key inválida o ausente
403	API Key sin permiso para este endpoint
404	Recurso no encontrado
409	Conflicto: pago duplicado (TicketId o TrazabilityCode ya registrado)
500	Error interno — contactar soporte con TicketId y timestamp

GetClientObligationsAlianza

Retorna todas las obligaciones financieras activas de un cliente en la cartera Alianza Jurídica. Internamente consulta Bitrix24 y devuelve los deals asociados al contacto, junto con las cuotas pendientes.

POST /ecollect/api/GetClientObligationsAlianza 200 OK

El tipo_contrato (34056) es fijo en el servidor. Solo se envía client_reference en el body.

Parámetros

Campo	Tipo	Estado	Descripción
client_reference	string	Requerido	Cédula de ciudadanía del cliente Alianza

cURL — Ejemplo listo para ejecutar

cURL

copiar y pegar

curl -X POST "https://sai.desarrollo.avanzarsoluciones.com/ecollect/api/GetClientObligationsAlianza" \
  -H "Authorization: Api-Key DMeixmeN.k4j8s9d2f1g7h3l5n6m0p2q4r6t8v0w2" \
  -H "Content-Type: application/json" \
  -d '{
    "client_reference": "52910357"
  }'

Estructura de respuesta

La respuesta varía según el método de autenticación:

Api-Key (integración externa): respuesta slim con los campos imprescindibles para mostrar el saldo al cliente.
Sesión Django (admin/portal interno): respuesta extendida con campos adicionales de auditoría (montos por filial, slots de pago, etc.).

Respuesta slim (Api-Key) — Top-level

Campo	Tipo	Descripción
total_records	integer	Cantidad de obligaciones encontradas
records	array<ObligationRecord>	Lista de obligaciones

Subtipo: `ObligationRecord` (slim)

Campo	Tipo	Descripción
obligation_id	string	ID del deal en Bitrix24
obligation_name	string	Título del deal (campo TITLE)
cedula	string	Cédula del titular (eco del `client_reference` que enviaste)
total_balance	decimal	HONORARIOS original del deal (sin descontar pagos)
pending_balance	decimal	Saldo real pendiente: HONORARIOS original menos pagos registrados
overdue_amount	decimal	Suma de cuotas con fecha ≤ hoy que aún quedan pendientes
minimum_payment_due	decimal	Monto mínimo a pagar HOY. Acumula cuotas vencidas + cuota del período actual
reference_date_used	string	Fecha (ISO 8601) tomada como "hoy" para los cálculos acumulativos
pending_quotes	array<QuoteRecord>	Detalle de cuotas con saldo pendiente (al final del record por verbosidad)

Subtipo: `QuoteRecord`

Campo	Tipo	Descripción
date	string	Fecha programada de la cuota (ISO 8601)
value	decimal	Valor de la cuota en COP

Ejemplo de respuesta slim (Api-Key)

JSON · 200 OK

{
  "total_records": 1,
  "records": [
    {
      "obligation_id": "822044",
      "obligation_name": "ALFREDO ROJAS VIDAL - CA Prueba",
      "cedula": "1126446660",
      "total_balance": 4388400.0,
      "pending_balance": 728400.0,
      "overdue_amount": 4388400.0,
      "minimum_payment_due": 4388400.0,
      "reference_date_used": "2026-05-28T20:41:52+00:00",
      "pending_quotes": [
        { "date": "2024-11-29T03:00:00+03:00", "value": 844200.0 },
        { "date": "2024-12-30T03:00:00+03:00", "value": 1772100.0 },
        { "date": "2025-01-30T03:00:00+03:00", "value": 1772100.0 }
      ]
    }
  ]
}

Respuesta extendida (sesión Django admin) — solo uso interno

Cuando llamas desde el portal admin con cookie de sesión, cada ObligationRecord también incluye estos campos:

Campo	Tipo	Descripción
balance_value	decimal	HONORARIOS original del deal (sin descontar pagos)
currency	string	Moneda ISO. Default `"COP"`
stage_id	string \| null	Etapa actual en Bitrix (ej. `"C130:NEW"`)
date_create	string \| null	Fecha de creación del deal (ISO 8601)
category_id	string \| null	Pipeline/categoría Bitrix
contact_id	string \| null	ID del contacto Bitrix asociado
paid_amount	number \| null	Monto ya pagado en este deal
total_original_amount	number \| null	Monto total contratado originalmente
total_contrato	number \| null	Total honorarios pactados
flm_total	number \| null	Saldo pendiente FLM
prosperar_total	number \| null	Saldo pendiente Prosperar
avanzar_total	number \| null	Saldo pendiente Avanzar
anticipo_value	number \| null	Valor del anticipo pactado
anticipo_date	string \| null	Fecha del anticipo
quotes	array<QuoteRecord>	Cuotas pendientes de pago
all_quotes	array<QuoteRecord>	Todas las cuotas (pagadas + pendientes)
payment_records	array<PaymentSlot> \| null	Slots de pagos confirmados (`"Anticipo"`, `"Pago 1"`, …)

PaymentCreation

Registra oficialmente un pago realizado por un cliente Alianza. Endpoint idempotente por TicketId y TrazabilityCode: ante un reintento con los mismos identificadores devuelve 409 con el pago ya registrado.

POST /ecollect/api/internal/pagos/crear-alianza 201 Created

El payload se basa en datos de Bitrix (id_bitrix, cedula, nombre). Cliente y Negocio se resuelven (o crean) automáticamente. Si el Negocio ya existía con un tipo_contrato distinto de "34056", el endpoint devuelve 400 con expected_tipo_contrato y actual_tipo_contrato para diagnóstico.

Parámetros — nivel raíz

Campo	Tipo	Estado	Descripción
id_bitrix	string	Requerido	ID del Deal en Bitrix24 (numérico, ej. `"822044"`). Indexa `get_or_create` de Negocio.
cedula	string	Requerido	Cédula del titular. Indexa `get_or_create` de Cliente.
nombre	string	Opcional	Nombre completo. Solo se persiste si el Cliente es nuevo o no tenía nombre.
ecollect	object	Requerido	Datos del pago en formato ECOllect (ver tabla siguiente).

Parámetros — sub-objeto `ecollect`

Campo	Tipo	Estado	Descripción
EntityCode	string	Requerido	Código de entidad / cédula del cliente en ECOllect
TicketId	string	Requerido	Único — ID del ticket de pago
TrazabilityCode	string	Requerido	Único — código de trazabilidad financiera
TransValue	decimal	Requerido	Monto del pago en COP (debe ser `> 0`)
TranState	enum	Requerido	`OK` · `FAIL` · `PENDING` · `REVERSED` · `CANCELLED`
BankProcessDate	datetime	Requerido	Fecha ISO 8601 de procesamiento bancario
UserMail	email	Opcional	Email del cliente que realizó el pago
PaymentsArray	array	Opcional	Detalle libre de cuotas pagadas (JSON)
referencia_interna	string	Opcional	Código humano interno. Si se omite, se usa `TicketId`.
origen_pago	enum	Opcional	`ecollect` (default) · `manual` · `bank_transfer` · `bitrix` · `other`

cURL — Ejemplo listo para ejecutar

cURL

copiar y pegar

curl -X POST "https://sai.desarrollo.avanzarsoluciones.com/ecollect/api/internal/pagos/crear-alianza" \
  -H "Authorization: Api-Key DMeixmeN.k4j8s9d2f1g7h3l5n6m0p2q4r6t8v0w2" \
  -H "Content-Type: application/json" \
  -d '{
    "id_bitrix": "822044",
    "cedula":    "1098686512",
    "nombre":    "JUAN PEREZ",
    "ecollect": {
      "EntityCode":      "1098686512",
      "TicketId":        "TK-2026-100001",
      "TrazabilityCode": "TRZ-2026-100001",
      "TransValue":      250000,
      "TranState":       "OK",
      "BankProcessDate": "2026-05-25T17:00:00-05:00",
      "UserMail":        "cliente@email.com",
      "PaymentsArray":   [],
      "referencia_interna": "NEG-2026-001"
    }
  }'

Respuesta

JSON · 201 Created

{
  "id": 142,
  "cliente_id": 15,
  "cliente_cedula": "1098686512",
  "negocio_id": 22,
  "referencia_interna": "NEG-2026-001",
  "origen_pago": "ecollect",
  "entity_code": "1098686512",
  "ticket_id": "TK-2026-100001",
  "trazability_code": "TRZ-2026-100001",
  "trans_value": "250000.00",
  "tran_state": "OK",
  "bank_process_date": "2026-05-25T17:00:00-05:00",
  "created_at": "2026-05-26T12:30:14Z",
  "submodulo": "alianza"
}

GetClientObligationsLidera

Retorna todas las obligaciones activas de un cliente en la cartera Lidera. Estructura de respuesta idéntica a Alianza.

POST /ecollect/api/GetClientObligationsLidera 200 OK

Mismo contrato que GetClientObligationsAlianza: solo se envía client_reference en el body. El tipo_contrato (13597) y entity_code (LIDERA) son fijos en el servidor.

Parámetros

Campo	Tipo	Estado	Descripción
client_reference	string	Requerido	Cédula de ciudadanía del cliente Lidera

cURL — Ejemplo listo para ejecutar

cURL

copiar y pegar

curl -X POST "https://sai.desarrollo.avanzarsoluciones.com/ecollect/api/GetClientObligationsLidera" \
  -H "Authorization: Api-Key DMeixmeN.k4j8s9d2f1g7h3l5n6m0p2q4r6t8v0w2" \
  -H "Content-Type: application/json" \
  -d '{
    "client_reference": "52910357"
  }'

Estructura de respuesta

La respuesta varía según el método de autenticación (mismo comportamiento que GetClientObligationsAlianza):

Api-Key (integración externa): respuesta slim.
Sesión Django (admin/portal): respuesta extendida.

Respuesta slim (Api-Key) — Top-level

Campo	Tipo	Descripción
total_records	integer	Cantidad de obligaciones encontradas
records	array<ObligationRecord>	Lista de obligaciones

Subtipo: `ObligationRecord` (slim)

Campo	Tipo	Descripción
obligation_id	string	ID del deal en Bitrix24
obligation_name	string	Título del deal (campo TITLE)
cedula	string	Cédula del titular (eco del `client_reference` que enviaste)
total_balance	decimal	HONORARIOS original del deal (sin descontar pagos)
pending_balance	decimal	Saldo real pendiente: HONORARIOS original menos pagos registrados
overdue_amount	decimal	Suma de cuotas con fecha ≤ hoy que aún quedan pendientes
minimum_payment_due	decimal	Monto mínimo a pagar HOY
reference_date_used	string	Fecha (ISO 8601) tomada como "hoy" para los cálculos
pending_quotes	array<QuoteRecord>	Detalle de cuotas con saldo pendiente (al final del record por verbosidad)

Subtipo: `QuoteRecord`

Campo	Tipo	Descripción
date	string	Fecha programada de la cuota (ISO 8601)
value	decimal	Valor de la cuota en COP

Ejemplo de respuesta slim (Api-Key)

JSON · 200 OK

{
  "total_records": 1,
  "records": [
    {
      "obligation_id": "822044",
      "obligation_name": "ALFREDO ROJAS VIDAL - CA Prueba",
      "cedula": "1126446660",
      "total_balance": 4388400.0,
      "pending_balance": 728400.0,
      "overdue_amount": 4388400.0,
      "minimum_payment_due": 4388400.0,
      "reference_date_used": "2026-05-28T20:41:52+00:00",
      "pending_quotes": [
        { "date": "2024-11-29T03:00:00+03:00", "value": 844200.0 },
        { "date": "2024-12-30T03:00:00+03:00", "value": 1772100.0 },
        { "date": "2025-01-30T03:00:00+03:00", "value": 1772100.0 }
      ]
    }
  ]
}

Respuesta extendida (sesión Django admin)

Cuando llamas desde el portal admin con cookie de sesión, cada ObligationRecord también incluye: balance_value, currency, stage_id, date_create, category_id, contact_id, paid_amount, total_original_amount, total_contrato, flm_total, prosperar_total, avanzar_total, anticipo_value, anticipo_date, quotes, all_quotes, payment_records.

{
  "total_records": 1,
  "total_balance": 850000.00,
  "records": [
    {
      "obligation_id": "112233",
      "obligation_name": "Lidera - Insolvencia",
      "balance_value": 850000.00,
      "currency": "COP",
      "stage_id": "C130:NEW",
      "date_create": "2026-04-02T09:10:55",
      "category_id": "130",
      "contact_id": "45678",
      "paid_amount": 0.00,
      "total_original_amount": 850000.00,
      "total_contrato": 850000.00,
      "flm_total": 0.00,
      "prosperar_total": 850000.00,
      "avanzar_total": 0.00,
      "anticipo_value": 150000.00,
      "anticipo_date": "2026-05-10",
      "quotes": [
        { "date": "2026-06-10", "value": 350000.00 },
        { "date": "2026-07-10", "value": 350000.00 }
      ],
      "all_quotes": [
        { "date": "2026-06-10", "value": 350000.00 },
        { "date": "2026-07-10", "value": 350000.00 }
      ],
      "payment_records": [
        { "label": "Anticipo", "date": "2026-05-10", "value": 150000.00 },
        { "label": "Pago 1",   "date": null,         "value": null }
      ]
    }
  ]
}

PaymentCreation

Registra oficialmente un pago de un cliente Lidera. Mismo payload e idempotencia que la versión Alianza, pero exige que el negocio sea de tipo 13597.

POST /ecollect/api/internal/pagos/crear-lidera 201 Created

Idéntico contrato que /crear-alianza: payload con id_bitrix, cedula, nombre y sub-objeto ecollect. La única diferencia es que si el Negocio ya existía con un tipo_contrato distinto de "13597", devuelve 400.

Parámetros — nivel raíz

Campo	Tipo	Estado	Descripción
id_bitrix	string	Requerido	ID del Deal en Bitrix24 (numérico)
cedula	string	Requerido	Cédula del titular
nombre	string	Opcional	Nombre completo (solo se persiste si Cliente es nuevo)
ecollect	object	Requerido	Datos del pago en formato ECOllect

Parámetros — sub-objeto `ecollect`

Campo	Tipo	Estado	Descripción
EntityCode	string	Requerido	Código de entidad / cédula en ECOllect
TicketId	string	Requerido	Único — ID del ticket de pago
TrazabilityCode	string	Requerido	Único — código de trazabilidad
TransValue	decimal	Requerido	Monto del pago en COP (`> 0`)
TranState	enum	Requerido	`OK` · `FAIL` · `PENDING` · `REVERSED` · `CANCELLED`
BankProcessDate	datetime	Requerido	Fecha ISO 8601 de procesamiento
UserMail	email	Opcional	Email del cliente
PaymentsArray	array	Opcional	Detalle libre de cuotas pagadas
referencia_interna	string	Opcional	Si se omite, se usa `TicketId`
origen_pago	enum	Opcional	`ecollect` (default)

cURL — Ejemplo listo para ejecutar

cURL

copiar y pegar

curl -X POST "https://sai.desarrollo.avanzarsoluciones.com/ecollect/api/internal/pagos/crear-lidera" \
  -H "Authorization: Api-Key DMeixmeN.k4j8s9d2f1g7h3l5n6m0p2q4r6t8v0w2" \
  -H "Content-Type: application/json" \
  -d '{
    "id_bitrix": "822044",
    "cedula":    "1126446660",
    "nombre":    "ALFREDO ROJAS VIDAL",
    "ecollect": {
      "EntityCode":      "1126446660",
      "TicketId":        "TK-LI-100001",
      "TrazabilityCode": "TRZ-LI-100001",
      "TransValue":      350000,
      "TranState":       "OK",
      "BankProcessDate": "2026-05-25T17:00:00-05:00",
      "UserMail":        "cliente@email.com",
      "PaymentsArray":   [],
      "referencia_interna": "LI-2026-001"
    }
  }'

Introducción

Base URL

Headers requeridos

Autenticación

Formato del header

Verificación rápida

Códigos de error

GetClientObligationsAlianza

Parámetros

cURL — Ejemplo listo para ejecutar

Estructura de respuesta

Respuesta slim (Api-Key) — Top-level

Subtipo: ObligationRecord (slim)

Subtipo: QuoteRecord

Ejemplo de respuesta slim (Api-Key)

Respuesta extendida (sesión Django admin) — solo uso interno

PaymentCreation

Parámetros — nivel raíz

Parámetros — sub-objeto ecollect

cURL — Ejemplo listo para ejecutar

Respuesta

GetClientObligationsLidera

Parámetros

cURL — Ejemplo listo para ejecutar

Estructura de respuesta

Respuesta slim (Api-Key) — Top-level

Subtipo: ObligationRecord (slim)

Subtipo: QuoteRecord

Ejemplo de respuesta slim (Api-Key)

Respuesta extendida (sesión Django admin)

PaymentCreation

Parámetros — nivel raíz

Parámetros — sub-objeto ecollect

cURL — Ejemplo listo para ejecutar

Subtipo: `ObligationRecord` (slim)

Subtipo: `QuoteRecord`

Parámetros — sub-objeto `ecollect`

Subtipo: `ObligationRecord` (slim)

Subtipo: `QuoteRecord`

Parámetros — sub-objeto `ecollect`