Modelos de respuesta en Fiscalapi

Esta página describe los modelos de respuesta de FiscalAPI: los modelos base, que definen la estructura común que heredan todos los objetos (como producto, factura y persona), y los modelos que envuelven las respuestas exitosas y los errores.

1. Modelos base

Los modelos base forman una cadena de herencia que reutiliza las propiedades comunes. AuditableDto aporta las fechas de creación y de última actualización. BaseDto lo hereda, agrega el identificador único y es la base de la mayoría de las respuestas de la API. CatalogDto hereda BaseDto y agrega description para representar los catálogos del SAT.

1.1 AuditableDto

Campos de auditoría que registran cuándo se creó un registro y cuándo se actualizó por última vez.

Propiedades

Ejemplo:

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

1.2 BaseDto

Hereda AuditableDto y agrega el identificador único del registro. Es la base de la mayoría de las entidades.

Propiedades

Ejemplo:

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

1.3 CatalogDto

Hereda BaseDto y agrega la descripción. Representa un registro de un catálogo del SAT o un registro con la misma estructura que uno de esos catálogos.

Propiedades

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 con la que FiscalAPI comunica el resultado de cada operación, tanto en las respuestas exitosas como en los errores. El modelo estándar es ApiResponse<T>. Una respuesta 400 de validación trae en data una lista de ValidationFailure, y una consulta paginada trae un PagedList<T>.

2.1 ApiResponse<T>

Modelo estándar de respuesta en FiscalAPI. Contiene la carga útil, el estado de la operación y metadatos adicionales. El tipo genérico T es el tipo de datos de la carga útil.

Propiedades

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

Describe una falla de validación detectada antes de procesar la solicitud. Las respuestas 400 (Bad Request) de validación traen una lista de estas fallas. Los errores de lectura de la solicitud llegan con la misma forma: un valor de otro tipo (por ejemplo, texto en un número), un JSON mal formado, un cuerpo vacío, un campo obligatorio ausente o null dentro de un complemento, o un parámetro de consulta inválido. En esas fallas, propertyName es la ruta del valor y errorMessage describe la causa.

En los errores de lectura, errorCode y formattedMessagePlaceholderValues son null, y un cuerpo que no se puede leer responde una sola falla:

Las consultas GET /api/v4/<recurso>/load, como la de los catálogos, revisan sus seis parámetros antes de consultar: sort, filter, group, select, totalSummary y groupSummary. Cada problema responde una falla, con propertyName igual al parámetro que lo trae (por ejemplo, sort), y todas llegan en la misma respuesta:

De un objeto, usa uno de sus campos simples; por ejemplo, country.id. Los nombres de campo no distinguen mayúsculas y minúsculas.

Propiedades

Ejemplo (crear una persona con una contraseña de 5 caracteres):

{
  "data": [
    {
      "propertyName": "Password",
      "errorMessage": "Password must be at least 6 characters long and contain at least one uppercase letter (A-Z), one lowercase letter (a-z), one digit (0-9) and one character that is not a letter or a digit. Letters with accents and ñ are not uppercase or lowercase letters for this rule.",
      "attemptedValue": null,
      "customState": null,
      "severity": 0,
      "errorCode": "PasswordTooShort",
      "formattedMessagePlaceholderValues": null
    }
  ],
  "succeeded": false,
  "message": "Sorry, it's not me, it's you.",
  "details": "One or more validation failures have occurred.",
  "httpStatusCode": 400,
  "traceIdentifier": "1071497CFECD493A975F14A639CF2B6B"
}

2.3 PagedList<T>

Respuesta paginada: contiene los elementos de la página actual y la información de paginación.

Propiedades

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"
}