Documentación / Proformas
Estructura de Respuesta: Proforma
Todas las estructuras JSON de respuesta del módulo de proformas, incluyendo los tipos de cada campo, sus valores posibles y los endpoints que las devuelven, para que el frontend y la generación de PDF usen referencias estables.
ProformaResponseDto — Proforma completa
Esta estructura es devuelta por los endpoints POST /proformas, GET /proformas/:id, PATCH /proformas/:id/pay, PATCH /proformas/:id/cancel y PUT /proformas/:id. La respuesta usa un objeto raíz proforma.
Datos principales
| Campo | Tipo | Descripción |
|---|---|---|
| prfmaid | string | ID único (UUID) de la proforma. |
| prfmaidentificador | string | Identificador legible generado como `{emcodigo}-{suidentificador}-{cjidentificador}-{secuencia}`. |
| prfmaestado | string | Estado actual. Valores: `emitida`, `pagada`, `anulada`. |
| prfmafchregistro | Date | Fecha y hora de creación. |
| prfmafchactualizacion | Date | Fecha de última modificación. |
Emisor — Quién emite
empresa
| Campo | Tipo | Descripción |
|---|---|---|
| emid | string | ID único de la empresa. |
| emruc | string | null | RUC de la empresa. |
| emcodigo | string | null | Código interno. |
| emcorreo | string | null | Correo electrónico. |
| emlogo | string | null | URL pública del logo. |
| emrznsocial | string | null | Razón social. |
sucursal
| Campo | Tipo | Descripción |
|---|---|---|
| suid | string | ID único de la sucursal. |
| suidentificador | string | null | Identificador (3 dígitos). |
| sunombre | string | null | Nombre de la sucursal. |
caja
| Campo | Tipo | Descripción |
|---|---|---|
| cjid | string | ID único de la caja. |
| cjidentificador | string | null | Identificador de la caja. |
usuario
| Campo | Tipo | Descripción |
|---|---|---|
| usid | string | ID único del usuario. |
| usnombre | string | null | Nombre del usuario. |
| usrol | string | null | Rol: `administrador`, `jefe`, `empleado`. |
Receptor — Información del cliente
| Campo | Tipo | Descripción |
|---|---|---|
| clnteid | string | ID único del cliente. |
| clnteidentificacion | string | null | Cédula o RUC. |
| clntenombre | string | null | Nombre o razón social. |
| clntecorreo | string | null | Correo electrónico. |
| clntedireccion | string | null | Dirección física. |
| clntetelefono | string | null | Teléfono. |
Método de pago
| Campo | Tipo | Descripción |
|---|---|---|
| mpid | string | ID único del método de pago. |
| mpnombre | string | null | Nombre del método de pago. |
Total — Resumen monetario
| Campo | Tipo | Descripción |
|---|---|---|
| prfmasubtotal | number | Suma de totales de todas las líneas. |
| prfmadescuento | number | Descuento total. Si no hay, vale 0. |
| prfmatotal | number | Total final (`subtotal - descuento`). |
Detalle — Items
Arreglo de objetos. Cada elemento representa una línea del detalle.
| Campo | Tipo | Descripción |
|---|---|---|
| dprfmaid | string | ID único de la línea. |
| dprfmatipoitem | string | `inventariable` o `manual`. |
| producto | object | Datos del producto (ver abajo). |
producto
| Campo | Tipo | Descripción |
|---|---|---|
| dprfmacodigo | string | null | Código del producto. `null` si es manual. |
| dprfmadescripcion | string | null | Descripción del producto o servicio. |
| dprfmacantidad | number | Cantidad. Siempre mayor a 0. |
| dprfmapreciounitario | number | Precio unitario. |
| dprfmapreciototal | number | Total de la línea. |
Documento — PDF asociado
| Campo | Tipo | Descripción |
|---|---|---|
| docnombre | string | null | Nombre del archivo PDF. |
| docurl | string | null | URL pública completa del PDF. |
FindProformasResponseDto — Listado paginado
Devuelto por GET /proformas. Cada elemento de items es un ProformaResponseDto completo.
| Campo | Tipo | Descripción |
|---|---|---|
| items | ProformaResponseDto[] | Arreglo de proformas completas. |
| page | number | Página actual. |
| pageSize | number | Tamaño de página. |
| totalItems | number | Total de proformas. |
| totalPages | number | Total de páginas. |
ProformaPdfResponseDto — Referencia del PDF
Devuelto por GET /proformas/:id/pdf. Versión reducida que solo incluye los datos del documento.
| Campo | Tipo | Descripción |
|---|---|---|
| proforma.prfmaid | string | ID único de la proforma. |
| proforma.prfmaidentificador | string | Identificador legible. |
| proforma.documento.docnombre | string | null | Nombre del archivo PDF. |
| proforma.documento.docurl | string | null | URL pública del PDF. |
Endpoints y respuestas
| Endpoint | Método | Código | Respuesta |
|---|---|---|---|
| /proformas | POST | 201 | ProformaResponseDto |
| /proformas | GET | 200 | FindProformasResponseDto |
| /proformas/:id | GET | 200 | ProformaResponseDto |
| /proformas/:id | PUT | 200 | ProformaResponseDto |
| /proformas/:id/pay | PATCH | 200 | ProformaResponseDto |
| /proformas/:id/cancel | PATCH | 200 | ProformaResponseDto |
| /proformas/:id/pdf | GET | 200 | ProformaPdfResponseDto |
| /proformas/:id/send | POST | 200 | { message } |
Notas importantes
Raíz `proforma`: todas las respuestas envuelven los datos en un objeto con clave `proforma`. Accede siempre como `response.proforma.*`.
`emlogo` y `docurl`: son URLs públicas completas. No necesitas concatenar una URL base.
`dprfmatipoitem`: se deriva de `dprfmaesinventariable`: `true` → `"inventariable"`, `false` → `"manual"`.
`producto.dprfmacodigo`: es `null` para items manuales.
Listado paginado: `GET /proformas` devuelve la estructura completa en `items[]`, no un resumen.
Fechas: `prfmafchregistro` y `prfmafchactualizacion` son ISO 8601.
`prfmaidentificador`: se genera automáticamente al crear la proforma y no cambia.
PDF: se genera automáticamente al crear, pagar, anular o reemplazar una proforma.
`docnombre` y `docurl`: pueden ser `null` si el PDF no se ha generado.