API de Facturación Electrónica

GET/companies

Obtiene la lista de empresas configuradas para facturación.

Respuesta:

[
  {
    "id": "abc-123-def",
    "name": "Mi Empresa SRL",
    "ruc": "80012345-6",
    "business_name": "MI EMPRESA SOCIEDAD DE RESPONSABILIDAD LIMITADA"
  }
]

POST/emit/invoice

Emite una factura electrónica y la envía a SIFEN.

Body (JSON):

{
  "company_id": "a7e9f084-d15c-4a8f-8b3d-0a7d5f24734a",
  "moneda": "PYG",
  "indicadorPresencia": 1,
  "cliente": {
    "ruc": "80009735-1",
    "razonSocial": "ANDE",
    "tipoContribuyente": 2,
    "tipoOperacion": 3,
    "direccion": "Av. España",
    "numeroCasa": "1234",
    "email": "facturacion@ande.gov.py"
  },
  "items": [
    {
      "codigo": "PROD-001",
      "descripcion": "Silla de Hierro",
      "cantidad": 2,
      "precioUnitario": 110000,
      "ivaTipo": 10,
      "unidadMedida": 77
    },
    {
      "codigo": "PROD-002",
      "descripcion": "Mesa de Madera",
      "cantidad": 1,
      "precioUnitario": 52500,
      "ivaTipo": 5,
      "unidadMedida": 77
    }
  ],
  "condicion": {
    "tipo": 1,
    "entregas": [
      {
        "tipo": 1,
        "monto": 272500,
        "moneda": "PYG"
      }
    ]
  }
}

Respuesta Exitosa:

{
  "ns2:rRetEnviDe": {
    "ns2:rProtDe": {
      "ns2:dEstRes": "Aprobado",
      "ns2:dProtAut": "12345678901234567890",
      "ns2:gResProc": {
        "ns2:dCodRes": "0260",
        "ns2:dMsgRes": "Aprobado"
      }
    }
  },
  "cdc": "01800123456001001000104720241201000000011234567890",
  "qr_url": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=...",
  "xml": "...",
  "kude_pdf_base64": null,
  "documento_id": "f3a2b1c0-1234-5678-abcd-ef0123456789"
}

POST/emit/credit-note

Emite una nota de crédito asociada a una factura.

Campos Adicionales Requeridos (además del body de factura):

{
  "company_id": "a7e9f084-d15c-4a8f-8b3d-0a7d5f24734a",
  "motivo": 1,
  "documentoAsociado": {
    "tipo": 1,
    "cdc": "01800097351001001000000120260115191611126841"
  },
  "cliente": { ... },
  "items": [ ... ],
  "moneda": "PYG"
}

Motivos de Nota de Crédito:

POST/emit/debit-note

Emite una nota de débito para ajustes adicionales.

Motivos de Nota de Débito:

POST/emit/remission

Emite una nota de remisión para traslado de mercadería.

Ejemplo:

{
  "company_id": "a7e9f084-d15c-4a8f-8b3d-0a7d5f24734a",
  "moneda": "PYG",
  "cliente": { ... },
  "items": [
    {
      "codigo": "PROD-001",
      "descripcion": "Silla de Oficina",
      "cantidad": 5,
      "unidadMedida": 77
    }
  ],
  "complementoRemision": {
    "motivo": 1,
    "responsableEmi": 1,
    "tipoAccion": 1,
    "fechaInicio": "2026-03-18",
    "fechaFin": "2026-03-18",
    "kilometros": 10,
    "precioFlete": 0
  }
}

POST/consult/ruc

Valida un RUC en el sistema SIFEN.

Body (JSON):

{
  "company_id": "a7e9f084-d15c-4a8f-8b3d-0a7d5f24734a",
  "ruc": "80009735-1"
}

Respuesta:

{
  "ns2:rResEnviConsRUC": {
    "ns2:xContRUC": {
      "ns2:dRUC": "80009735-1",
      "ns2:dRazSoc": "ADMINISTRACION NACIONAL DE ELECTRICIDAD",
      "ns2:dNomFan": "ANDE",
      "ns2:dEstRUC": "Activo"
    }
  }
}

POST/consult/document

Consulta el estado de un documento por su CDC.

Body (JSON):

{
  "company_id": "a7e9f084-d15c-4a8f-8b3d-0a7d5f24734a",
  "cdc": "01800097351001001000000120260115191611126841"
}

POST/emit/self-invoice

Emite una Autofactura Electrónica (iTiDE=4). Se usa cuando la empresa compra bienes o servicios a un proveedor que no es contribuyente (sin RUC). El campo cliente contiene los datos del vendedor/proveedor.

Body:

{
  "company_id": "...",
  "tipoTransaccion": 10,
  "cliente": {
    "razonSocial": "María González López",
    "documentoTipo": 1,
    "documentoNumero": "3456789",
    "tipoContribuyente": 1,
    "tipoOperacion": 2,
    "direccion": "Compañía San Miguel",
    "numeroCasa": "0"
  },
  "items": [...],
  "condicion": { "tipo": 1 },
  "moneda": "PYG"
}

POST/events/cancel

Cancela un documento electrónico emitido ante SIFEN. Registra el evento con XML firmado y respuesta SIFEN. Si el documento existe en la base de datos, su estado cambia a cancelado.

Body:

{
  "company_id": "...",
  "cdc": "01800123456001001000104720241201000000011234567890",
  "motivo": "Error en datos del cliente"
}

Respuesta:

{
  "rRetEnviEventoDe": { ... },
  "evento_id": "uuid-del-evento-registrado"
}

POST/events/inutilizacion

Inutiliza un rango de números de documentos ante SIFEN (Evento tipo 2, Manual 150). Usar cuando se emitieron documentos con error y no fueron enviados a SIFEN, o para invalidar una secuencia de numeración.

Body:

{
  "company_id": "...",
  "tipoDocumento": 1,
  "establecimiento": "001",
  "punto": "001",
  "nroDesde": 1,
  "nroHasta": 3,
  "motivo": "Documentos emitidos con error y no enviados a SIFEN",
  "serie": null,
  "timbradoNumero": null
}

Campos:

• tipoDocumento — 1=Factura, 4=Autofactura, 5=NC, 6=ND, 7=NRE
• nroDesde / nroHasta — rango de números a inutilizar
• serie — serie de 3 caracteres (opcional)
• timbradoNumero — usa el timbrado default si se omite

Respuesta:

{
  "rRetEnviEventoDe": { ... },
  "evento_id": "uuid-del-evento-registrado"
}

POST/kude

Genera el KuDE (Representación Gráfica del Documento Electrónico) en HTML a partir del XML firmado. El HTML puede renderizarse directamente en el navegador o convertirse a PDF. Incluye el logo de la empresa si está configurado en el admin.

Body:

{ "xml": "<?xml version=\"1.0\"...>" }

Respuesta:

HTML con el KuDE listo para imprimir (Content-Type: text/html).

POST/batch/create

Crea un lote con hasta 50 documentos. Devuelve batch_id y estado pending.

{
  "company_id": "...",
  "documents": [ { ...doc1... }, { ...doc2... } ]
}

POST/batch/{batch_id}/process

Genera y firma todos los XMLs del lote, luego los envía a SIFEN. Estado pasa a sent y se obtiene el sifen_batch_number.

GET/batch/{batch_id}/status

Consulta el estado del lote en SIFEN y actualiza el estado de cada documento (approved / rejected).

GET/batch/{batch_id}

Detalle completo del lote con todos sus documentos.

GET/batch/list

Lista lotes con filtros opcionales: ?company_id=&status=&limit=

POST/emit/invoice

{
  "company_id": "a7e9f084-d15c-4a8f-8b3d-0a7d5f24734a",
  "moneda": "PYG",
  "indicadorPresencia": 1,
  "tipoTransaccion": 1,

  "cliente": {
    "ruc": "11111111-1",
    "razonSocial": "Municipalidad de Asunción",
    "tipoContribuyente": 2,
    "tipoOperacion": 3,
    "direccion": "Chile esq. Palma",
    "numeroCasa": "S/N",
    "departamento": 11,
    "distrito": 143,
    "ciudad": 1532,
    "email": "compras@asuncion.gov.py"
  },

  "dncp": {
    "modalidad": "11",
    "entidad": "00123",
    "año": "24",
    "secuencia": "0000045",
    "fecha": "2024-03-15"
  },

  "items": [
    {
      "codigo": "SRV-001",
      "descripcion": "Servicio de limpieza",
      "cantidad": 10,
      "precioUnitario": 150000,
      "ivaTipo": 10,
      "unidadMedida": 77,
      "dncp": {
        "codigoNivelGeneral": "00000001",
        "codigoNivelEspecifico": "001"
      }
    },
    {
      "codigo": "MAT-005",
      "descripcion": "Materiales de construcción",
      "cantidad": 5,
      "precioUnitario": 200000,
      "ivaTipo": 5,
      "unidadMedida": 77,
      "dncp": {
        "codigoNivelGeneral": "00000002",
        "codigoNivelEspecifico": "003"
      }
    }
  ],

  "condicion": {
    "tipo": 1,
    "entregas": [
      { "tipo": 1, "monto": 2500000, "moneda": "PYG" }
    ]
  }
}

POST/emit/invoice

{
  "company_id": "a7e9f084-d15c-4a8f-8b3d-0a7d5f24734a",
  "moneda": "PYG",
  "indicadorPresencia": 1,

  "cliente": {
    "ruc": "11111111-1",
    "razonSocial": "Municipalidad de Asunción",
    "tipoContribuyente": 2,
    "tipoOperacion": 3,
    "direccion": "Chile esq. Palma",
    "numeroCasa": "S/N"
  },

  "items": [
    {
      "codigo": "SRV-001",
      "descripcion": "Servicio de consultoría",
      "cantidad": 1,
      "precioUnitario": 500000,
      "ivaTipo": 10,
      "unidadMedida": 77
    }
  ],

  "condicion": { "tipo": 1 }
}