Emitir comprobante

POST /api/v1/facturas

Emite un comprobante electrónico (FE, TE, NC o ND) y lo encola para envío a Hacienda. La respuesta es inmediata con estado procesando; el estado final llega después vía webhook o mediante polling a GET /facturas/{clave}.

Autenticación y permisos

Atributo	Valor
Esquema	API key (`X-Api-Key`)
Scope requerido	`facturas:write`
Idempotente	Sí (con header `Idempotency-Key`)
Rate limit	120 req/min por API key

Headers


POST /api/v1/facturas HTTP/1.1
Host: api.lxsyscr.com
X-Api-Key: lxs_live_a1b2c3d4_001122...
Content-Type: application/json
Idempotency-Key: 4f1c8a8a-2c4f-4b5e-9c2a-1234567890ab
Accept: application/json

Request body

Ver FacturaApiRequestDto para el schema completo.

Ejemplo mínimo (FE):


{
  "tipo": "FacturaElectronica",
  "cliente": { "idCliente": 42 },
  "condicionVenta": "01",
  "medioPago": "01",
  "moneda": "CRC",
  "lineas": [
    { "idProducto": 100, "cantidad": 2 }
  ]
}

Ejemplo completo (FE con descuento, exoneración, USD):


{
  "tipo": "FacturaElectronica",
  "cliente": { "idCliente": 42 },
  "condicionVenta": "02",
  "plazoCredito": 30,
  "medioPago": "04",
  "moneda": "USD",
  "tipoCambio": 670.50,
  "codigoActividad": "722002",
  "comentario": "Pedido #1234 — Cliente VIP",
  "lineas": [
    {
      "idProducto": 100,
      "cantidad": 3,
      "precioUnitario": 50.00,
      "montoDescuento": 5.00,
      "naturalezaDescuento": "Volumen >= 3 unidades"
    },
    {
      "idProducto": 101,
      "cantidad": 1,
      "montoExoneracion": 12.50
    }
  ],
  "referencias": []
}

Respuestas

`201 Created`


HTTP/1.1 201 Created
Location: /api/v1/facturas/50615012600310112345600100001010000000123456789012
Content-Type: application/json


{
  "clave": "50615012600310112345600100001010000000123456789012",
  "numeroConsecutivo": "00100001010000000123",
  "tipoDocumento": "01",
  "estadoHacienda": "procesando",
  "totalComprobante": 169.50,
  "moneda": "USD",
  "fechaEmision": "2026-05-15T15:32:11Z"
}

`400 Bad Request`

Validación falló. Ejemplos:


{ "error": "Debe incluir al menos una línea." }


{ "error": "Producto 999 no encontrado." }


{ "error": "Cliente 42 no encontrado." }


{ "error": "Factura electrónica requiere cliente." }

`401 Unauthorized`

API key faltante, malformada o revocada.


{ "error": "API key inválida o revocada." }

`403 Forbidden`

API key válida pero sin el scope facturas:write.


{ "error": "Scope insuficiente. Requerido: facturas:write" }

`409 Conflict`

Idempotency-Key reutilizada con un body distinto. Ver Idempotencia.


{ "error": "Idempotency-Key reutilizada con body distinto." }

`413 Payload Too Large`

Body excede 256 KB.

`429 Too Many Requests`


HTTP/1.1 429 Too Many Requests
Retry-After: 38


{ "error": "Rate limit excedido. Reintenta en 38 segundos." }

`500 Internal Server Error`


{ "error": "Error interno emitiendo el comprobante." }

`501 Not Implemented`

Tipo de comprobante aún no soportado (caso histórico, ya no aplica).


{ "error": "Funcionalidad no disponible en esta versión." }

Notas operativas

La emisión es asíncrona respecto al envío a Hacienda. Un 201 significa “encolado para envío”, no “aceptado por Hacienda”.
El PDF y el XML quedan disponibles tras la emisión local, sin esperar la respuesta de Hacienda.
Si no configuraste webhook, debés hacer polling a GET /facturas/{clave} para conocer el estado final.