Urbanor Cobranza

API de Integración · Guía Técnica para Sistemas Externos · Bancos · M2M

v1.0 REST · JSON

Autenticación

Todo acceso a los endpoints protegidos requiere un Bearer Token. El token se obtiene intercambiando las credenciales del API Client.

⚠ IMPORTANTE: Las credenciales (clientId y clientSecret) son provistas por el equipo de Urbanor. No las compartas ni las incluyas en código público.

POST {baseUrl}/api/v1/auth/token

Headers

Content-Type: application/json

Body

{
  "clientId":     "550e8400-e29b-41d4-a716-446655440000",
  "clientSecret": "a3f1c9e2b847d6f0a1e5..."
}

Parámetros

Campo	Tipo	Descripción
`clientId`	string	UUID del cliente registrado
`clientSecret`	string	Secret de 64+ caracteres provisto por Urbanor

Respuesta exitosa 200

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType":   "Bearer",
  "expiresIn":   3600
}

Uso en requests posteriores

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

💡 TIP: El token expira en expiresIn segundos (generalmente 1 hora). Renuévalo antes de que expire volviendo a llamar a {baseUrl}/api/v1/auth/token.

Consultar Deuda

GET {baseUrl}/api/v1/deuda/:termino

Consulta la deuda de un cliente. El parámetro :termino es flexible y acepta tres formatos.

Headers

Authorization: Bearer <token>

Modos de búsqueda

Formato	Ejemplo	Descripción
Código de cliente	`C0005077`	Código alfanumérico del cliente
C.I.	`13103597`	Solo dígitos
Código de lote	`LB112A076050LT`	Acepta con o sin guiones, con Ñ o sin Ñ

ℹ NOTA: El código de lote puede enviarse con o sin guiones, y con Ñ o sin Ñ — ambos formatos son aceptados. La respuesta siempre devuelve el código con guiones y con Ñ en su formato original.

Formatos aceptados para código de lote

Lote real	Variantes aceptadas en URL
`LB1-12A-076-050-LT`	`LB112A076050LT` o `LB1-12A-076-050-LT`
`SI1-00Ñ-001-001-LT`	`SI100001001LT` o `SI1-00Ñ-001-001-LT`

Ejemplos de request

# Por código de cliente
GET {baseUrl}/api/v1/deuda/C0005077

# Por C.I.
GET {baseUrl}/api/v1/deuda/13103597

# Por lote (con o sin guiones)
GET {baseUrl}/api/v1/deuda/LB112A076050LT

Respuesta exitosa 200

{
  "status":   200,
  "messages": ["Deuda obtenida correctamente"],
  "data": {
    "NombreCliente":    "ESTEFANIA CAYARA CRUZ",
    "CodigoReferencia": "C0005077",
    "NITCI":            "7648995",
    "DetalleLotes": [
      {
        "CodigoLote":  "LB1-12A-076-050-LT",
        "DetalleDeuda": [
          {
            "NroCuota":        14,
            "MesPeriodo":       7,
            "AnioPeriodo":      2026,
            "FechaVencimiento": "2026-07-07T00:00:00.000Z",
            "MontoNeto":        696.28,
            "MontoMulta":       0,
            "MontoTotal":       696.28
          }
        ]
      }
    ]
  }
}

Registrar Pago

POST {baseUrl}/api/v1/pagos

Headers

Authorization: Bearer <token>
Content-Type: application/json

3.1 Campos del Body

Campo	Tipo	Req.	Descripción
`codigoCliente`	string	✓	Código del cliente. Ej: `C0005077`
`loteId`	string	✓	Código del lote con guiones. Ej: `LB1-12A-076-050-LT`
`referenciaBancaria`	string	✓	Número de voucher o referencia del banco
`fechaPago`	string	✓	ISO 8601: `YYYY-MM-DDTHH:mm:ss`
`origenPago`	string	✓	`APP_MOVIL` · `BANCA_INTERNET` · `VENTANILLA` · `ATM`
`montoTotal`	number	✓	Total procesado por el banco (suma de todas las cuotas)
`cuotas`	array	✓	Lista de cuotas pagadas (mínimo 1, deben ser consecutivas)

3.2 Campos de cada cuota cuotas[]

Campo	Tipo	Req.	Descripción
`nroCuota`	integer	✓	Número de cuota (entero positivo)
`montoCuota`	number	✓	Monto base de la cuota sin multa
`montoMulta`	number	✓	Monto de multa. Enviar `0` si no hay multa
`datosFactura`	object	—	Datos de la factura emitida por el banco (opcional)

3.3 Campos de datosFactura

Campo	Tipo	Req.	Descripción
`NroFactura`	integer	✓	Número de factura
`FechaEmision`	string	✓	Formato `YYYY-MM-DD`. Ej: `2026-04-17`
`NroAutorizacion`	integer	✓	Número de autorización SIN
`CodigoControl`	string	✓	Código de control de la factura
`FacturaNITCI`	integer	✓	NIT o CI del facturado
`FacturaNombre`	string	✓	Nombre del facturado
`TotalFacturado`	number	✓	Total en Bs. Ej: `696.28`

3.4 Reglas de validación de cuotas

→ Las cuotas deben ser consecutivas entre sí. No se puede pagar la cuota 16 sin incluir la 15.

→ No se permiten números de cuota duplicados.

→ nrosCuota deben ser enteros positivos.

→ La multa puede ser 0 si la cuota no tiene penalización.

3.5 Ejemplos

Pago simple (sin factura)

{
  "codigoCliente":      "C0005077",
  "loteId":             "LB1-12A-076-050-LT",
  "referenciaBancaria": "1234567893721",
  "fechaPago":          "2026-04-17T14:30:00",
  "origenPago":         "BANCA_INTERNET",
  "montoTotal":         1392.56,
  "cuotas": [
    { "nroCuota": 15, "montoCuota": 696.28, "montoMulta": 0 },
    { "nroCuota": 16, "montoCuota": 696.28, "montoMulta": 0 }
  ]
}

Pago con datos de factura

{
  "codigoCliente":      "C0005077",
  "loteId":             "LB1-12A-076-050-LT",
  "referenciaBancaria": "1234567893721",
  "fechaPago":          "2026-04-17T14:30:00",
  "origenPago":         "BANCA_INTERNET",
  "montoTotal":         796.28,
  "cuotas": [
    {
      "nroCuota":   15,
      "montoCuota":  696.28,
      "montoMulta": 100,
      "datosFactura": {
        "NroFactura":      777,
        "FechaEmision":    "2026-04-17",
        "NroAutorizacion": 321,
        "CodigoControl":   "45D22CE502FA8B6F35948E4FAD8F98C168B643DD",
        "FacturaNITCI":    7648995,
        "FacturaNombre":   "ELIZETH DURAN DURAN",
        "TotalFacturado":  100  // factura solo multa
      }
    },
    {
      "nroCuota":   16,
      "montoCuota":  696.28,
      "montoMulta": 0
    }
  ]
}

Respuesta exitosa 201

{
  "status":   201,
  "messages": ["Pago registrado correctamente"],
  "data": {
    "id":                 142,
    "codigoCliente":      "C0005077",
    "loteId":             "LB1-12A-076-050-LT",
    "montoTotal":         796.28,
    "fechaPago":          "2024-08-09T14:30:00.000Z",
    "origenPago":         "BANCA_INTERNET",
    "banco":              "NOMBRE_BANCO",
    "referencia":         "1234567893721"
  }
}

Manejo de Errores

Todos los errores siguen el mismo formato:

{
  "status":   400,
  "messages": ["codigoCliente debe tener el formato: 1 a 3 letras seguidas de números"]
}

Códigos HTTP

400 Validación fallida — revisa los campos del body

401 Token ausente, inválido o expirado

403 El API Client no tiene el permiso requerido

404 Cliente o deuda no encontrada

409 Pago duplicado — la referencia bancaria ya existe

500 Error interno del servidor

Urbanor Cobranza · Documentación Técnica · Página 1 de 1