Sincronizar estado de factura con SIAT

POST/api/v1/facturas/:facturaId/sincronizar-estado

Consulta a SIAT por el CUF guardado y actualiza el estado fiscal local de la factura indicada. Requiere X-API-Key con permiso facturas.consultar. facturaId es el UUID interno; no es el CUF ni el número de factura. No necesita cuerpo. El backend recupera los identificadores y códigos operativos; no pide CUIS, CUFD, NIT emisor ni código de recepción.

Header requerido X-API-KeyVer operaciones de Facturas

Contrato de la operación

Consulta a SIAT por el CUF guardado y actualiza el estado fiscal local de la factura indicada. Requiere X-API-Key con permiso facturas.consultar. facturaId es el UUID interno; no es el CUF ni el número de factura. No necesita cuerpo. El backend recupera los identificadores y códigos operativos; no pide CUIS, CUFD, NIT emisor ni código de recepción.

Este endpoint no vuelve a emitir la factura ni reenvía su XML. La consulta GET /facturas/{facturaId} devuelve lo persistido; este POST llama al proveedor y guarda el resultado. Para emisiones masivas usa /facturas/masivas/{emisionMasivaId}/verificar, que programa la validación del paquete mediante su código de recepción y devuelve 202.

La respuesta es 200 con el mensaje estado de factura sincronizado y el contrato de factura. El servicio traduce 908 a aceptado, 905 a anulado, 902 a rechazado y 904 a observado; otros códigos conservan el estado local anterior. Son las traducciones actuales de Falmus, no una lista exhaustiva de estados SIAT. Puede devolver 401, 403, 404, 422 o 503 en caso de fallo.

La implementación actual busca la factura por empresa, pero no comprueba el ambiente persistido frente al ambiente de la clave antes de operar. Esta revisión identifica ese punto como corrección prioritaria en [revision-endpoints-siat.md](../revision-endpoints-siat.md).

Fuente del servicio oficial: [Verificación de estado de factura electrónica](https://siatinfo.impuestos.gob.bo/index.php/facturacion-en-linea/implementacion-servicios-facturacion/...

Ejemplo

Solicitud de ejemplo

Clave ficticia; no se ejecuta desde esta página

cURL · POST

export FALMUS_API_URL='https://staging-api.falmus.com/api/v1'
export FALMUS_API_KEY='flm_test_REEMPLAZA_CON_TU_CLAVE'
export FACTURA_ID='REEMPLAZA_CON_FACTURA_ID'

curl --request POST \
  --url "$FALMUS_API_URL/facturas/${FACTURA_ID}/sincronizar-estado" \
  --header "X-API-Key: $FALMUS_API_KEY"

Este ejemplo no incluye un cuerpo. Revisa el contrato para conocer los parámetros de ruta y consulta.

Respuesta

Ejemplo de respuesta

200 OKapplication/json

JSON

{
  "message": "estado de factura sincronizado",
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "numeroFactura": 42,
    "cuf": "A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0",
    "codigoRecepcion": "00000000-0000-4000-8000-000000000042",
    "codigoEstado": 908,
    "estado": "aceptado",
    "ambiente": "pruebas",
    "fechaEmision": "2026-08-30T16:10:00-04:00",
    "montoTotal": 500,
    "codigoPuntoVenta": 0,
    "codigoDocumentoSector": 1,
    "nombreDocumentoSector": "Compra y venta",
    "urlQr": "https://pilotosiat.impuestos.gob.bo/consulta/QR?nit=123456789&cuf=A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0&numero=42&t=2",
    "urlXml": "https://api.example.test/api/v1/public/facturas/A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0/xml",
    "urlPdf": "https://api.example.test/api/v1/public/facturas/A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0/pdf"
  }
}

Datos ficticios; los identificadores y valores cambian en cada respuesta.

Volver a Facturas