Estructura de Respuestas

Las respuestas de nuestra API siguen un formato estructurado que permite identificar rápidamente el estado de las operacion o registros, acceder a los datos relevantes de facturación y manejar errores de forma consistente.

Respuesta existosa de la modalidad Veri*Factu asíncrona

Este formato de respuesta lo podemos encontrar en los endpoints de emisión asíncrona en modalidad Veri*Factu. En este modo de envío no asociamos directamente el registro a una operación operationId por lo que solo se verá información de registro. Después de su envío se podrá consultar a el operationId al que fue asociado y su estado legal ante el sistema de la AEAT.

{
  "message": "Successfully created invoice record",
  "data": {
    "id": "01JGCMYBNEXEQ4Z5FE7HPZKAGV",
    "invoice": {
      "serialNumber": "F001-0001",
      "typeCode": "F1",
      "issuedAt": "2024-07-01T15:30:45.123Z",
      "operationDate": "2024-03-20T15:30:45.123Z"
    },
    "files": {
      "request": "https://api.example.com/files/requests/01JGCMYBNEXEQ4Z5FE7HPZKAGV"
    }
  }
}

Campos Clave

Campo	Descripción
`data.id`	ID del registro de facturación Veri*Factu.
`data.invoice.serialNumber`	Número de serie de la factura.
`data.invoice.typeCode`	Tipo de factura según diccionarios.
`data.invoice.issuedAt`	Fecha de emisión de la factura en UTC (cuando fue generado en el sistema).
`data.invoice.operationDate`	Fecha de operación de la factura en UTC (cuando fue realizada la venta).
`data.files.request`	URL para descargar el XML con la estructura del registro de facturación.

Respuesta en la facturación en modalidad Veri*Factu síncrona

Este formato de respuesta se obtiene al facturar síncronamente en modalidad Veri*Factu, enviando una operación completa (lote de registros) directamente. A diferencia del envío individual acá recibirás el operationId, el estado del procesamiento global y la respuesta consolidada de la AEAT.

{
  "message": "Ordinary invoice creation processed",
  "data": {
    "id": "01JS5NXXFC8YAQEZ0WJWMCYAJZ",
    "trackingStatus": "FINISHED",
    "issuedAt": "2025-04-19T00:07:16.714Z",
    "records": [
      {
        "id": "01JS5NXXFB3FRKQYF888X2H9FH",
        "type": "CREATION_ORDINARY_INVOICE",
        "invoice": {
          "serialNumber": "F001-0001",
          "typeCode": "F1",
          "issuedAt": "2024-07-01T15:30:45.123Z",
          "operationDate": "2024-03-20T15:30:45.123Z"
        },
        "veriFactuResponse": {
          "recordStatus": "Correcto",
          "error": null
        }
      }
    ],
    "company": {
		  "id": "01JGCMVZSYW0ADWSJ1NDXB6E36",
		  "nif": "A12345674",
		  "name": "Umbrella Corp."
	  },
    "files": {
      "request": "http://api.example/users/9bbe6c08-e68d-4522-9e58-e9e7de857b54/companies/01JGCMVZSYW0ADWSJ1NDXB6E36/operations/01JS5NXXFC8YAQEZ0WJWMCYAJZ/request.xml"
    }
	},
  "veriFactuResponse": {
    "verificationSecureCode": "A-NABH97559RU3J4",
     "globalStatus": "Correcto"
  }
}

Campos Clave

Campo	Descripción
`data.id`	ID de la operación de facturación.
`data.trackingStatus`	Estado del procesamiento de la operación.
`data.records`	Listado de registros de facturación procesados.
`data.records[index].invoice.serialNumber`	Número de serie de la factura.
`data.records[index].invoice.typeCode`	Tipo de factura según diccionarios.
`data.records[index].invoice.issuedAt`	Fecha de emisión de la factura en UTC (cuando fue generado en el sistema).
`data.records[index].invoice.operationDate`	Fecha de operación de la factura en UTC (cuando fue realizada la venta).
`data.verifactuResponse`	Respuesta de la operación global de la AEAT.

Respuesta existosa de la modalidad No Veri*Factu

Este formato de respuesta lo podemos encontrar en los endpoints de emisión en modalidad No VeriFactu. En esta respuesta notaremos que no tiene asociada una operación, ya que estas se harán tantas veces como requerimientos de la AEAT hayan, esta metada estará referencia en el campo sendings.

{
  "message": "Successfully saved ordinary invoice record",
  "data": {
    "id": "01JZ4R3P2Z26WH0WGXX0RKTT4K",
    "type": "CREATION_ORDINARY_INVOICE",
    "invoice": {
      "serialNumber": "F001-0001",
      "typeCode": "F1",
      "issuedAt": "2024-07-01T15:30:45.123Z",
      "operationDate": "2024-03-20T15:30:45.123Z"
    },
    "files": {
      "record": "http://api.example.com/01JRX47DCGRKSC9K84S9HX8V7M.xml"
    },
    "sendings": []
  }
}

Campos Clave

Campo	Descripción
`data.id`	ID del registro de facturación No Veri*Factu.
`data.invoice.serialNumber`	Número de serie de la factura.
`data.invoice.typeCode`	Tipo de factura según diccionarios.
`data.invoice.issuedAt`	Fecha de emisión de la factura en UTC (cuando fue generado en el sistema).
`data.invoice.operationDate`	Fecha de operación de la factura en UTC (cuando fue realizada la venta).
`data.sendings`	El listado envíos a la AEAT que se realizaron desde que fue emitido.
`data.files.record`	URL para descargar el XML con la estructura del registro de facturación.

Estructura de Errores

Para los errores tenemos una estructura estandarizada que incluye códigos únicos, mensajes claros y referencias técnicas, permitiendo identificar la causa de la incidencia. Estos errores, ya sean de validación, respuestas de la AEAT o del sistema, mantienen un formato consistente.

{
  "message": "Validation error",
  "errors": [
    {
      "code": "AEP_BRQ_0001",
      "message": "Max length is 10",
      "reference": "MAX_LENGTH_IS_10",
      "extension": {
        "field": "/field",
        "type": "maxLength"
      }
    }
  ]
}

Nota
En la documentación de cada endpoint se puede encontrar con un ejemplo de su respuesta.