Modelo de Respuestas de fiscalapi

Esta página documenta el modelo estandarizado de respuestas que proporciona la API de fiscalapi.

La API implementa un modelo de respuestas estandarizado para garantizar una experiencia de integración coherente y predecible. Este modelo facilita la comprensión y el manejo de las respuestas, mejorando la eficiencia y calidad de las integraciones.

El modelo de respuesta de fiscalapi se compone de dos objetos principales: apiResponse y validationFailure.

apiResponse es el modelo estándar que se utiliza en todas las respuestas de la API.
validationFailure es el modelo específico para errores de validación.

Cuando ocurren errores de validación (errores de nivel 1), la API devuelve un objeto apiResponse, donde la propiedad data es una lista de objetos validationFailure.

Este modelo es consistente en todas las respuestas y en todos los SDKs. Cada SDK, en su lenguaje correspondiente (JavaScript, Python, C#, PHP, Go, etc.), mantiene el mismo contrato y nombres, adaptándose únicamente a las convenciones de nomenclatura específicas del lenguaje.

Estructura de la respuesta

El modelo apiResponse es la estructura estándar utilizada en todas las respuestas de la API de fiscalapi. Este modelo simplifica la integración y depuración, proporcionando un marco uniforme para manejar respuestas y errores. A continuación, se describen las propiedades de este modelo.

Name
data
Type
any?
Description
La carga útil de la respuesta, que puede ser de cualquier tipo. Esta propiedad permite una gran flexibilidad en los datos devueltos, adaptándose a las necesidades de cada respuesta específica. En este ejemplo data contendrá un objeto invoice
Ejemplos:
- Si solicita una factura, la propiedad data contendrá un objeto invoice con toda la información de la factura.
- Si solicita una lista de facturas, la propiedad data contendrá un arreglo de objetos invoice.
Nota: Esta propiedad es opcional y puede estar ausente en respuestas que no incluyan datos. También puede contener tipos primitivos como string, number, boolean, entre otros.
Name
succeeded
Type
boolean?
Description
Un valor booleano que indica si la solicitud fue exitosa true o falló false.
Name
message
Type
string?
Description
Un mensaje que proporciona información adicional sobre la respuesta. Es útil para mostrar mensajes contextuales al usuario final.
Name
details
Type
string?
Description
Detalles adicionales sobre la respuesta, generalmente utilizados para proporcionar información más específica en casos de error.
Name
httpStatusCode
Type
number?
Description
El código de estado HTTP de la respuesta. Este campo es especialmente útil, ya que esta información normalmente no está disponible cuando se consume una API a través de un SDK. Sin embargo, hemos incluido este campo en el módelo de respuesta para que usted pueda reflejar los estados adecuados a sus usuarios finales.
Name
traceIdentifier
Type
string?
Description
Un identificador único para rastrear la solicitud. Es particularmente útil para la depuración en entornos complejos y para facilitar el soporte técnico.

apiResponse object

{
"data": {
    "versionCode": "4.0",
    "series": "F",
    "number": "FAP240304AU3-1",
    "date": "2022-11-11T14:35:18",
    "issuerTin": "FAP240304AU3",
    "issuerLegalName": "FISCAL API",
    "recipientTin": "KAHO641101B39",
    "recipientLegalName": "OSCAR KALA HAAK",
    "paymentFormCode": "04",
    "subtotal": 170.520000,
    "discount": 0.000000,
    "currencyCode": "MXN",
    "exchangeRate": 1.000000,
    "total": 197.800000,
    "omited ...": "...",
},
"succeeded": true,
"message": "",
"details": "",
"httpStatusCode": 200
}

Objeto `validationFailure`

El modelo validationFailure describe los errores de validación (errores nivel 1) específicos encontrados durante una solicitud.

Si ocurre al menos una falla de validación, la API aborta el procesamiento y devuelve un apiResponse con: data: Una lista de objetos validationFailure y código de estado http : 400 Bad Request

Name
propertyName
Type
string?
Description
El nombre de la propiedad que causó la falla de validación.
Name
errorMessage
Type
string?
Description
Mensaje de error que detalla la causa de la falla de validación.
Estos mensajes están diseñados para describir fallos específicos y pueden variar según la propiedad y el tipo de validador aplicado.
Están orientados principalmente a desarrolladores, por lo que suelen ser mensajes técnicos en inglés y no están traducidos al español. Actualmente, no se planea su localización.
⚠️ Tenga en cuenta que estos son mensajes de error de nivel 1. En este punto del ciclo de vida de la solicitud, aún no se han ejecutado las validaciones de nivel 2, que corresponden a las revisiones específicas para CFDI 4.0 estipuladas por el SAT.
Solo si se superan todas las validaciones de nivel 1, se procederá a las validaciones de nivel 2, las cuales comprenden las verificaciones específicas del CFDI 4.0 emitidas por el SAT. Según la legislación, los mensajes de nivel 2 deben presentarse en español, conforme a lo descrito en la página de Errores.
Name
attemptedValue
Type
any?
Description
El valor que se intentó asignar a la propiedad y que causó la falla.
Name
customState
Type
any?
Description
Estado personalizado asociado con la falla de validación. Este campo es opcional.
Name
severity
Type
string?
Description
El nivel de severidad de la falla. El valor predeterminado es Error.
Name
errorCode
Type
string?
Description
Código único que identifica la causa específica de la falla.

Response

{
"data": [
  {
    "propertyName": "Password",
    "errorMessage": "The length of 'Password' must be at least 6 characters. You entered 5 characters.",
    "attemptedValue": "12345",
    "customState": null,
    "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",
    "customState": null,
    "severity": 0,
    "errorCode": "PredicateValidator"
  }
],
"succeeded": false,
"message": "Sorry, it's not me, it's you.",
"details": "One or more validation failures have occurred.",
"httpStatusCode": 400,
"traceIdentifier": "1071497CFECD493A975F14A639CF2B6B"
}

Beneficios de la Estandarización

El modelo apiResponse ofrece múltiples beneficios que optimizan la experiencia de desarrollo:

Consistencia: Todas las respuestas de la API siguen una estructura uniforme, lo que simplifica la comprensión y manejo de las respuestas.
Manejo de errores: Las propiedades succeeded, message y details proporcionan una forma coherente de verificar el éxito de las solicitudes y gestionar mensajes de error de manera eficiente.
Depuración eficaz: La propiedad traceIdentifier es una herramienta valiosa para rastrear y diagnosticar problemas, facilitando una resolución rápida en casos de soporte técnico.
Extensibilidad: La flexibilidad de la propiedad data permite que el modelo apiResponse se adapte a diversas necesidades, lo que mejora su aplicabilidad a diferentes funcionalidades de la API.

Al adoptar este modelo de respuesta estandarizado, fiscalapi garantiza una experiencia de API confiable y predecible para los desarrolladores. Esta consistencia no solo facilita la integración, sino que también mejora el mantenimiento y escalabilidad del código en proyectos de desarrollo.