Sofi — Plataforma Digital para tu Empresa

Desarrolladores

Documentación de la API

API RESTful versionada. Cada endpoint está descrito con su propósito, parámetros y un ejemplo listo para usar — sin importar el lenguaje con el que trabajes.

Cómo autenticarse

Obligatorio en todas las rutas protegidas

Antes de llamar a cualquier endpoint protegido necesitas un Bearer token — lo obtienes con el login — y un header X-Tenant que identifica a qué empresa pertenece la petición. Ambos van en cada request; sin ellos la API responde 401 Unauthorized.

Headers requeridos

Authorization

Bearer {token}

Token JWT devuelto por /auth/login. Expira en 60 min; usa /auth/refresh para renovarlo.

X-Tenant

{slug_de_tu_marca}

Identificador único de tu empresa en Sofi. Todos los datos devueltos estarán acotados a ese tenant.

Accept

application/json

Necesario para que los errores se devuelvan en JSON en lugar de HTML.

Ejemplo: obtener token

POST /api/v1/auth/login

curl -X POST https://tu-dominio.com/api/v1/auth/login \
  -H "X-Tenant: mi_empresa" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"ana@empresa.com","password":"****"}'

// 200 OK
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
  "user": {
    "id": 42, "name": "Ana García",
    "role": "client"
  }
}

Autenticación & sesión

Gestión de credenciales y ciclo de vida del token JWT.

POST

Inicia sesión /api/v1/auth/login

Recibe email y password. Devuelve el Bearer token JWT y el perfil del usuario. Este es el primer paso antes de cualquier otra llamada.

GET

Perfil del usuario /api/v1/auth/me

Retorna nombre, email, rol, permisos y configuraciones del usuario autenticado en el tenant activo.

POST

Renovar token /api/v1/auth/refresh

Genera un nuevo token antes de que el actual expire, sin necesidad de volver a ingresar las credenciales. Útil para sesiones largas.

POST

Recuperar contraseña /api/v1/auth/forgot-password

Inicia el flujo de recuperación enviando un código de verificación al email del usuario.

POST

Restablecer con código /api/v1/auth/reset-with-code

Valida el código recibido por email y permite establecer una nueva contraseña. Invalida el código tras usarlo.

POST

Cerrar sesión /api/v1/auth/logout

Invalida el token actual en el servidor. El cliente debe descartarlo localmente. No acepta más peticiones con ese token.

Códigos de respuesta

200

Petición exitosa. El body contiene los datos solicitados.

201

Created

Recurso creado correctamente (POST).

401

Unauthorized

Token ausente, inválido o expirado. Vuelve a hacer login.

403

Forbidden

Token válido pero sin permisos para esta operación.

422

Unprocessable

Validación fallida. El campo "errors" detalla los problemas.

404

Not Found

El recurso solicitado no existe en este tenant.

500

Server Error

Error interno. Reportar con el request ID si está disponible.

Contratos & pagos

Consulta contratos del usuario y su historial financiero. Los datos se sincronizan con el ERP cuando hay conector activo.

GET

Mis contratos /api/v1/contracts

Lista todos los contratos vinculados al usuario autenticado: número, estado, saldo pendiente y próxima fecha de pago.

GET

Detalle del contrato /api/v1/contracts/{id}

Devuelve todos los campos del contrato: partes, servicios incluidos, vigencia, condiciones y datos del responsable de cuenta.

GET

Estado de cuenta /api/v1/contracts/{num}/account-statement

Balance actualizado: cargos aplicados, pagos registrados, saldo a favor o adeudo. Siempre refleja la última sincronización con el ERP.

GET

Descargar estado de cuenta (PDF) /api/v1/contracts/{num}/account-statement/pdf

Genera y devuelve el PDF del estado de cuenta con el diseño de la empresa. Listo para enviar al cliente sin pasos adicionales.

GET

Historial de pagos /api/v1/contracts/{id}/payments

Lista cronológica de cada pago: monto, fecha, referencia de transacción y método utilizado (BillPocket, Recaudo, efectivo, etc.).

POST

Registrar pago /api/v1/contracts/pay

Crea un nuevo movimiento de pago sobre el contrato indicado. Compatible con los gateways configurados en el panel (BillPocket, Recaudo).

GET /api/v1/contracts

curl https://tu-dominio.com/api/v1/contracts \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Tenant: mi_empresa" \
  -H "Accept: application/json"

// 200 OK
{
  "data": [
    {
      "id": 1,
      "number": "C-2024-0042",
      "status": "active",
      "balance": 1500.00,
      "next_payment": "2026-07-15"
    }
  ]
}

Obituarios & Condolencias

Publica obituarios, recibe mensajes de condolencia y genera el libro PDF personalizado con la plantilla visual de la empresa.

GET

Listar obituarios /api/v1/obituaries

Devuelve los obituarios publicados del tenant: nombre del difunto, fechas de velación y sepelio, número de condolencias recibidas y estado de publicación.

GET

Detalle del obituario /api/v1/obituaries/{id}

Información completa: datos del difunto, mensaje de la familia, fechas y lugar de los servicios, y todas las condolencias aprobadas recibidas hasta el momento.

POST

Enviar condolencia /api/v1/obituaries/{id}/condolences

Publica un mensaje de condolencia en el obituario indicado. Si la empresa tiene moderación activa, el mensaje queda pendiente hasta ser aprobado desde el panel.

GET

Generar PDF de condolencias /api/v1/obituaries/{id}/condolences/pdf

Genera al vuelo el PDF con todas las condolencias aprobadas, usando la plantilla visual configurada en el panel: colores, tipografía, imágenes y páginas de portada.

POST

Enviar PDF por WhatsApp /api/v1/obituaries/{id}/condolences/send-whatsapp

Envía automáticamente el PDF compilado de condolencias al número del familiar registrado en el contrato, a través del canal de WhatsApp configurado en el tenant.

PATCH

Aprobar / rechazar condolencia /api/v1/obituaries/{id}/condolences/{cid}/status

Actualiza el estado de moderación de una condolencia (approved / rejected). Requiere rol de operador o administrador dentro del tenant.

Rastreo de servicios

Seguimiento en tiempo real del servicio. Tanto el cliente como el operador en campo pueden consultar y actualizar el estado.

GET

Mis servicios /api/v1/orders

Lista todos los servicios y pedidos del usuario con su estado actual: pendiente, en camino, en curso o completado.

GET

Detalle del servicio /api/v1/orders/{id}

Información completa: operador asignado, ubicación actual, historial de estados con timestamps y datos de contacto del equipo.

GET

Seguimiento por código /api/v1/orders/{code}/details

Vista de seguimiento usando el código público del servicio. Útil para compartir el link de rastreo con el cliente sin requerir login.

GET

Servicios del operador /api/v1/driver-app/services

Lista los servicios activos asignados al operador autenticado: dirección, hora programada y datos de contacto del cliente.

POST

Confirmar llegada /api/v1/driver-app/services/{code}/arrived

El operador confirma su llegada al punto de servicio. Dispara automáticamente una notificación push al cliente informándole que el equipo está presente.

POST

Completar servicio /api/v1/driver-app/services/{code}/complete

Marca el servicio como completado. Actualiza el estado en el ERP si hay conector activo y envía la notificación de cierre al cliente.

GET /api/v1/orders/{id}

// 200 OK — detalle del servicio
{
  "id": 318,
  "code": "SVC-2026-0318",
  "status": "in_progress",
  "driver": {
    "name": "Carlos López",
    "phone": "+52 55 1234 5678"
  },
  "timeline": [
    { "status": "assigned",   "at": "10:05" },
    { "status": "arrived",    "at": "10:42" },
    { "status": "in_progress","at": "10:45" }
  ]
}

Notificaciones

Centro de notificaciones push y en-app. Gestiona el historial, el estado de lectura y las preferencias de cada usuario.

GET

Listar notificaciones /api/v1/notifications

Devuelve el historial completo de notificaciones del usuario autenticado, ordenadas de más reciente a más antigua, con su estado de lectura.

GET

Conteo de no leídas /api/v1/notifications/unread-count

Retorna únicamente el número de notificaciones sin leer. Diseñado para actualizar badges en tiempo real sin traer el listado completo.

GET

Preferencias push /api/v1/notifications/settings

Devuelve la configuración actual del usuario: qué tipos de eventos activan una notificación push (pagos, rastreo, condolencias, chat, etc.).

PUT

Actualizar preferencias /api/v1/notifications/settings

Permite al usuario activar o desactivar cada categoría de notificaciones push individualmente. Los cambios aplican de inmediato en el servidor.

POST

Marcar como leída /api/v1/notifications/{id}/read

Marca una notificación específica como leída. El conteo de no leídas se actualiza automáticamente.

POST

Marcar todas como leídas /api/v1/notifications/read-all

Marca en una sola llamada todas las notificaciones pendientes del usuario como leídas. Útil para el botón "limpiar todo" de la app.

Chat con soporte

Canal de mensajería en tiempo real entre el usuario y el equipo de la empresa. Los mensajes se sincronizan con la bandeja del operador en el panel.

GET

Listar conversaciones /api/v1/chat/conversations

Devuelve todas las conversaciones activas del usuario con soporte: último mensaje, estado (abierta / cerrada) y fecha de actividad reciente.

POST

Iniciar o continuar conversación /api/v1/chat/conversations

Crea una nueva conversación de soporte o recupera la existente si ya hay una activa. Nunca genera duplicados para el mismo usuario.

GET

Leer mensajes /api/v1/chat/conversations/{id}/messages

Recupera el historial completo de mensajes de la conversación, con autor, contenido, timestamp y estado de entrega.

POST

Enviar mensaje /api/v1/chat/conversations/{id}/messages

Publica un nuevo mensaje del usuario en la conversación. El operador lo recibe en tiempo real en el panel de soporte.

POST

Cerrar conversación /api/v1/chat/conversations/{id}/close

Marca la conversación como resuelta. Genera el resumen en el historial y libera al operador. El usuario puede abrir una nueva cuando lo necesite.

POST /api/v1/chat/conversations/{id}/messages

curl -X POST .../messages \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Tenant: mi_empresa" \
  -d '{"message":"Hola, tengo una duda sobre mi contrato"}'

// 201 Created
{
  "id": 891,
  "author": "Ana García",
  "message": "Hola, tengo una duda...",
  "sent_at": "2026-06-24T10:31:00Z"
}

Exportaciones & PDFs

Genera y descarga documentos en PDF al vuelo. Todos usan el diseño de la empresa configurado en el panel — sin pasos adicionales.

GET

Comprobante de pago (PDF) /api/v1/exports/invoices/{id}/pdf

Descarga el PDF del comprobante o factura de un pago registrado. Incluye folio, monto, fecha, referencia de transacción y datos de la empresa.

GET

PDF de orden de servicio /api/v1/exports/orders/{id}/pdf

Genera el PDF completo de una orden: datos del cliente, servicios contratados, operador asignado, costos y firmas si aplica.

GET

Ticket de orden /api/v1/exports/orders/{id}/ticket

Versión simplificada de la orden en formato ticket, optimizada para impresión térmica. Contiene solo los campos esenciales para entrega al cliente.

GET

Estado de cuenta (PDF) /api/v1/contracts/{num}/account-statement/pdf

PDF del estado de cuenta con cargos, abonos y saldo del periodo seleccionado. Usa la plantilla corporativa de la empresa con logo y colores propios.

GET

PDF de condolencias /api/v1/obituaries/{id}/condolences/pdf

PDF compilado con todas las condolencias aprobadas del obituario, usando la plantilla visual personalizada: portada, páginas interiores y cierre con el diseño de la empresa.

Todos los endpoints de exportación devuelven Content-Type: application/pdf. Para guardar el archivo, usa -o archivo.pdf en curl o maneja el stream binario en tu cliente HTTP.

Tienda integrada

Catálogo de productos, carrito de compras y pedidos de tiendas integradas en la app (florería, cafetería, etc.). Cada tienda es un {shop} distinto configurado en el panel.

GET

Categorías del catálogo /api/v1/shops/{shop}/grupos-articulos

Lista las categorías o grupos de artículos disponibles en la tienda indicada. Úsalas para construir el menú de navegación del catálogo.

GET

Detalle de producto /api/v1/shops/{shop}/articulo/{id}

Devuelve toda la información de un artículo: nombre, descripción, precio, imágenes, disponibilidad y variantes si aplica.

GET

Artículos por categoría /api/v1/shops/{shop}/grupo-articulo/{id}

Lista los artículos que pertenecen a una categoría específica. Incluye precio, imagen y stock actual.

GET

Ver carrito /api/v1/shops/{shop}/carrito

Recupera los artículos actualmente en el carrito del usuario autenticado para esta tienda.

POST

Añadir al carrito /api/v1/shops/{shop}/carrito

Agrega un artículo al carrito con la cantidad indicada. Si el artículo ya existe, suma la cantidad.

PUT

Actualizar cantidad /api/v1/shops/{shop}/carrito/{id}

Modifica la cantidad de un artículo específico en el carrito. Envía cantidad 0 para eliminarlo.

DELETE

Quitar del carrito /api/v1/shops/{shop}/carrito/{id}

Elimina un artículo del carrito del usuario. No afecta el inventario hasta que se procese el checkout.

POST

Realizar pedido /api/v1/shops/{shop}/checkout

Procesa el carrito como un pedido. Valida disponibilidad, aplica el método de pago y genera la orden. Devuelve el ID del pedido creado.

GET

Opciones de entrega /api/v1/shops/{shop}/delivery-options

Lista los métodos de envío disponibles para la tienda: entrega a domicilio, recolección en sucursal y sus costos.

GET

Mis pedidos de tienda /api/v1/shops/{shop}/pedidos

Historial de pedidos realizados por el usuario en esta tienda, con estado, artículos y fecha.

GET /api/v1/shops/floreria/grupos-articulos

curl .../shops/floreria/grupos-articulos \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Tenant: mi_empresa"

// 200 OK
{
  "data": [
    { "id": 1, "nombre": "Arreglos",    "total": 12 },
    { "id": 2, "nombre": "Coronas",     "total": 8  },
    { "id": 3, "nombre": "Bouquets",    "total": 15 }
  ]
}

POST /api/v1/shops/floreria/checkout

curl -X POST .../shops/floreria/checkout \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Tenant: mi_empresa" \
  -d '{"payment_method":"billpocket","address_id":5}'

// 201 Created
{
  "order_id": 2041,
  "status": "pending",
  "total": 850.00,
  "estimated_delivery": "45 min"
}

Base URL: https://tu-dominio.com/api/v1 · Todos los endpoints devuelven JSON · Errores: {"message":"...","errors":{}}

La plataforma que
digitaliza y escala
tu negocio

Todo lo que tu empresa necesita,
en una sola plataforma

Obituarios digitales

Condolencias con PDF

Gestión de contratos

Tiendas integradas

Rastreo del servicio

Notificaciones push

Integración ERP

Panel administrativo

Facturación e invoices

Se conecta con lo que
ya usas

Una app que tus clientes
quieren usar

Una plataforma,
infinitas marcas

Infraestructura robusta
lista para escalar

Laravel 11

Flutter

Firebase

PostgreSQL

Mensajería WhatsApp

Conector ERP

PDF inteligente

Documentación de la API

Cómo autenticarse

Autenticación & sesión

Contratos & pagos

Obituarios & Condolencias

Rastreo de servicios

Notificaciones

Chat con soporte

Exportaciones & PDFs

Tienda integrada

Lleva tu empresa
al siguiente nivel

La plataforma que digitaliza y escala tu negocio

Todo lo que tu empresa necesita, en una sola plataforma

Obituarios digitales

Condolencias con PDF

Gestión de contratos

Tiendas integradas

Rastreo del servicio

Notificaciones push

Integración ERP

Panel administrativo

Facturación e invoices

Se conecta con lo que ya usas

Una app que tus clientes quieren usar

Una plataforma, infinitas marcas

Infraestructura robusta lista para escalar

Laravel 11

Flutter

Firebase

PostgreSQL

Mensajería WhatsApp

Conector ERP

PDF inteligente

Documentación de la API

Cómo autenticarse

Autenticación & sesión

Contratos & pagos

Obituarios & Condolencias

Rastreo de servicios

Notificaciones

Chat con soporte

Exportaciones & PDFs

Tienda integrada

Lleva tu empresa al siguiente nivel

La plataforma que
digitaliza y escala
tu negocio

Todo lo que tu empresa necesita,
en una sola plataforma

Se conecta con lo que
ya usas

Una app que tus clientes
quieren usar

Una plataforma,
infinitas marcas

Infraestructura robusta
lista para escalar

Lleva tu empresa
al siguiente nivel