Modelos de respuesta en fiscalapi

En esta sección se detallan los modelos de respuesta de FiscalAPI. Se describen los modelos base, que constituyen la estructura común heredada por todos los objetos (como producto, factura y persona), así como los modelos específicos que gestionan tanto las respuestas exitosas como los errores.

Tabla de Contenido

1. Modelos Base
   1.1 AuditableDto
   1.2 BaseDto
   1.3 CatalogDto
2. Modelos de Respuesta
   2.1 ApiResponse<T>
   2.2 ValidationFailure
   2.3 PagedList<T>

1. Modelos Base

Los modelos base son estructuras estándar utilizadas como cimientos para construir respuestas coherentes en la API. Estos modelos siguen un patrón de herencia que permite reutilizar propiedades comunes:

Jerarquía de modelos base

• AuditableDto: Modelo fundamental que proporciona campos de auditoría para rastrear la creación y actualización de registros.

• BaseDto: Hereda AuditableDto agregando un identificador único. Constituye el modelo base para la mayoría de las respuestas en la API.

• CatalogDto: Hereda BaseDto incorporando el campo description. Se utiliza específicamente para representar catálogos del SAT.

Estos modelos base conforman la arquitectura fundamental para todas las respuestas de fiscalapi.

1.1 AuditableDto

Proporciona campos de auditoría para rastrear la creación y actualización de registros.

Properties

Ejemplo:

{
  "createdAt": "2024-02-20T10:30:00",
  "updatedAt": "2024-02-20T15:45:00"
}

1.2 BaseDto

Hereda AuditableDto y agrega un identificador único, siendo el modelo base para la mayoría de las entidades.

Properties

Ejemplo:

{
  "id": "abc123xyz",
  "createdAt": "2024-02-20T10:30:00",
  "updatedAt": "2024-02-20T15:45:00"
}

1.3 CatalogDto

Hereda BaseDto y agrega un campo de descripción. Representa una propiead que es un catálogo del SAT, como el catálogo de unidades de medida, metodos de pago, regimen fiscal, etc.

Properties

Ejemplo:

{
  "id": "cat123",
  "description": "Elemento de catálogo de ejemplo",
  "createdAt": "2024-02-20T10:30:00",
  "updatedAt": "2024-02-20T15:45:00"
}

2. Modelos de Respuesta

Estos modelos definen la estructura estandarizada que utiliza FiscalAPI para comunicar resultados de operaciones, incluyendo tanto respuestas exitosas como errores.

2.1 ApiResponse<T>

Modelo estándar de respuesta en fiscalapi, encapsula la carga útil (paylad response), el estado de la operación y metadatos adicionales. El tipo genérico T representa el tipo de datos que se espera en la carga útil de la respuesta.

Properties

Ejemplo:

{
  "data": {
    "invoiceNumber": "FAP240304AU3-1",
    "date": "2023-11-11T14:35:18",
    "issuerTin": "FAP240304AU3",
    "total": 197.80,
    "currencyCode": "MXN",
    "status": "Vigente",
    "...": "..."
  },
  "succeeded": true,
  "message": "Operación exitosa",
  "details": "",
  "httpStatusCode": 200,
  "traceIdentifier": "ABC123XYZ"
}

2.2 ValidationFailure

Modelo que describe las fallas de validación detectadas antes de procesar la solicitud. Se utiliza en respuestas con código HTTP 400 (Bad Request) para informar al cliente sobre los errores de validación.

Properties

Ejemplo:

{
  "data": [
    {
      "propertyName": "Password",
      "errorMessage": "The length of 'Password' must be at least 6 characters. You entered 5 characters.",
      "attemptedValue": "12345",
      "severity": 0,
      "errorCode": "MinimumLengthValidator"
    },
    {
      "propertyName": "Password",
      "errorMessage": "Password must be at least 6 characters long and contain at least one uppercase letter, one lowercase letter, one digit, and one non-alphanumeric character.",
      "attemptedValue": "12345",
      "severity": 0,
      "errorCode": "PredicateValidator"
    }
  ],
  "succeeded": false,
  "message": "Se han producido errores de validación.",
  "details": "One or more validation failures have occurred.",
  "httpStatusCode": 400,
  "traceIdentifier": "1071497CFECD493A975F14A639CF2B6B"
}

2.3 PagedList<T>

Modelo utilizado para respuestas paginadas, encapsulando tanto la lista de elementos como la información de paginación.

Properties

Ejemplo:

{
  "data": {
    "items": [
      {
        "invoiceNumber": "INV001",
        "date": "2023-05-01T10:00:00",
        "issuerTin": "XAXX010101000",
        "total": 120.50
      },
      {
        "invoiceNumber": "INV002",
        "date": "2023-05-02T09:30:00",
        "issuerTin": "XEXX010101000",
        "total": 95.00
      }
    ],
    "pageNumber": 1,
    "totalPages": 3,
    "totalCount": 5,
    "hasPreviousPage": false,
    "hasNextPage": true
  },
  "succeeded": true,
  "message": "Se ha obtenido la lista de facturas",
  "details": "",
  "httpStatusCode": 200,
  "traceIdentifier": "XYZ789ABC"
}