RECURSO DE LA API

Cobros y finanzas

Factura, cobro idempotente, saldo de cuenta corriente, conciliación de cierre de día y e-Fatura. El dinero se maneja con numeric(14,2); el saldo de cuenta corriente se deriva, no se escribe manualmente.

Acceso anticipado Toda la API

Endpoints

12 endpoint

Endpoints de este recurso. Cada endpoint se limita a los datos de la clínica a la que está vinculada la clave de la API; los endpoints de escritura admiten la cabecera Idempotency-Key.

POST /v1/invoices Crea una factura admin · secretaria · médico

GET /v1/invoices Lista las facturas admin

GET /v1/invoices/{id} Obtiene el detalle de la factura Todos los roles autorizados

POST /v1/invoices/{id}/void Anula la factura (asiento inverso) admin

POST /v1/invoices/{id}/einvoice Envía la factura como e-Fatura (GİB) admin

GET /v1/einvoices Lista los registros de e-Fatura admin

POST /v1/payments Registra un cobro (idempotente) admin · secretaria · médico

GET /v1/patients/{id}/balance Obtiene el saldo de cuenta corriente del paciente Todos los roles autorizados

GET /v1/patients/{id}/ledger Lista los movimientos de cuenta corriente del paciente Todos los roles autorizados

GET /v1/cash/day Obtiene el resumen de caja de cierre de día admin · secretaria

GET /v1/cari Lista los saldos de cuenta corriente admin · secretaria

GET /v1/billing/summary Obtiene el resumen de finanzas/cobros admin · secretaria

Ejemplo de uso

Registrar cobro (idempotente)

Solicitud

curl -X POST https://api.udentiva.com/v1/payments \
  -H "Authorization: Bearer udk_live_xxx" \
  -H "Idempotency-Key: pay-7c3f..." \
  -H "Content-Type: application/json" \
  -d '{"patient_id":"c0ffee00-...","amount":"1500.00","method":"card"}'

Respuesta

HTTP/1.1 201 Created
{
  "id": "pmt-9001",
  "amount": "1500.00",
  "method": "card",
  "created_at": "2026-06-24T09:15:00Z"
}

# Aynı Idempotency-Key ile tekrar → aynı kayıt döner, ikinci tahsilat OLUŞMAZ.

Seguridad en este recurso

La seguridad no es una función, es la propia arquitectura. Las garantías vigentes en este recurso:

Cobro idempotente: gracias a Idempotency-Key + bloqueo del servidor, el mismo pago no se registra dos veces ni siquiera en un reintento de red (no hay doble cobro).

El dinero es siempre numeric(14,2); no se realiza aritmética con el importe proveniente del cliente, el redondeo se hace en un único punto en el servidor.

Anulación/reembolso = asiento inverso (void/refund); la línea no se elimina físicamente. El saldo de cuenta corriente se deriva como Σfactura − Σpago.

La operación multi-entidad (factura + línea + pago) es atómica en una única transaction: o todo o nada.

Todo el modelo de seguridad →

Formato de error

Los errores se devuelven con un sobre coherente; el código va dirigido a la máquina, el mensaje al usuario. El error interno o el stack nunca se filtran.

{
  "error": {
    "code": "validation_failed",
    "message": "Campo no válido: correo electrónico"
  }
}

Otros recursos

Pacientes Citas y calendario Odontograma y Tratamiento Inventario Imágenes Laboratorio Lead y CRM Turismo de salud Informes y BI Webhooks Transferencia de Datos (Export API)

¿Quiere acceso anticipado?

Sea el primero en enterarse cuando se abra la API.

Contactar