Fiscalapi response models

This page describes the Fiscalapi response models. The base models define the common structure that every object inherits, such as a CFDI product (CFDI: Mexico's electronic invoice), an invoice, or a person (any individual or legal entity registered in your tenant). The other models wrap successful responses and errors.

1. Base models

The base models form an inheritance chain that reuses the common properties. AuditableDto provides the creation and last-update dates. BaseDto inherits it, adds the unique identifier, and is the base of most API responses. CatalogDto inherits BaseDto and adds description to represent SAT catalogs (SAT: Mexico's tax authority, Servicio de Administración Tributaria).

1.1 AuditableDto

Audit fields that track when a record was created and when it was last updated.

Properties

Example:

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

1.2 BaseDto

Inherits AuditableDto and adds the record's unique identifier. It's the base of most entities.

Properties

Example:

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

1.3 CatalogDto

Inherits BaseDto and adds the description. It represents a record from a SAT catalog, or a record with the same structure as one of those catalogs.

Properties

Example:

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

2. Response models

These models define the structure Fiscalapi uses to report the result of each operation, for successful responses and for errors alike. The standard model is ApiResponse<T>. A 400 validation response carries a list of ValidationFailure in data, and a paginated query returns a PagedList<T>.

2.1 ApiResponse<T>

The standard response model in Fiscalapi. It contains the payload, the operation status, and additional metadata. The generic type T is the data type of the payload.

Properties

Example:

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

Describes a validation failure detected before the request is processed. 400 (Bad Request) validation responses carry a list of these failures. Request parsing errors arrive in the same shape: a value of another type (for example, text in a number), malformed JSON, an empty body, a required field that is missing or null inside a complement (complemento, an XML extension the SAT defines for specific operations), or an invalid query parameter. In those failures, propertyName is the path of the value and errorMessage describes the cause.

In parsing errors, errorCode and formattedMessagePlaceholderValues are null, and a body that can't be read returns a single failure:

Queries to GET /api/v4/<resource>/load, such as the catalog query, check their six parameters before they run: sort, filter, group, select, totalSummary, and groupSummary. Each problem returns one failure, with propertyName set to the parameter that contains it (for example, sort), and all the failures arrive in the same response:

For an object, use one of its simple fields, for example country.id. Field names are case-insensitive.

Properties

Example (creating a person with a 5-character password):

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

A paginated response: it contains the items on the current page and the pagination details.

Properties

Example:

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