Facturas

Maneja las operaciones relacionadas con facturas en la API.

Endpoints

Obtener todas las facturas

GET /invoices

Obtiene el listado de todas las facturas.

Respuesta

La API devolverá un array con todas las facturas registradas o un mensaje de error en caso de fallar.

Respuesta exitosa:

[
  {
    "id": "uuid-factura-1",
    "customerId": "uuid-cliente",
    "issueDate": "2025-06-02",
    "taxpayerId": "uuid-empresa",
    "establishmentId": "uuid-establecimiento",
    "emissionPointId": "uuid-punto-emision",
    "documentTypeId": "uuid-tipo-documento"
    // ... otros campos de la factura
  },
  {
    "id": "uuid-factura-2"
    // ... datos de otra factura
  }
]

Posibles errores

Código	Descripción
500	Error interno al obtener la lista de facturas

{
  "statusCode": 500,
  "message": "Error fetching invoices: [detalles del error]"
}

Crear una nueva factura

POST /invoice

Crea una nueva factura procesando todos los pasos necesarios.

Encabezados requeridos

Key	Value (Ejemplo de Clave API para autenticación)
x-api-key	`$2a$12$IQf1vb/MNB7o3UKLMCECZeX.SzHl4C3kZmqkzF9c/JZkqp/mVlbBS`

Cuerpo de la solicitud (JSON):

{
  "customerId": "uuid-cliente",
  "issueDate": "2025-06-02",
  "taxpayerId": "uuid-empresa",
  "establishmentId": "uuid-establecimiento",
  "emissionPointId": "uuid-punto-emision",
  "tenantId": "uuid-tenant",
  "paymentMethods": [
    {
      "paymentMethodId": "uuid-metodo-pago",
      "deadline": 30,
      "timeUnit": "DAY",
      "value": "100.00"
    }
  ],
  "details": [
    {
      "productId": "uuid-producto",
      "quantity": 2,
      "price": "50.00",
      "discount": "0.00"
    }
  ]
}

Campos del objeto para crear una factura

Campo	Tipo	Requerido	Descripción
customerId	String (UUID)	Sí	ID del cliente
issueDate	String	Sí	Fecha de emisión de la factura
taxpayerId	String (UUID)	Sí	ID de la empresa
establishmentId	String (UUID)	Sí	ID del establecimiento
emissionPointId	String (UUID)	Sí	ID del punto de emisión
tenantId	String (UUID)	No	ID del tenant
paymentMethods	Array	Sí	Métodos de pago para la factura
details	Array	Sí	Detalles de los productos de la factura
paymentMethodId	String (UUID)	Sí	ID del método de pago
deadline	Integer	No	Plazo de pago
timeUnit	Enum (TimeUnit)	No	Unidad de tiempo para el plazo (DAY, MONTH, YEAR)
value	String (Decimal)	Sí	Valor del pago

Respuesta

La API devolverá la información de la factura creada exitosamente o un mensaje de error en caso de fallar.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "uuid-cliente",
  "issueDate": "2025-06-02",
  "taxpayerId": "uuid-empresa",
  "establishmentId": "uuid-establecimiento",
  "emissionPointId": "uuid-punto-emision",
  "documentTypeId": "uuid-tipo-documento",
  "tenantId": "uuid-tenant",
  "paymentMethods": [
    {
      "id": "663e8344-a29e-41b5-b716-446655440123",
      "paymentMethodId": "uuid-metodo-pago",
      "deadline": 30,
      "timeUnit": "DAY",
      "value": "100.00"
    }
  ],
  "details": [
    {
      "id": "772e9500-e29b-41d4-a716-446655440321",
      "productId": "uuid-producto",
      "quantity": 2,
      "price": "50.00",
      "discount": "0.00"
    }
  ],
  "createdAt": "2025-06-02T12:00:00Z",
  "updatedAt": "2025-06-02T12:00:00Z"
}

Posibles errores

Código	Descripción
400	Error en la creación de la factura con detalles del problema

{
  "statusCode": 400,
  "message": "Error creating invoice: [detalles del error]"
}

Obtener una factura por ID

GET /invoices/{id}

Obtiene la información detallada de una factura específica a partir de su ID.

Encabezados requeridos

Encabezado	Tipo	Descripción	Ejemplo
x-api-key	String	Clave API para autenticación (formato similar a bcrypt)	`$2a$12$IQf1vb/MNB7o3UKLMCECZeX.SzHl4C3kZmqkzF9c/JZkqp/mVlbBS`

Parámetros de ruta

Parámetro	Tipo	Descripción
id	String (UUID)	ID de la factura a consultar

Respuesta

La API devolverá los detalles completos de la factura solicitada o un mensaje de error en caso de fallar.

Respuesta exitosa:

{
  "id": "uuid-factura",
  "customerId": "uuid-cliente",
  "issueDate": "2025-06-02",
  "taxpayerId": "uuid-empresa",
  "establishmentId": "uuid-establecimiento",
  "emissionPointId": "uuid-punto-emision",
  "documentTypeId": "uuid-tipo-documento",
  "tenantId": "uuid-tenant",
  "paymentMethods": [
    {
      "id": "uuid-pago",
      "paymentMethodId": "uuid-metodo-pago",
      "deadline": 30,
      "timeUnit": "DAY",
      "value": "100.00"
    }
  ],
  "details": [
    {
      "id": "uuid-detalle",
      "productId": "uuid-producto",
      "quantity": 2,
      "price": "50.00",
      "discount": "0.00"
    }
  ],
  "createdAt": "2025-06-02T12:00:00Z",
  "updatedAt": "2025-06-02T12:00:00Z"
}

Posibles errores

Código	Descripción
500	Error interno al obtener la factura
404	La factura con el ID proporcionado no ha sido encontrada

{
  "statusCode": 500,
  "message": "Error fetching invoice: [detalles del error]"
}

{
  "statusCode": 404,
  "message": "Invoice not found"
}