API de Facturación Electrónica

Documentación completa para la integración con SIFEN Paraguay

Inicio Rápido: Formato Plano

La forma más simple de integrar es enviar un raw JSON con claves en mayúsculas al endpoint index.php. Sin estructura compleja, sin conocer todos los códigos internos de SIFEN.

✅
Este es el camino recomendado para integradores nuevos: enviar todo en application/json y dejar que el servidor convierta automáticamente al formato experto.

Body JSON listo para enviar

JSON plano (ejemplo real)
[
  {
    "API_KEY": "TU_API_KEY_AQUI",
    "TENANT_ID": "tu_empresa",
    "ESTABLECIMIENTO": 1,
    "PUNTO": 1,
    "RUC": "2830501-9",
    "RAZON_SOCIAL": "MARCIAL ESTECHE",
    "CODIGO": "1",
    "DIRECCION": "ITAPUA, ENCARNACION, IRRAZABAL 144",
    "CORREO": "[email protected]",
    "TELEFONO": "0981123456",
    "CONDICION": "CONTADO",
    "PLAZO": "",
    "PERSONA": "FISICA",
    "CONTRIBUYENTE": "SI",
    "ENTIDAD_DE_GOBIERNO": "NO",
    "FORMATO": "TICKET",
    "MONEDA": "USD",
    "CAMBIO": 6500,
    "ITEMS": [
      { "CODIGO": "1", "DESCRIPCION": "SERVICIO TECNICO", "CANTIDAD": 1, "PRECIO": 25000, "IVA": 10 }
    ]
  }
]

Ejemplos de envío por lenguaje

VB6 (WinHTTP)
' Requiere: Proyecto → Referencias → Microsoft WinHTTP Services, version 5.1

Public Function EnviarFactura() As String
    Dim http As WinHttp.WinHttpRequest
    Dim json As String

    ' Construir JSON — comillas dobles se escriben dobles dentro del string
    json = "[{" & _
           """API_KEY"":""TU_API_KEY_AQUI""," & _
           """TENANT_ID"":""tu_empresa""," & _
           """ESTABLECIMIENTO"":1," & _
           """PUNTO"":1," & _
           """RUC"":""2830501-9""," & _
           """RAZON_SOCIAL"":""MARCIAL ESTECHE""," & _
           """CODIGO"":""1""," & _
           """CORREO"":""[email protected]""," & _
           """TELEFONO"":""0981123456""," & _
           """CONDICION"":""CONTADO""," & _
           """PERSONA"":""FISICA""," & _
           """CONTRIBUYENTE"":""SI""," & _
           """ENTIDAD_DE_GOBIERNO"":""NO""," & _
           """FORMATO"":""TICKET""," & _
           """MONEDA"":""USD""," & _
           """CAMBIO"":6500," & _
           """ITEMS"":[" & _
             "{""CODIGO"":""1"",""DESCRIPCION"":""SERVICIO TECNICO""," & _
             """CANTIDAD"":1,""PRECIO"":25000,""IVA"":10}" & _
           "]}]"

    Set http = New WinHttp.WinHttpRequest
    http.Open "POST", "https://oietema.com/fact_elect/index.php", False
    http.SetRequestHeader "Content-Type", "application/json; charset=utf-8"
    http.Send json

    EnviarFactura = http.ResponseText
End Function

Private Sub Command1_Click()
    MsgBox EnviarFactura()
End Sub

' ── Si tenés ñ o tildes, usar esta función auxiliar y enviar así:
' http.Send ToUtf8Bytes(json)
Public Function ToUtf8Bytes(ByVal s As String) As Byte()
    Dim ado As Object
    Set ado = CreateObject("ADODB.Stream")
    ado.Type = 2 : ado.Charset = "utf-8" : ado.Open
    ado.WriteText s
    ado.Position = 0 : ado.Type = 1 : ado.Position = 3
    ToUtf8Bytes = ado.Read
    ado.Close
End Function
cURL
curl -X POST "https://oietema.com/fact_elect/index.php" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "API_KEY": "TU_API_KEY_AQUI",
      "TENANT_ID": "tu_empresa",
      "ESTABLECIMIENTO": 1,
      "PUNTO": 1,
      "RUC": "2830501-9",
      "RAZON_SOCIAL": "MARCIAL ESTECHE",
      "CODIGO": "1",
      "DIRECCION": "ITAPUA, ENCARNACION, IRRAZABAL 144",
      "CORREO": "[email protected]",
      "TELEFONO": "0981123456",
      "CONDICION": "CONTADO",
      "PLAZO": "",
      "PERSONA": "FISICA",
      "CONTRIBUYENTE": "SI",
      "ENTIDAD_DE_GOBIERNO": "NO",
      "FORMATO": "TICKET",
      "MONEDA": "USD",
      "CAMBIO": 6500,
      "ITEMS": [
        { "CODIGO": "1", "DESCRIPCION": "SERVICIO TECNICO", "CANTIDAD": 1, "PRECIO": 25000, "IVA": 10 }
      ]
    }
  ]'
JavaScript (fetch)
const payload = [
  {
    API_KEY: "TU_API_KEY_AQUI",
    TENANT_ID: "cnid",
    ESTABLECIMIENTO: 1,
    PUNTO: 1,
    RUC: "2830501-9",
    RAZON_SOCIAL: "MARCIAL ESTECHE",
    CODIGO: "1",
    DIRECCION: "ITAPUA, ENCARNACION, IRRAZABAL 144",
    CORREO: "[email protected]",
    TELEFONO: "0981123456",
        CONDICION: "CONTADO",
        PLAZO: "",
        PERSONA: "FISICA",
        CONTRIBUYENTE: "SI",
        ENTIDAD_DE_GOBIERNO: "NO",
        FORMATO: "TICKET",
        MONEDA: "USD",
        CAMBIO: 6500,
    ITEMS: [
      { CODIGO: "1", DESCRIPCION: "SERVICIO TECNICO", CANTIDAD: 1, PRECIO: 25000, IVA: 10 }
    ]
  }
];

const resp = await fetch("https://oietema.com/fact_elect/index.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload)
});

const texto = await resp.text();
console.log(texto);
Python (requests)
import requests

url = "https://oietema.com/fact_elect/index.php"
payload = [
    {
        "API_KEY": "TU_API_KEY_AQUI",
        "TENANT_ID": "tu_empresa",
        "ESTABLECIMIENTO": 1,
        "PUNTO": 1,
        "RUC": "2830501-9",
        "RAZON_SOCIAL": "MARCIAL ESTECHE",
        "CODIGO": "1",
        "DIRECCION": "ITAPUA, ENCARNACION, IRRAZABAL 144",
        "CORREO": "[email protected]",
        "TELEFONO": "0981123456",
        "CONDICION": "CONTADO",
        "PLAZO": "",
        "PERSONA": "FISICA",
        "CONTRIBUYENTE": "SI",
        "ENTIDAD_DE_GOBIERNO": "NO",
        "FORMATO": "TICKET",
        "MONEDA": "USD",
        "CAMBIO": 6500,
        "ITEMS": [
            {"CODIGO": "1", "DESCRIPCION": "SERVICIO TECNICO", "CANTIDAD": 1, "PRECIO": 25000, "IVA": 10}
        ]
    }
]

r = requests.post(url, json=payload, timeout=30)
print(r.text)
Visual FoxPro 9
* Requiere: COM → WinHttp.WinHttpRequest

LOCAL oHttp, cUrl, cJson, cResp

cUrl  = "https://oietema.com/fact_elect/index.php"
cJson = '[{' + CHR(13)+CHR(10) + ;
        '  "API_KEY":"TU_API_KEY_AQUI",' + ;
        '  "TENANT_ID":"tu_empresa",' + ;
        '  "ESTABLECIMIENTO":1,' + ;
        '  "PUNTO":1,' + ;
        '  "RUC":"2830501-9",' + ;
        '  "RAZON_SOCIAL":"MARCIAL ESTECHE",' + ;
        '  "CODIGO":"1",' + ;
        '  "CORREO":"[email protected]",' + ;
        '  "TELEFONO":"0981123456",' + ;
        '  "CONDICION":"CONTADO",' + ;
        '  "PERSONA":"FISICA",' + ;
        '  "CONTRIBUYENTE":"SI",' + ;
        '  "ENTIDAD_DE_GOBIERNO":"NO",' + ;
        '  "ITEMS":[' + ;
        '    {"CODIGO":"1","DESCRIPCION":"SERVICIO TECNICO",' + ;
        '     "CANTIDAD":1,"PRECIO":25000,"IVA":10}' + ;
        '  ]' + ;
        '}]'

oHttp = CREATEOBJECT("WinHttp.WinHttpRequest.5.1")
oHttp.Open("POST", cUrl, .F.)
oHttp.SetRequestHeader("Content-Type", "application/json; charset=utf-8")
oHttp.Send(cJson)

cResp = oHttp.ResponseText
MESSAGEBOX(cResp, 0, "Respuesta SIFEN")
Delphi (WinInet / Indy)
uses
  IdHTTP, IdSSLOpenSSL, SysUtils;

function EnviarFactura: string;
var
  Http: TIdHTTP;
  SSL: TIdSSLIOHandlerSocketOpenSSL;
  Body: TStringStream;
  Json: string;
begin
  Json :=
    '[{' +
    '"API_KEY":"TU_API_KEY_AQUI",' +
    '"TENANT_ID":"tu_empresa",' +
    '"ESTABLECIMIENTO":1,' +
    '"PUNTO":1,' +
    '"RUC":"2830501-9",' +
    '"RAZON_SOCIAL":"MARCIAL ESTECHE",' +
    '"CODIGO":"1",' +
    '"CORREO":"[email protected]",' +
    '"TELEFONO":"0981123456",' +
    '"CONDICION":"CONTADO",' +
    '"PERSONA":"FISICA",' +
    '"CONTRIBUYENTE":"SI",' +
    '"ENTIDAD_DE_GOBIERNO":"NO",' +
    '"ITEMS":[' +
    '  {"CODIGO":"1","DESCRIPCION":"SERVICIO TECNICO",' +
    '   "CANTIDAD":1,"PRECIO":25000,"IVA":10}' +
    ']}]';

  SSL  := TIdSSLIOHandlerSocketOpenSSL.Create(nil);
  Http := TIdHTTP.Create(nil);
  try
    Http.IOHandler := SSL;
    Http.Request.ContentType := 'application/json; charset=utf-8';
    Body := TStringStream.Create(Json, TEncoding.UTF8);
    try
      Result := Http.Post('https://oietema.com/fact_elect/index.php', Body);
    finally
      Body.Free;
    end;
  finally
    Http.Free;
    SSL.Free;
  end;
end;

// Llamada:
// ShowMessage(EnviarFactura);
ℹ️
Requiere Indy (viene con Delphi) y las DLLs de OpenSSL (libssl-3.dll / libeay32.dll) en la carpeta del ejecutable para HTTPS.
PHP (cURL)
<?php
$url = "https://oietema.com/fact_elect/index.php";
$payload = [
    [
        "API_KEY" => "TU_API_KEY_AQUI",
        "TENANT_ID" => "cnid",
        "ESTABLECIMIENTO" => 1,
        "PUNTO" => 1,
        "RUC" => "2830501-9",
        "RAZON_SOCIAL" => "MARCIAL ESTECHE",
        "CODIGO" => "1",
        "DIRECCION" => "ITAPUA, ENCARNACION, IRRAZABAL 144",
        "CORREO" => "[email protected]",
        "TELEFONO" => "0981123456",
        "CONDICION" => "CONTADO",
        "PLAZO" => "",
        "PERSONA" => "FISICA",
        "CONTRIBUYENTE" => "SI",
        "ENTIDAD_DE_GOBIERNO" => "NO",
        "ITEMS" => [
            ["CODIGO" => "1", "DESCRIPCION" => "SERVICIO TECNICO", "CANTIDAD" => 1, "PRECIO" => 25000, "IVA" => 10]
        ]
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$respuesta = curl_exec($ch);
curl_close($ch);

echo $respuesta;
C# (.NET HttpClient)
using System.Net.Http;
using System.Text;

var url = "https://oietema.com/fact_elect/index.php";
var json = """
[
  {
    "API_KEY": "TU_API_KEY_AQUI",
    "TENANT_ID": "tu_empresa",
    "ESTABLECIMIENTO": 1,
    "PUNTO": 1,
    "RUC": "2830501-9",
    "RAZON_SOCIAL": "MARCIAL ESTECHE",
    "CODIGO": "1",
    "DIRECCION": "ITAPUA, ENCARNACION, IRRAZABAL 144",
    "CORREO": "[email protected]",
    "TELEFONO": "0981123456",
    "CONDICION": "CONTADO",
    "PLAZO": "",
    "PERSONA": "FISICA",
    "CONTRIBUYENTE": "SI",
    "ENTIDAD_DE_GOBIERNO": "NO",
    "ITEMS": [
      { "CODIGO": "1", "DESCRIPCION": "SERVICIO TECNICO", "CANTIDAD": 1, "PRECIO": 25000, "IVA": 10 }
    ]
  }
]
""";

using var http = new HttpClient();
using var content = new StringContent(json, Encoding.UTF8, "application/json");
var resp = await http.PostAsync(url, content);
var texto = await resp.Content.ReadAsStringAsync();
Console.WriteLine(texto);

Formato Plano (Simplificado)

El formato plano es una alternativa al JSON experto diseñada para integradores simples (VB6, sistemas legados, etc.) que no necesitan conocer los códigos internos de SIFEN. Solo hay un tipo de entrada: JSON con claves en mayúsculas.

✅
Con el formato plano se puede enviar todo dentro de data incluyendo credenciales, sin necesidad de parámetros POST adicionales (apiKey, tenantId, tenantPunto, cliente, email).
ℹ️
El sistema detecta automáticamente si la entrada es formato plano o formato experto. Ambos formatos coexisten. Los integradores existentes no necesitan cambiar nada.

Envío desde Postman / cURL / VB6

Enviar el body como raw JSON (Content-Type: application/json). No se necesitan campos de formulario adicionales.

Campos disponibles

CampoTipoObligatorioValores aceptadosNotas
API_KEYstring✅Tu clave de APIPuede venir en el JSON o en el POST field apiKey
TENANT_IDstring✅ej: oietemaIdentificador de la empresa
ESTABLECIMIENTOnúmero✅1, 2…Puede reemplazarse con TENANT_PUNTO ej: "001-001"
PUNTOnúmero✅1, 2…Punto de expedición
RUCstring✅"2830501-9", cédula, "XX"Con o sin DV. XX para venta innominada
RAZON_SOCIALstring✅Nombre completo
PERSONAstring✅FISICA / JURIDICAIgnora acentos y mayúsculas
CONTRIBUYENTEstring✅SI / NO¿Tiene RUC activo en SIFEN?
ENTIDAD_DE_GOBIERNOstringOpcionalSI / NOSolo aplica a personas jurídicas. Nunca con FISICA. Default: NO
CONDICIONstring✅CONTADO / CREDITO
PLAZOstringCondicional"30 dias", "60 dias"Requerido si CONDICION=CREDITO
CODIGOstringOpcionalCódigo interno del cliente
DIRECCIONstringOpcionalTexto libreSe concilia automáticamente contra la BD de lugares
CORREO / EMAILstringOpcionalEmail válidoPara envío del KUDE al cliente
TELEFONO / CELULARstringOpcionalSolo dígitos, opcional + al inicio. Long. 6–15Teléfono del receptor para notificaciones (WhatsApp/SMS). Caracteres no numéricos se eliminan automáticamente.
DOCUMENTO_ASOCIADOstringOpcionalFACTURA / NOTA DE REMISIONDocumento al que referencia esta factura
FORMATOstringOpcionalTICKET / A4Formato del KUDE PDF. TICKET = 80 mm para impresoras térmicas. Si se omite, se genera A4.
MONEDAstringOpcionalUSDSi se omite o tiene otro valor, se factura en PYG (Guaraní) por defecto. Usar USD para facturar en dólares.
CAMBIOnúmeroCondicionalej: 6500Tipo de cambio (1 USD = X PYG). Requerido cuando MONEDA=USD. Debe ser mayor a 0.
ITEMSarray✅Ver tabla de itemsAl menos un elemento

Campos de cada item en ITEMS[]

CampoTipoObligatorioNotas
CODIGOstring/númeroOpcionalSi es numérico se rellena con ceros hasta 7 dígitos (1 → 0000001). Si falta se genera automáticamente.
DESCRIPCIONstring✅Descripción del producto o servicio
CANTIDADnúmero✅Debe ser mayor a 0
PRECIOnúmero✅Precio unitario. Puede ser 0.
IVAnúmeroOpcional0 = Exento, 5 = 5%, 10 = 10%. Default: 10
⚠️
IVA: 0 se interpreta siempre como Exento. No hay distinción entre exento y exonerado en el formato plano.

Ejemplos JSON completos

Contado · Persona Física · Contribuyente

JSON plano — Contado, B2B
[{
  "API_KEY": "TU_API_KEY",
  "TENANT_ID": "oietema",
  "ESTABLECIMIENTO": 1,
  "PUNTO": 1,
  "RUC": "2830501-9",
  "RAZON_SOCIAL": "MARCIAL ESTECHE",
  "CODIGO": "1",
  "DIRECCION": "CENTRAL, ASUNCION, CALLE SAN BLAZ 1250",
  "CORREO": "[email protected]",
  "TELEFONO": "0981123456",
  "CONDICION": "CONTADO",
  "PERSONA": "FISICA",
  "CONTRIBUYENTE": "SI",
  "ENTIDAD_DE_GOBIERNO": "NO",
  "ITEMS": [
    { "CODIGO": "1", "DESCRIPCION": "PEPINO EL KILO",    "CANTIDAD": 100, "PRECIO": 5000,  "IVA": 5 },
    { "CODIGO": "2", "DESCRIPCION": "HARINA EL KILO",    "CANTIDAD": 10,  "PRECIO": 9000,  "IVA": 10 },
    { "CODIGO": "3", "DESCRIPCION": "AYUDA COMUNITARIA", "CANTIDAD": 1,   "PRECIO": 50000, "IVA": 0 }
  ]
}]

Crédito · Persona Jurídica · Contribuyente

JSON plano — Crédito, B2B Jurídica
[{
  "API_KEY": "TU_API_KEY",
  "TENANT_ID": "oietema",
  "ESTABLECIMIENTO": 1,
  "PUNTO": 1,
  "RUC": "80029277-4",
  "RAZON_SOCIAL": "EMPRESA EJEMPLO S.A.",
  "CORREO": "[email protected]",
  "TELEFONO": "0981123456",
  "CONDICION": "CREDITO",
  "PLAZO": "30 dias",
  "PERSONA": "JURIDICA",
  "CONTRIBUYENTE": "SI",
  "ENTIDAD_DE_GOBIERNO": "NO",
  "ITEMS": [
    { "CODIGO": "1", "DESCRIPCION": "SERVICIO MENSUAL", "CANTIDAD": 1, "PRECIO": 500000, "IVA": 10 }
  ]
}]

Entidad de Gobierno · Crédito

JSON plano — Crédito, B2G
[{
  "API_KEY": "TU_API_KEY",
  "TENANT_ID": "oietema",
  "ESTABLECIMIENTO": 1,
  "PUNTO": 1,
  "RUC": "11001001-0",
  "RAZON_SOCIAL": "MUNICIPALIDAD DE ASUNCION",
  "CONDICION": "CREDITO",
  "PLAZO": "60 dias",
  "PERSONA": "JURIDICA",
  "CONTRIBUYENTE": "SI",
  "ENTIDAD_DE_GOBIERNO": "SI",
  "ITEMS": [
    { "CODIGO": "1", "DESCRIPCION": "MATERIALES DE CONSTRUCCION", "CANTIDAD": 10, "PRECIO": 200000, "IVA": 10 }
  ]
}]

No contribuyente · Venta innominada (XX)

JSON plano — B2C innominado
[{
  "API_KEY": "TU_API_KEY",
  "TENANT_ID": "oietema",
  "ESTABLECIMIENTO": 1,
  "PUNTO": 1,
  "RUC": "XX",
  "RAZON_SOCIAL": "Sin Nombre",
  "CONDICION": "CONTADO",
  "PERSONA": "FISICA",
  "CONTRIBUYENTE": "NO",
  "ITEMS": [
    { "DESCRIPCION": "VARIOS", "CANTIDAD": 1, "PRECIO": 15000, "IVA": 10 }
  ]
}]

Ejemplo VB6 (raw JSON)

ℹ️
VB6 debe enviar el body como raw JSON usando WinHttp.WinHttpRequest. No se usan campos de formulario. Requiere referencia: Microsoft WinHTTP Services, version 5.1.
VB6
' Requiere: Proyecto → Referencias → Microsoft WinHTTP Services, version 5.1

Public Function EnviarFacturaPlana() As String
    Dim http As WinHttp.WinHttpRequest
    Dim json As String
    Dim url As String

    url = "https://oietema.com/fact_elect/index.php"

    ' Construir JSON. Las comillas dobles dentro de VB6 se escriben como ""
    json = "[{" & _
           "\"API_KEY\":\"TU_API_KEY\"," & _
           "\"TENANT_ID\":\"oietema\"," & _
           "\"ESTABLECIMIENTO\":1," & _
           "\"PUNTO\":1," & _
           "\"RUC\":\"2830501-9\"," & _
           "\"RAZON_SOCIAL\":\"MARCIAL ESTECHE\"," & _
           "\"CONDICION\":\"CONTADO\"," & _
           "\"PERSONA\":\"FISICA\"," & _
           "\"CONTRIBUYENTE\":\"SI\"," & _
           "\"ENTIDAD_DE_GOBIERNO\":\"NO\"," & _
           "\"ITEMS\":[" & _
              "{\"CODIGO\":\"1\",\"DESCRIPCION\":\"PEPINO EL KILO\",\"CANTIDAD\":100,\"PRECIO\":5000,\"IVA\":5}," & _
              "{\"CODIGO\":\"2\",\"DESCRIPCION\":\"HARINA EL KILO\",\"CANTIDAD\":10,\"PRECIO\":9000,\"IVA\":10}" & _
           "]" & _
           "}]"

    Set http = New WinHttp.WinHttpRequest
    http.Open "POST", url, False
    http.SetRequestHeader "Content-Type", "application/json; charset=utf-8"
    http.Send json

    EnviarFacturaPlana = http.ResponseText
End Function

' Uso:
Private Sub Command1_Click()
    MsgBox EnviarFacturaPlana()
End Sub
⚠️
Si algún campo contiene ñ, tildes u otros caracteres especiales, usar la función auxiliar ToUtf8Bytes() para convertir el string antes de enviarlo y evitar corrupciones de codificación.

Función auxiliar UTF-8 para VB6: 
Public Function ToUtf8Bytes(ByVal s As String) As Byte()
    Dim ado As Object
    Set ado = CreateObject("ADODB.Stream")
    ado.Type = 2 : ado.Charset = "utf-8" : ado.Open
    ado.WriteText s
    ado.Position = 0 : ado.Type = 1 : ado.Position = 3
    ToUtf8Bytes = ado.Read
    ado.Close
End Function

' Luego: http.Send ToUtf8Bytes(json)

Mensajes de error del formato plano

Si la validación falla, la respuesta es texto plano con el listado de errores. Ningún número de factura se consume si hay errores de validación.

Ejemplo de respuesta de error (validación)
ERROR en los datos enviados (formato plano):
  - CONDICION=CREDITO requiere el campo PLAZO (ej.: "30 dias", "60 dias").

Corrija los datos y reintente. Ningún documento fue enviado a SIFEN.
Ejemplo: persona física marcada como entidad de gobierno
ERROR en los datos enviados (formato plano):
  - Una PERSONA FISICA no puede ser ENTIDAD DE GOBIERNO. Verifique los datos.

Corrija los datos y reintente. Ningún documento fue enviado a SIFEN.

Si SIFEN devuelve un error tras la emisión, se muestra el mensaje de SIFEN al integrador y se registra en la carpeta /bug/ del servidor con el contexto completo (tenant, número, CDC, JSON enviado, XML generado) para diagnóstico posterior.

Tabla de reglas cruzadas

PERSONACONTRIBUYENTEENTIDAD_DE_GOBIERNOiTiOpe generadoVálido
FISICASINO1 (B2B)✅
FISICANONO2 (B2C)✅
FISICASI / NOSI—❌ Error: persona física no puede ser entidad de gobierno
JURIDICASINO1 (B2B)✅
JURIDICASISI3 (B2G)✅
JURIDICANOSI—❌ Error: entidad de gobierno debe ser contribuyente
cualquieraNONO2 (B2C)✅

Nota de Remisión — Formato Plano

El endpoint remision.php acepta el campo data en dos formatos: el JSON experto de siempre (con cliente/receptor anidados y códigos SIFEN) y el formato plano, pensado para que el integrador envíe solo los datos de negocio y el servidor complete todo lo demás: emisor, timbrado, numeración, ubicaciones, fecha de emisión y transporte por defecto.

✅
Al igual que en factura, con el formato plano se puede enviar todo dentro de data (credenciales incluidas), sin parámetros POST adicionales (apiKey, tenantId, tenantPunto, cliente, email).
ℹ️
El sistema detecta automáticamente si la entrada es plana o experta. El formato experto de remisión sigue funcionando sin cambios; el plano es aditivo.

Reglas básicas

Campos disponibles

CampoTipoObligatorioValores aceptadosNotas
API_KEYstring✅Tu clave de APIPuede venir en el JSON o en el POST field apiKey
TENANT_IDstring✅ej: oietemaIdentificador de la empresa
ESTABLECIMIENTOnúmero✅1, 2…Puede reemplazarse con TENANT_PUNTO ej: "001-001"
PUNTOnúmero✅1, 2…Punto de expedición
RUCstring✅"80012345-6", cédula, "XX"Con DV si es contribuyente. XX para destinatario innominado
RAZON_SOCIALstring✅Nombre del destinatario
CONTRIBUYENTEstring✅SI / NO¿Tiene RUC activo en SIFEN?
PERSONAstringOpcionalFISICA / JURIDICADefault: JURIDICA. Ignora acentos y mayúsculas
CORREO / EMAILstringOpcionalEmail válidoPara envío del KUDE al destinatario
TELEFONO / CELULARstringOpcionalTexto libre
DIRECCIONstringOpcionalTexto libreDirección del receptor; también es el lugar de entrega por defecto
CIUDADstringOpcionalTexto libre, ej: "Caaguazú"El servidor la concilia al catálogo oficial SIFEN (departamento/distrito/ciudad)
MOTIVOnúmero/stringOpcional1–14, 99 o texto ("VENTAS", "DEVOLUCION"…)Motivo del traslado (E501). Default: 1 = Traslado por ventas. Ver tabla abajo
RESPONSABLEnúmero/stringOpcional1–5 o textoResponsable de la emisión (E505). Default: 1 = Emisor de la factura
KMSnúmeroRequeridoej: 25Km estimados de recorrido (dKmR). SIFEN lo exige en toda nota de remisión; debe ser mayor a 0
FECHA_FACTURAstringCondicionalYYYY-MM-DDFecha de la factura vinculada (dFecEm). Requerido si MOTIVO=1 (Traslado por ventas); opcional con los demás motivos. No puede ser posterior a hoy
TRANSPORTEstringOpcionalPROPIO / TERCEROSDefault: PROPIO. Con TERCEROS exige TRANSPORTISTA_*
MODALIDADstringOpcionalTERRESTRE / FLUVIAL / AEREO / MULTIMODALDefault: TERRESTRE
RESPONSABLE_FLETEstring/númeroOpcionalEMISOR / RECEPTOR / TERCERO / AGENTEDefault: EMISOR
TRANSPORTISTA_NOMBREstringCondicionalRazón social del transportistaRequerido si TRANSPORTE=TERCEROS
TRANSPORTISTA_RUCstringCondicional"80098765-4"Requerido si TRANSPORTE=TERCEROS. Con DV: NNNNNNNN-D
TRANSPORTISTA_DIRECCIONstringOpcionalTexto libreDomicilio fiscal del transportista
VEHICULOstring✅Chapa / matrícula, ej: "ABC 123" (máx. 20 caracteres)Obligatorio: SIFEN rechaza la nota de remisión sin el bloque de vehículo
VEHICULO_TIPOstringOpcionalej: "Camión", "Camioneta", "Furgoneta"Default: Camioneta. SIFEN admite 4 a 10 caracteres: textos más largos se acortan ("Camión de carga" → Camión, "Tractocamión" → Camión)
VEHICULO_MARCAstring✅ej: "Scania" (máx. 10 caracteres)Obligatorio (SIFEN exige la marca del vehículo)
CHOFER_NOMBREstring✅Nombre completo (máx. 60)Obligatorio: SIFEN exige el chofer en toda nota de remisión. Con transporte propio (sin TRANSPORTISTA_*) el servidor emite gCamTrans con el chofer como no contribuyente
CHOFER_DOCUMENTOstring✅Cédula del chofer (máx. 20)Obligatorio (SIFEN exige el documento del chofer)
SALIDA_DIRECCION / SALIDA_CIUDADstringOpcionalTexto libreSi no se envían, no se emite gCamSal (se asume el local del emisor, ya conocido por el tenant)
ENTREGA_DIRECCION / ENTREGA_CIUDADstringOpcionalTexto libreVacíos → el servidor los rellena con DIRECCION + CIUDAD del receptor
FORMATOstringOpcionalTICKET / A4Formato del KUDE PDF. Si se omite, se genera A4.
ITEMSarray✅Ver tabla de itemsAl menos un elemento

Campos de cada item en ITEMS[]

CampoTipoObligatorioNotas
CODIGOstring/númeroOpcionalSi es numérico se rellena con ceros hasta 7 dígitos (123 → 0000123). Si falta se genera automáticamente.
DESCRIPCIONstring✅Descripción de la mercadería
CANTIDADnúmero✅Debe ser mayor a 0
⚠️
La nota de remisión no lleva precios ni IVA. Si el integrador los envía dentro de los items, se ignoran.

Valores de MOTIVO (E501)

CódigoDescripciónCódigoDescripción
1Traslado por ventas8Traslado de bienes por transformación
2Traslado por consignación9Traslado de bienes por reparación
3Exportación10Traslado por emisor móvil
4Traslado por compra11Exhibición o demostración
5Importación12Participación en ferias
6Traslado por devolución13Traslado de encomienda
7Traslado entre locales de la empresa14 / 99Decomiso / Otro

Ejemplos JSON — 3 variantes

Variante A — Súper compacta (mínimo indispensable)

Solo datos obligatorios. El servidor asume: motivo 1 (Traslado por ventas), transporte propio terrestre, salida = local del emisor. Como el motivo es 1, FECHA_FACTURA es obligatoria; KMS, vehículo y chofer los exige SIFEN en toda remisión.

JSON plano remisión — mínimo
[{
  "API_KEY": "TU_API_KEY",
  "TENANT_ID": "oietema",
  "ESTABLECIMIENTO": 1,
  "PUNTO": 1,
  "RUC": "80012345-6",
  "RAZON_SOCIAL": "Juan Pérez",
  "CONTRIBUYENTE": "SI",
  "FECHA_FACTURA": "2026-09-17",
  "KMS": 25,
  "VEHICULO": "ABC 123",
  "VEHICULO_MARCA": "Toyota",
  "CHOFER_NOMBRE": "Pedro López",
  "CHOFER_DOCUMENTO": "4123456",
  "ITEMS": [
    {"DESCRIPCION": "Cajas de yerba", "CANTIDAD": 10}
  ]
}]

Variante B — Compacta (uso habitual)

Agrega contacto y dirección del receptor (que el servidor usa también como lugar de entrega), vehículo y chofer para el caso típico de transporte propio.

JSON plano remisión — habitual
[{
  "API_KEY": "TU_API_KEY",
  "TENANT_ID": "oietema",
  "ESTABLECIMIENTO": 1,
  "PUNTO": 1,
  "RUC": "80012345-6",
  "RAZON_SOCIAL": "Juan Pérez",
  "CONTRIBUYENTE": "SI",
  "CORREO": "[email protected]",
  "TELEFONO": "0981...",
  "DIRECCION": "Ruta 2 km 30",
  "CIUDAD": "Caaguazú",
  "MOTIVO": 1,
  "FECHA_FACTURA": "2026-09-17",
  "KMS": 25,
  "VEHICULO": "ABC 123",
  "CHOFER_NOMBRE": "Pedro López",
  "CHOFER_DOCUMENTO": "4123456",
  "ITEMS": [
    {"DESCRIPCION": "Cajas de yerba", "CANTIDAD": 10, "CODIGO": "123"}
  ]
}]

Variante C — Extensa (todas las opciones, incluido transporte de terceros)

Todos los campos soportados. Si un campo opcional va vacío o no se envía, el servidor aplica el default indicado (ver tabla de defaults más abajo).

JSON plano remisión — completo (comentado)
[{
  "API_KEY": "TU_API_KEY",
  "TENANT_ID": "oietema",
  "ESTABLECIMIENTO": 1,
  "PUNTO": 1,
  "RUC": "80012345-6",
  "RAZON_SOCIAL": "Juan Pérez",
  "CONTRIBUYENTE": "SI",
  "CORREO": "[email protected]",
  "TELEFONO": "0981...",
  "DIRECCION": "Ruta 2 km 30",
  "CIUDAD": "Caaguazú",

  // MOTIVO: opcional, default = 1. Acepta número (1-14, 99) o texto
  // ("VENTAS", "DEVOLUCION", "CONSIGNACION", ...). Ver tabla E501 arriba.
  "MOTIVO": 1,

  // RESPONSABLE: opcional, default = 1.  1 = Emisor de la factura
  // 2 = Poseedor  3 = Empresa transportista  4 = Despachante  5 = Agente
  "RESPONSABLE": 1,

  "KMS": 25,   // requerido, mayor a 0: SIFEN exige dKmR en toda remisión

  // FECHA_FACTURA: requerido si MOTIVO = 1 (Traslado por ventas); es la
  // fecha de la factura que respalda el traslado (dFecEm). Con los demás
  // motivos es opcional. No puede ser posterior a hoy.
  "FECHA_FACTURA": "2026-09-17",

  // ─────────── TRANSPORTE ───────────
  // TRANSPORTE: opcional, default = "PROPIO".
  //   "PROPIO"   → vehículo de la empresa emisora (iTipTrans=1)
  //   "TERCEROS" → transportista contratado (iTipTrans=2)
  "TRANSPORTE": "TERCEROS",

  // MODALIDAD: opcional, default = "TERRESTRE".
  //   TERRESTRE | FLUVIAL | AEREO | MULTIMODAL
  "MODALIDAD": "TERRESTRE",

  // ── Solo si TRANSPORTE="TERCEROS" (obligatorios en ese caso) ──
  // Si faltan, el servidor rechaza con error claro.
  "TRANSPORTISTA_NOMBRE": "Translog S.A.",
  "TRANSPORTISTA_RUC": "80098765-4",                  // con DV: NNNNNNNN-D
  "TRANSPORTISTA_DIRECCION": "Av. Eusebio Ayala 1234", // opcional

  // ── Vehículo. Opcional en ambos casos ──
  // Vacío o ausente → el bloque de vehículo no se emite en el XML.
  "VEHICULO": "ABC 123",        // chapa / matrícula
  "VEHICULO_TIPO": "Camión",    // opcional, default = "Camioneta"
  "VEHICULO_MARCA": "Scania",   // opcional

  // ── Chofer. Opcional ──
  // Con TRANSPORTE="PROPIO" (sin transportista), el servidor igual emite
  // el bloque gCamTrans como no-contribuyente con estos datos.
  "CHOFER_NOMBRE": "Pedro López",
  "CHOFER_DOCUMENTO": "4123456",

  // ── Salida. Opcional ──
  // Sin SALIDA_DIRECCION → no se emite; se asume el local del emisor.
  "SALIDA_DIRECCION": "Depósito central, Ruta 1 km 20",
  "SALIDA_CIUDAD": "San Lorenzo",   // texto libre; se concilia al catálogo SIFEN

  // ── Entrega. Opcional ──
  // Vacíos → el servidor los rellena con DIRECCION + CIUDAD del receptor.
  "ENTREGA_DIRECCION": "",
  "ENTREGA_CIUDAD": "",

  // ITEMS: obligatorio, al menos 1. Sin precios ni IVA.
  // CODIGO opcional: si falta se autogenera (0000001, 0000002, ...)
  "ITEMS": [
    {"DESCRIPCION": "Cajas de yerba", "CANTIDAD": 10, "CODIGO": "123"}
  ]
}]

¿Qué rellena el servidor cuando un campo va vacío?

CampoSi viene vacío o ausente
MOTIVO1 (Traslado por ventas)
RESPONSABLE1 (Emisor de la factura)
TRANSPORTEPROPIO
MODALIDADTERRESTRE
SALIDA_*No se emite (se asume el local del emisor)
ENTREGA_*DIRECCION + CIUDAD del receptor
VEHICULO, CHOFER_*Sin default: son obligatorios (SIFEN rechaza la remisión sin vehículo ni chofer)
TRANSPORTISTA_*Con PROPIO no se emite; con TERCEROS son obligatorios (junto con CHOFER_NOMBRE y CHOFER_DOCUMENTO)
CODIGO del itemSe autogenera (0000001, 0000002, ...)
CIUDAD / *_CIUDADTexto libre: el servidor lo concilia al catálogo oficial SIFEN
Fecha de emisiónSiempre la del servidor (se ignora la del integrador)
Número, timbrado, emisorSiempre desde el tenant en la base de datos

Mensajes de error

Si la validación falla, la respuesta es texto plano con el listado de errores. Ningún número de remisión se consume si hay errores de validación.

Ejemplo de respuesta de error (validación)
ERROR en los datos enviados (formato plano remisión):
  - TRANSPORTE=TERCEROS requiere TRANSPORTISTA_RUC (formato NNNNNNNN-D).
  - El dígito verificador del RUC '80012345-9' no es válido. Para el RUC '80012345' el DV correcto es '6'.

Nota de Crédito y Nota de Débito — Formato Plano

Las notas de crédito (NC) y de débito (ND) se emiten por el mismo endpoint que la factura (index.php, campo data) y con el mismo formato plano. La única diferencia es el campo TIPO_DOCUMENTO más dos datos obligatorios: el MOTIVO y la identificación de la factura original.

ℹ️
La NC resta (devoluciones, descuentos, anulación fuera del plazo de 48 h). La ND suma (intereses por mora, ajustes de precio hacia arriba, fletes y gastos recuperados). Salvo eso, el payload es idéntico.
⚠️
En SIFEN el timbrado electrónico se habilita por tipo de documento. Si el RUC nunca pidió a la SET la habilitación de nota de crédito o de débito, el envío es rechazado con 1101 — Número de timbrado inválido, aunque ese mismo timbrado facture sin problemas. No es un error del sistema ni del payload: hay que solicitar la habilitación a la SET.

Reglas básicas

Campos propios de NC / ND

Todos los campos del formato plano de factura (API_KEY, TENANT_ID, ESTABLECIMIENTO, PUNTO, RUC, RAZON_SOCIAL, PERSONA, CONTRIBUYENTE, ENTIDAD_DE_GOBIERNO, CONDICION, PLAZO, MONEDA, CAMBIO, EMAIL, ITEMS…) se usan igual. Estos son los que se agregan o cambian:

CampoTipoObligatorioValores aceptadosNotas
TIPO_DOCUMENTOstring✅NOTA_DE_CREDITO / NOTA_DE_DEBITOAlias aceptados: NC, NOTA_CREDITO, ND, NOTA_DEBITO. Sin este campo se emite una factura
MOTIVOnúmero/string✅1–8 o textoMotivo de emisión (E401). Ver tabla abajo
FACTURA_CDCstringCondicionalCDC de 44 dígitosRequerido si la factura original es electrónica. Excluyente con el bloque de factura impresa
FACTURA_TIMBRADOstringCondicionalej: "12557896"Requerido si la factura original es impresa o de otro emisor
FACTURA_NUMEROstringCondicionalej: "0001234"Requerido junto con FACTURA_TIMBRADO
FACTURA_FECHAstringCondicionalYYYY-MM-DDFecha de emisión de la factura impresa
FACTURA_ESTABLECIMIENTOstringOpcionalej: "001"Default: 001. Solo para factura impresa
FACTURA_PUNTOstringOpcionalej: "001"Default: 001. Solo para factura impresa
MONEDAstringOpcionalPYG / USD…Debe coincidir con la moneda de la factura original
CAMBIOnúmeroCondicionalej: 7300Requerido si MONEDA no es PYG. Guaraníes por 1 unidad de la moneda

Motivos de emisión (campo MOTIVO)

La misma tabla vale para NC y para ND. Se puede enviar el número o el texto.

CódigoDescripción SIFENTexto aceptadoUso típico
1Devolución y ajuste de preciosDEVOLUCION_Y_AJUSTENC — anular una factura completa
2DevoluciónDEVOLUCIONNC — el cliente devolvió mercadería
3DescuentoDESCUENTONC — descuento otorgado después de facturar
4BonificaciónBONIFICACIONNC — bonificación comercial
5Crédito incobrableCREDITO_INCOBRABLENC — deuda que no se va a cobrar
6Recupero de costoRECUPERO_DE_COSTOND — costo trasladado al cliente
7Recupero de gastoRECUPERO_DE_GASTOND — flete, seguro, gasto adelantado
8Ajuste de precioAJUSTE_DE_PRECIOND — interés por mora, ajuste hacia arriba
ℹ️
Los ocho códigos son válidos tanto en NC como en ND: SIFEN usa el mismo grupo gCamNCDE para los dos documentos. La columna «uso típico» es orientativa, no una restricción del sistema.

Ejemplos JSON

Nota de Débito — interés por mora sobre una factura electrónica

Un solo ítem con el importe que se cobra de más. La factura original se identifica por su CDC.

JSON plano — Nota de Débito
[{
  "API_KEY": "TU_API_KEY",
  "TENANT_ID": "oietema",
  "ESTABLECIMIENTO": 1,
  "PUNTO": 1,

  "TIPO_DOCUMENTO": "NOTA_DE_DEBITO",
  "MOTIVO": 8,
  "FACTURA_CDC": "01142345687001001000020612026081217825299084",

  "RUC": "80012345-6",
  "RAZON_SOCIAL": "Comercial Ejemplo SA",
  "PERSONA": "JURIDICA",
  "CONTRIBUYENTE": "SI",
  "ENTIDAD_DE_GOBIERNO": "NO",
  "CONDICION": "CONTADO",
  "MONEDA": "PYG",
  "EMAIL": "[email protected]",

  "ITEMS": [
    {"CODIGO": "INT", "DESCRIPCION": "Interes por mora", "CANTIDAD": 1, "PRECIO": 55000, "IVA": 10}
  ]
}]

Nota de Débito en moneda extranjera

Cuando la factura original está en dólares, la ND también. CAMBIO pasa a ser obligatorio.

JSON plano — ND en USD
[{
  "API_KEY": "TU_API_KEY",
  "TENANT_ID": "agro_br",
  "ESTABLECIMIENTO": 1,
  "PUNTO": 1,

  "TIPO_DOCUMENTO": "NOTA_DE_DEBITO",
  "MOTIVO": "AJUSTE_DE_PRECIO",
  "FACTURA_CDC": "01008447438001001000001512026090212033805740",

  "RUC": "80024030-8",
  "RAZON_SOCIAL": "LAR SRL",
  "PERSONA": "JURIDICA",
  "CONTRIBUYENTE": "SI",
  "ENTIDAD_DE_GOBIERNO": "NO",
  "CONDICION": "CONTADO",
  "MONEDA": "USD",
  "CAMBIO": 5980,

  "ITEMS": [
    {"CODIGO": "AJU", "DESCRIPCION": "Ajuste de precio", "CANTIDAD": 1, "PRECIO": 250, "IVA": 5}
  ]
}]

Nota de Crédito — anular una factura completa

Para dejar sin efecto una factura pasadas las 48 h de la cancelación, se emite una NC con los mismos ítems y el mismo importe que la factura original.

JSON plano — Nota de Crédito
[{
  "API_KEY": "TU_API_KEY",
  "TENANT_ID": "oietema",
  "ESTABLECIMIENTO": 1,
  "PUNTO": 1,

  "TIPO_DOCUMENTO": "NOTA_DE_CREDITO",
  "MOTIVO": 1,
  "FACTURA_CDC": "01142345687001001000020612026081217825299084",

  "RUC": "80012345-6",
  "RAZON_SOCIAL": "Comercial Ejemplo SA",
  "PERSONA": "JURIDICA",
  "CONTRIBUYENTE": "SI",
  "ENTIDAD_DE_GOBIERNO": "NO",
  "CONDICION": "CONTADO",
  "MONEDA": "PYG",

  "ITEMS": [
    {"CODIGO": "0000001", "DESCRIPCION": "Cartera Vizzano", "CANTIDAD": 1, "PRECIO": 300000, "IVA": 10}
  ]
}]

Nota de Crédito sobre una factura impresa (de otro emisor)

Sin CDC: se identifica la factura por timbrado, número y fecha.

JSON plano — NC sobre factura impresa
[{
  "API_KEY": "TU_API_KEY",
  "TENANT_ID": "oietema",
  "ESTABLECIMIENTO": 1,
  "PUNTO": 1,

  "TIPO_DOCUMENTO": "NOTA_DE_CREDITO",
  "MOTIVO": "DEVOLUCION",
  "FACTURA_TIMBRADO": "12557896",
  "FACTURA_ESTABLECIMIENTO": "002",
  "FACTURA_PUNTO": "005",
  "FACTURA_NUMERO": "0001234",
  "FACTURA_FECHA": "2026-03-15",

  "RUC": "80012345-6",
  "RAZON_SOCIAL": "Comercial Ejemplo SA",
  "PERSONA": "JURIDICA",
  "CONTRIBUYENTE": "SI",
  "ENTIDAD_DE_GOBIERNO": "NO",
  "CONDICION": "CONTADO",
  "MONEDA": "PYG",

  "ITEMS": [
    {"DESCRIPCION": "Devolucion de mercaderia", "CANTIDAD": 1, "PRECIO": 90000, "IVA": 10}
  ]
}]

Mensajes de error frecuentes

El validador responde antes de numerar y de enviar a SIFEN, así que estos errores no consumen numeración.

MensajeCausaSolución
TIPO_DOCUMENTO=NOTA_DE_DEBITO requiere el campo MOTIVOFalta MOTIVOEnviar un número del 1 al 8 o su texto
… requiere identificar la factura originalNo vino FACTURA_CDC ni FACTURA_TIMBRADO+FACTURA_NUMEROAgregar uno de los dos bloques
FACTURA_CDC debe tener exactamente 44 caracteresCDC incompleto o con separadoresEnviar los 44 dígitos, sin espacios ni guiones
Campo TIPO_DOCUMENTO debe ser FACTURA, NOTA_DE_CREDITO o NOTA_DE_DEBITOValor no reconocidoUsar uno de los valores o alias de la tabla
MONEDA=USD requiere el campo CAMBIOMoneda extranjera sin cotizaciónAgregar CAMBIO con los guaraníes por unidad
CONDICION=CREDITO requiere el campo PLAZOCondición a crédito sin plazoAgregar PLAZO, ej: "30 dias"
No hay registro de numeración para … tipo_documento: 5 (o 6)El punto de expedición no tiene el contador de NC/NDSe crea automáticamente al dar de alta empresas y puntos; si el punto es viejo, avisar al administrador
Error de SIFEN: Número de timbrado inválido (1101)El timbrado no está habilitado para ese tipo de documentoSolicitar a la SET la habilitación de nota de crédito / débito para el timbrado

Información General

URL Base
https://tu-dominio.com/fact_elect/
Método
POST
Content-Type
application/json (recomendado) o application/x-www-form-urlencoded
Autenticación
API Key por empresa

Endpoints Disponibles

POST index.php Emisión de Factura Electrónica
POST remision.php Emisión de Nota de Remisión Electrónica
GET kude.php?cdc={CDC} Visualización del KUDE
POST consultar_estado.php Consultar estado de un DE
POST consultar_ruc.php Consultar datos de un RUC en SIFEN
POST cancelar_api.php Cancelar una Factura Electrónica emitida

1. Emisión de Factura Electrónica

Parámetros POST (form-data)

Campo Tipo Obligatorio Descripción
apiKey string ✅ Clave API de la empresa
tenantId string ✅ Identificador del tenant/empresa (ej: puchi)
tenantPunto string Condicional Establecimiento-Punto de expedición (ej: 001-001). Puede omitirse si data[0].establecimiento y data[0].punto vienen dentro del JSON.
cliente string Condicional Nombre del cliente. Puede omitirse si viene en data[0].cliente.razonSocial.
email string Condicional Email del cliente (para envío del KUDE). Puede omitirse si viene en data[0].cliente.email.
data string (JSON) ✅ Datos de la factura en formato JSON (ver estructura abajo)
Nota: Los campos tenantPunto, cliente y email son condicionales: son requeridos sólo si no están presentes dentro del JSON data. Esto permite integrar sistemas que ya envían todos los datos en el JSON sin necesidad de duplicarlos en los parámetros POST.

Respuesta

Texto plano con formato:

Respuesta exitosa
Cliente: NOMBRE DEL CLIENTE
Estado: ok
Mensaje: Factura creada exitosamente...
NUM: 59-CDC: 01042287731001001000005912026041314432884104
Respuesta con error
Cliente: NOMBRE DEL CLIENTE
Estado: error
Mensaje: Error de SIFEN: [descripción del error]
NUM: 59-CDC: No disponible

2. Estructura del JSON (data)

El campo data es un array JSON con un solo elemento [{...}].

Ejemplo: Cliente Contribuyente (B2B)

JSON 
[
  {
    "tipoDocumento": 1,
    "tipoTransaccion": 1,
    "tipoImpuesto": 1,
    "moneda": "PYG",

    "cliente": {
      "contribuyente": true,
      "ruc": "80000004-2",
      "razonSocial": "EMPRESA IMPORTADORA S.A.",
      "tipoContribuyente": 2,
      "tipoOperacion": 1,
      "direccion": "AV. MARISCAL LOPEZ 1234",
      "numeroCasa": "1234",
      "departamento": 11,
      "departamentoDescripcion": "CENTRAL",
      "distrito": 1,
      "distritoDescripcion": "ASUNCION (DISTRITO)",
      "ciudad": 1,
      "ciudadDescripcion": "ASUNCION (DISTRITO)",
      "telefono": "021555123",
      "email": "[email protected]",
      "pais": "PRY",
      "paisDescripcion": "Paraguay",
      "codigo": "CLI001"
    },

    "items": [
      {
        "codigo": "0000001",
        "descripcion": "Jabón en Pan Cuñataí 180g",
        "unidadMedida": 77,
        "cantidad": 2,
        "precioUnitario": 1986,
        "iva": 5,
        "ivaTipo": 1,
        "ivaBase": 100
      },
      {
        "codigo": "0000002",
        "descripcion": "Arroz Paquete 1Kg",
        "unidadMedida": 77,
        "cantidad": 3,
        "precioUnitario": 8500,
        "iva": 10,
        "ivaTipo": 1,
        "ivaBase": 100
      }
    ],

    "condicion": {
      "tipo": 1,
      "entregas": [
        {
          "tipo": 1,
          "monto": 29472,
          "moneda": "PYG",
          "monedaDescripcion": "Guarani"
        }
      ]
    },

    "factura": {
      "presencia": 1
    }
  }
]

Ejemplo: Cliente No Contribuyente (B2C)

JSON 
[
  {
    "tipoDocumento": 1,
    "tipoTransaccion": 1,
    "tipoImpuesto": 1,
    "moneda": "PYG",

    "cliente": {
      "contribuyente": false,
      "tipoOperacion": 2,
      "documentoTipo": 1,
      "documentoNumero": "3456789",
      "razonSocial": "HECTOR ANTONIO BENITEZ VALDEZ",
      "direccion": "CALLE PRINCIPAL C/ SEGUNDA",
      "numeroCasa": "456",
      "departamento": 8,
      "departamentoDescripcion": "ITAPUA",
      "distrito": 89,
      "distritoDescripcion": "CAMBYRETA",
      "ciudad": 2600,
      "ciudadDescripcion": "CAMBYRETA",
      "telefono": "0975123456",
      "email": "[email protected]",
      "pais": "PRY",
      "paisDescripcion": "Paraguay",
      "codigo": "00180"
    },

    "items": [
      {
        "codigo": "0000001",
        "descripcion": "Jabón en Pan Cuñataí 180g",
        "unidadMedida": 77,
        "cantidad": 1,
        "precioUnitario": 1986,
        "iva": 5,
        "ivaTipo": 1,
        "ivaBase": 100
      },
      {
        "codigo": "0000002",
        "descripcion": "Jabón en Pan Cuñataí 270g",
        "unidadMedida": 77,
        "cantidad": 1,
        "precioUnitario": 2900,
        "iva": 0,
        "ivaTipo": 1,
        "ivaBase": 100
      },
      {
        "codigo": "0000003",
        "descripcion": "Bandera Paraguaya C/Mastil",
        "unidadMedida": 77,
        "cantidad": 1,
        "precioUnitario": 8500,
        "iva": 10,
        "ivaTipo": 1,
        "ivaBase": 100
      }
    ],

    "condicion": {
      "tipo": 1,
      "entregas": [
        {
          "tipo": 1,
          "monto": 13386,
          "moneda": "PYG",
          "monedaDescripcion": "Guarani"
        }
      ]
    },

    "factura": {
      "presencia": 1
    }
  }
]
ℹ️
Para no contribuyentes: usar documentoTipo + documentoNumero en lugar de ruc. El tipoOperacion debe ser 2 (B2C).

Ejemplo: Venta a Crédito

JSON 
[
  {
    "tipoDocumento": 1,
    "tipoTransaccion": 1,
    "tipoImpuesto": 1,
    "moneda": "PYG",

    "cliente": {
      "contribuyente": true,
      "ruc": "80000004-2",
      "razonSocial": "EMPRESA IMPORTADORA S.A.",
      "tipoContribuyente": 2,
      "tipoOperacion": 1,
      "direccion": "AV. MARISCAL LOPEZ 1234",
      "numeroCasa": "1234",
      "departamento": 11,
      "departamentoDescripcion": "CENTRAL",
      "distrito": 1,
      "distritoDescripcion": "ASUNCION (DISTRITO)",
      "ciudad": 1,
      "ciudadDescripcion": "ASUNCION (DISTRITO)",
      "email": "[email protected]",
      "pais": "PRY",
      "paisDescripcion": "Paraguay",
      "codigo": "CLI001"
    },

    "items": [
      {
        "codigo": "0000001",
        "descripcion": "Producto Ejemplo",
        "unidadMedida": 77,
        "cantidad": 10,
        "precioUnitario": 50000,
        "iva": 10,
        "ivaTipo": 1,
        "ivaBase": 100
      }
    ],

    "condicion": {
      "tipo": 2,
      "credito": {
        "tipo": 1,
        "plazo": "30 días",
        "cuotas": 1,
        "infoCuotas": [
          {
            "moneda": "PYG",
            "monedaDescripcion": "Guarani",
            "monto": 500000,
            "vencimiento": "2026-05-13"
          }
        ]
      }
    },

    "factura": {
      "presencia": 1
    }
  }
]

Ejemplos prácticos por tipo de cliente y condición de pago

Los siguientes ejemplos reflejan los casos reales de uso. La diferencia clave entre ellos está en los campos contribuyente, tipoContribuyente, tipoOperacion y la sección condicion.

ℹ️
contribuyente: false · tipoOperacion: 2 (B2C) · tipoContribuyente: 0 · identificar con documentoTipo: 1 (Cédula) y documentoNumero
JSON — No Contribuyente (Solo Cédula)
[{
  "tipoDocumento": 1,
  "establecimiento": 1,
  "punto": "1",
  "numero": 12,
  "descripcion": "Aparece en el documento",
  "observacion": "...",
  "fecha": "2026-04-22T10:20:49",
  "tipoEmision": 1,
  "tipoTransaccion": 3,
  "tipoImpuesto": 1,
  "moneda": "PYG",

  "cliente": {
    "contribuyente": false,
    "ruc": "2830501",
    "razonSocial": "MARCIAL ESTECHE",
    "nombreFantasia": "MARCIAL ESTECHE",
    "tipoOperacion": 2,
    "direccion": "Itapua, Encarnacion, 14 de mayo 1500",
    "numeroCasa": "",
    "departamento": 0,
    "departamentoDescripcion": "",
    "distrito": 0,
    "distritoDescripcion": "",
    "ciudad": 0,
    "ciudadDescripcion": "",
    "pais": "PRY",
    "paisDescripcion": "Paraguay",
    "tipoContribuyente": 0,
    "documentoTipo": 1,
    "documentoNumero": "2830501",
    "telefono": "595994858410",
    "celular": "595994858410",
    "email": "[email protected]",
    "codigo": "0001"
  },

  "usuario": {
    "documentoTipo": 1,
    "documentoNumero": "",
    "nombre": "",
    "cargo": "Vendedor"
  },

  "factura": { "presencia": 1 },

  "condicion": {
    "tipo": 1,
    "entregas": [{
      "tipo": 1,
      "monto": "22400",
      "moneda": "PYG",
      "monedaDescripcion": "Guarani",
      "cambio": 0
    }]
  },

  "items": [{
    "codigo": "0000001",
    "descripcion": "Martillo",
    "unidadMedida": 77,
    "cantidad": 2,
    "precioUnitario": 11200.00,
    "ivaTipo": 1,
    "ivaBase": 100,
    "iva": 10
  }]
}]
ℹ️
contribuyente: true · tipoOperacion: 1 (B2B) · tipoContribuyente: 1 (Unipersonal) · documentoTipo: 0 (RUC) · condicion.tipo: 1 (Contado)
JSON — Contribuyente Unipersonal · Contado
[{
  "tipoDocumento": 1,
  "establecimiento": 1,
  "punto": "1",
  "numero": 12,
  "descripcion": "Aparece en el documento",
  "observacion": "...",
  "fecha": "2026-04-22T10:21:19",
  "tipoEmision": 1,
  "tipoTransaccion": 3,
  "tipoImpuesto": 1,
  "moneda": "PYG",

  "cliente": {
    "contribuyente": true,
    "ruc": "2830501-9",
    "razonSocial": "MARCIAL ESTECHE",
    "nombreFantasia": "MARCIAL ESTECHE",
    "tipoOperacion": 1,
    "direccion": "Itapua, Encarnacion, 14 de mayo 1500",
    "numeroCasa": "",
    "departamento": 0,
    "departamentoDescripcion": "",
    "distrito": 0,
    "distritoDescripcion": "",
    "ciudad": 0,
    "ciudadDescripcion": "",
    "pais": "PRY",
    "paisDescripcion": "Paraguay",
    "tipoContribuyente": 1,
    "documentoTipo": 0,
    "documentoNumero": "2830501-9",
    "telefono": "595994858410",
    "celular": "595994858410",
    "email": "[email protected]",
    "codigo": "0001"
  },

  "usuario": {
    "documentoTipo": 1,
    "documentoNumero": "",
    "nombre": "",
    "cargo": "Vendedor"
  },

  "factura": { "presencia": 1 },

  "condicion": {
    "tipo": 1,
    "entregas": [{
      "tipo": 1,
      "monto": "22400",
      "moneda": "PYG",
      "monedaDescripcion": "Guarani",
      "cambio": 0
    }]
  },

  "items": [{
    "codigo": "0000001",
    "descripcion": "Martillo",
    "unidadMedida": 77,
    "cantidad": 2,
    "precioUnitario": 11200.00,
    "ivaTipo": 1,
    "ivaBase": 100,
    "iva": 10
  }]
}]
ℹ️
contribuyente: true · tipoContribuyente: 1 (Unipersonal) · condicion.tipo: 2 (Crédito) · el nodo credito reemplaza a entregas
JSON — Contribuyente Unipersonal · Crédito
[{
  "tipoDocumento": 1,
  "establecimiento": 1,
  "punto": "1",
  "numero": 12,
  "descripcion": "Aparece en el documento",
  "observacion": "...",
  "fecha": "2026-04-22T10:21:39",
  "tipoEmision": 1,
  "tipoTransaccion": 3,
  "tipoImpuesto": 1,
  "moneda": "PYG",

  "cliente": {
    "contribuyente": true,
    "ruc": "2830501-9",
    "razonSocial": "MARCIAL ESTECHE",
    "nombreFantasia": "MARCIAL ESTECHE",
    "tipoOperacion": 1,
    "direccion": "Itapua, Encarnacion, 14 de mayo 1500",
    "numeroCasa": "",
    "departamento": 0,
    "departamentoDescripcion": "",
    "distrito": 0,
    "distritoDescripcion": "",
    "ciudad": 0,
    "ciudadDescripcion": "",
    "pais": "PRY",
    "paisDescripcion": "Paraguay",
    "tipoContribuyente": 1,
    "documentoTipo": 0,
    "documentoNumero": "2830501-9",
    "telefono": "595994858410",
    "celular": "595994858410",
    "email": "[email protected]",
    "codigo": "0001"
  },

  "usuario": {
    "documentoTipo": 1,
    "documentoNumero": "",
    "nombre": "",
    "cargo": "Vendedor"
  },

  "factura": { "presencia": 1 },

  "condicion": {
    "tipo": 2,
    "credito": {
      "tipo": 1,
      "plazo": "30"
    }
  },

  "items": [{
    "codigo": "0000001",
    "descripcion": "Martillo",
    "unidadMedida": 77,
    "cantidad": 2,
    "precioUnitario": 11200.00,
    "ivaTipo": 1,
    "ivaBase": 100,
    "iva": 10
  }]
}]
ℹ️
contribuyente: true · tipoOperacion: 1 (B2B) · tipoContribuyente: 2 (Persona Jurídica) · condicion.tipo: 1 (Contado)
JSON — Persona Jurídica · Contado
[{
  "tipoDocumento": 1,
  "establecimiento": 1,
  "punto": "1",
  "numero": 12,
  "descripcion": "Aparece en el documento",
  "observacion": "...",
  "fecha": "2026-04-22T10:22:19",
  "tipoEmision": 1,
  "tipoTransaccion": 3,
  "tipoImpuesto": 1,
  "moneda": "PYG",

  "cliente": {
    "contribuyente": true,
    "ruc": "2830501-9",
    "razonSocial": "MARCIAL ESTECHE S.A.",
    "nombreFantasia": "MARCIAL ESTECHE S.A.",
    "tipoOperacion": 1,
    "direccion": "Itapua, Encarnacion, 14 de mayo 1500",
    "numeroCasa": "",
    "departamento": 0,
    "departamentoDescripcion": "",
    "distrito": 0,
    "distritoDescripcion": "",
    "ciudad": 0,
    "ciudadDescripcion": "",
    "pais": "PRY",
    "paisDescripcion": "Paraguay",
    "tipoContribuyente": 2,
    "documentoTipo": 0,
    "documentoNumero": "2830501-9",
    "telefono": "595994858410",
    "celular": "595994858410",
    "email": "[email protected]",
    "codigo": "0001"
  },

  "usuario": {
    "documentoTipo": 1,
    "documentoNumero": "",
    "nombre": "",
    "cargo": "Vendedor"
  },

  "factura": { "presencia": 1 },

  "condicion": {
    "tipo": 1,
    "entregas": [{
      "tipo": 1,
      "monto": "22400",
      "moneda": "PYG",
      "monedaDescripcion": "Guarani",
      "cambio": 0
    }]
  },

  "items": [{
    "codigo": "0000001",
    "descripcion": "Martillo",
    "unidadMedida": 77,
    "cantidad": 2,
    "precioUnitario": 11200.00,
    "ivaTipo": 1,
    "ivaBase": 100,
    "iva": 10
  }]
}]
ℹ️
contribuyente: true · tipoContribuyente: 2 (Persona Jurídica) · condicion.tipo: 2 (Crédito)
JSON — Persona Jurídica · Crédito
[{
  "tipoDocumento": 1,
  "establecimiento": 1,
  "punto": "1",
  "numero": 12,
  "descripcion": "Aparece en el documento",
  "observacion": "...",
  "fecha": "2026-04-22T10:22:38",
  "tipoEmision": 1,
  "tipoTransaccion": 3,
  "tipoImpuesto": 1,
  "moneda": "PYG",

  "cliente": {
    "contribuyente": true,
    "ruc": "2830501-9",
    "razonSocial": "MARCIAL ESTECHE S.A.",
    "nombreFantasia": "MARCIAL ESTECHE S.A.",
    "tipoOperacion": 1,
    "direccion": "Itapua, Encarnacion, 14 de mayo 1500",
    "numeroCasa": "",
    "departamento": 0,
    "departamentoDescripcion": "",
    "distrito": 0,
    "distritoDescripcion": "",
    "ciudad": 0,
    "ciudadDescripcion": "",
    "pais": "PRY",
    "paisDescripcion": "Paraguay",
    "tipoContribuyente": 2,
    "documentoTipo": 0,
    "documentoNumero": "2830501-9",
    "telefono": "595994858410",
    "celular": "595994858410",
    "email": "[email protected]",
    "codigo": "0001"
  },

  "usuario": {
    "documentoTipo": 1,
    "documentoNumero": "",
    "nombre": "",
    "cargo": "Vendedor"
  },

  "factura": { "presencia": 1 },

  "condicion": {
    "tipo": 2,
    "credito": {
      "tipo": 1,
      "plazo": "30"
    }
  },

  "items": [{
    "codigo": "0000001",
    "descripcion": "Martillo",
    "unidadMedida": 77,
    "cantidad": 2,
    "precioUnitario": 11200.00,
    "ivaTipo": 1,
    "ivaBase": 100,
    "iva": 10
  }]
}]
ℹ️
contribuyente: true · tipoOperacion: 3 (B2G — Entidad de Gobierno) · tipoContribuyente: 2 · condicion.tipo: 1 (Contado)
JSON — Entidad de Gobierno · Contado
[{
  "tipoDocumento": 1,
  "establecimiento": 1,
  "punto": "1",
  "numero": 12,
  "descripcion": "Aparece en el documento",
  "observacion": "...",
  "fecha": "2026-04-22T10:23:01",
  "tipoEmision": 1,
  "tipoTransaccion": 3,
  "tipoImpuesto": 1,
  "moneda": "PYG",

  "cliente": {
    "contribuyente": true,
    "ruc": "2830501-9",
    "razonSocial": "MINISTERIO DE HACIENDA",
    "nombreFantasia": "MINISTERIO DE HACIENDA",
    "tipoOperacion": 3,
    "direccion": "Itapua, Encarnacion, 14 de mayo 1500",
    "numeroCasa": "",
    "departamento": 0,
    "departamentoDescripcion": "",
    "distrito": 0,
    "distritoDescripcion": "",
    "ciudad": 0,
    "ciudadDescripcion": "",
    "pais": "PRY",
    "paisDescripcion": "Paraguay",
    "tipoContribuyente": 2,
    "documentoTipo": 0,
    "documentoNumero": "2830501-9",
    "telefono": "595994858410",
    "celular": "595994858410",
    "email": "[email protected]",
    "codigo": "0001"
  },

  "usuario": {
    "documentoTipo": 1,
    "documentoNumero": "",
    "nombre": "",
    "cargo": "Vendedor"
  },

  "factura": { "presencia": 1 },

  "condicion": {
    "tipo": 1,
    "entregas": [{
      "tipo": 1,
      "monto": "22400",
      "moneda": "PYG",
      "monedaDescripcion": "Guarani",
      "cambio": 0
    }]
  },

  "items": [{
    "codigo": "0000001",
    "descripcion": "Martillo",
    "unidadMedida": 77,
    "cantidad": 2,
    "precioUnitario": 11200.00,
    "ivaTipo": 1,
    "ivaBase": 100,
    "iva": 10
  }]
}]
ℹ️
contribuyente: true · tipoOperacion: 3 (B2G) · tipoContribuyente: 2 · condicion.tipo: 2 (Crédito)
JSON — Entidad de Gobierno · Crédito
[{
  "tipoDocumento": 1,
  "establecimiento": 1,
  "punto": "1",
  "numero": 12,
  "descripcion": "Aparece en el documento",
  "observacion": "...",
  "fecha": "2026-04-22T10:23:22",
  "tipoEmision": 1,
  "tipoTransaccion": 3,
  "tipoImpuesto": 1,
  "moneda": "PYG",

  "cliente": {
    "contribuyente": true,
    "ruc": "2830501-9",
    "razonSocial": "MINISTERIO DE HACIENDA",
    "nombreFantasia": "MINISTERIO DE HACIENDA",
    "tipoOperacion": 3,
    "direccion": "Itapua, Encarnacion, 14 de mayo 1500",
    "numeroCasa": "",
    "departamento": 0,
    "departamentoDescripcion": "",
    "distrito": 0,
    "distritoDescripcion": "",
    "ciudad": 0,
    "ciudadDescripcion": "",
    "pais": "PRY",
    "paisDescripcion": "Paraguay",
    "tipoContribuyente": 2,
    "documentoTipo": 0,
    "documentoNumero": "2830501-9",
    "telefono": "595994858410",
    "celular": "595994858410",
    "email": "[email protected]",
    "codigo": "0001"
  },

  "usuario": {
    "documentoTipo": 1,
    "documentoNumero": "",
    "nombre": "",
    "cargo": "Vendedor"
  },

  "factura": { "presencia": 1 },

  "condicion": {
    "tipo": 2,
    "credito": {
      "tipo": 1,
      "plazo": "30"
    }
  },

  "items": [{
    "codigo": "0000001",
    "descripcion": "Martillo",
    "unidadMedida": 77,
    "cantidad": 2,
    "precioUnitario": 11200.00,
    "ivaTipo": 1,
    "ivaBase": 100,
    "iva": 10
  }]
}]

3. Referencia de Campos

Objeto cliente

Campo Tipo Obligatorio Descripción Valores
contribuyente boolean ✅ ¿Es contribuyente? true / false
ruc string Solo contribuyente RUC con dígito verificador "80000004-2"
tipoContribuyente integer Solo contribuyente Tipo de contribuyente 1=Persona Física, 2=Persona Jurídica
tipoOperacion integer ✅ Tipo de operación 1=B2B, 2=B2C, 3=B2G, 4=B2F
documentoTipo integer Solo no contribuyente Tipo de documento de identidad Ver tabla abajo
documentoNumero string Solo no contribuyente Número de documento "3456789"
razonSocial string ✅ Nombre o razón social del cliente
direccion string ✅ Dirección del cliente
numeroCasa string Recomendado Número de casa "1234", "0" si no aplica
departamento integer Recomendado Código de departamento SIFEN Ver tabla de departamentos
departamentoDescripcion string Recomendado Nombre del departamento "ITAPUA", "CENTRAL"
distrito integer Recomendado Código de distrito SIFEN
distritoDescripcion string Recomendado Nombre del distrito
ciudad integer Recomendado Código de ciudad SIFEN
ciudadDescripcion string Recomendado Nombre de la ciudad
telefono string Opcional Teléfono
email string Recomendado Email del receptor
pais string Opcional Código ISO país "PRY" (defecto)
paisDescripcion string Opcional Nombre del país "Paraguay" (defecto)
codigo string Opcional Código interno de cliente (VB6) "00180"

Tipos de Documento de Identidad (documentoTipo)

CódigoDescripción
1Cédula paraguaya
2Pasaporte
3Cédula extranjera
4Carnet de residencia
5Innominado (ventas menores)
9Otro

Reglas Importantes del Cliente

⚠️
Contribuyente (contribuyente: true): Requiere ruc, tipoContribuyente y tipoOperacion: 1 (B2B).
No contribuyente (contribuyente: false): Requiere documentoTipo, documentoNumero y tipoOperacion: 2 (B2C). No enviar ruc.
Si se omite departamento/distrito/ciudad, el servidor intenta autocompletar a partir de direccion.

Objeto items[]

Campo Tipo Obligatorio Descripción Valores
codigo string ✅ Código interno del producto "0000001"
descripcion string ✅ Descripción del producto/servicio
unidadMedida integer Recomendado Código unidad de medida SIFEN 77=Unidad (defecto)
cantidad number ✅ Cantidad vendida
precioUnitario number ✅ Precio unitario con IVA incluido
iva number ✅ Tasa de IVA 0, 5 o 10
ivaTipo integer ✅ Tipo de afectación IVA 1=Gravado, 2=Exonerado, 3=Exento
ivaBase number Recomendado Proporción gravada (%) 100 (defecto)

Reglas del IVA

Escenario iva ivaTipo ivaBase Resultado SIFEN
Gravado 10% 10 1 100 IVA 10% sobre el total
Gravado 5% 5 1 100 IVA 5% sobre el total
Exento 0 1 100 Se convierte a Exento (afecIVA=3)
Exonerado 0 2 0 Exonerado - Art. 100 Ley 6380/2019
Parcialmente gravado 10 1 60 60% gravado al 10%, 40% exento
ℹ️
El precioUnitario siempre es con IVA incluido. El servidor calcula automáticamente la base gravada y la liquidación de IVA según las fórmulas NT13 del SIFEN.

Objeto condicion

CampoTipoObligatorioDescripciónValores
tipo integer ✅ Tipo de condición 1=Contado, 2=Crédito
entregas array Solo contado Detalle de pagos Ver abajo
credito object Solo crédito Datos del crédito Ver abajo

Entregas (pagos en contado)

CampoTipoObligatorioDescripciónValores
tipo integer ✅ Forma de pago 1=Efectivo, 2=Cheque, 3=Tarjeta crédito, 4=Tarjeta débito
monto number ✅ Monto del pago Si es 0, se completa automáticamente con el total
moneda string Opcional Moneda "PYG" (defecto)
monedaDescripcion string Opcional Descripción moneda "Guarani" (defecto)

Crédito

CampoTipoObligatorioDescripción
tipo integer ✅ 1=Plazo, 2=Cuota
plazo string ✅ Descripción del plazo ("30 días")
cuotas integer Si tipo=2 Cantidad de cuotas
infoCuotas array Si tipo=2 Detalle de cada cuota

Objeto factura

CampoTipoObligatorioDescripciónValores
presencia integer Opcional Indicador de presencia 1=Presencial (defecto), 2=No presencial, 3=Internet, 9=No corresponde

4. Ejemplo de Envío desde VB6

Visual Basic 6 
' ============================================
' Ejemplo de envío de Factura Electrónica
' desde Visual Basic 6 (VB6)
' ============================================

Private Sub EnviarFactura()
    Dim http As New MSXML2.XMLHTTP60
    Dim url As String
    Dim postData As String
    Dim jsonData As String
    
    url = "https://tu-dominio.com/fact_elect/index.php"
    
    ' Construir el JSON con los datos de la factura
    jsonData = "[{" & _
        """tipoDocumento"":1," & _
        """tipoTransaccion"":1," & _
        """tipoImpuesto"":1," & _
        """moneda"":""PYG""," & _
        """cliente"":{" & _
            """contribuyente"":true," & _
            """ruc"":""80000004-2""," & _
            """razonSocial"":""EMPRESA IMPORTADORA S.A.""," & _
            """tipoContribuyente"":2," & _
            """tipoOperacion"":1," & _
            """direccion"":""AV. MARISCAL LOPEZ 1234""," & _
            """numeroCasa"":""1234""," & _
            """departamento"":11," & _
            """departamentoDescripcion"":""CENTRAL""," & _
            """distrito"":1," & _
            """distritoDescripcion"":""ASUNCION (DISTRITO)""," & _
            """ciudad"":1," & _
            """ciudadDescripcion"":""ASUNCION (DISTRITO)""," & _
            """email"":""[email protected]""," & _
            """pais"":""PRY""," & _
            """paisDescripcion"":""Paraguay""," & _
            """codigo"":""CLI001""" & _
        "}," & _
        """items"":[" & _
            "{""codigo"":""0000001""," & _
             """descripcion"":""Producto Ejemplo""," & _
             """unidadMedida"":77," & _
             """cantidad"":2," & _
             """precioUnitario"":15000," & _
             """iva"":10," & _
             """ivaTipo"":1," & _
             """ivaBase"":100}" & _
        "]," & _
        """condicion"":{""tipo"":1,""entregas"":[{""tipo"":1,""monto"":30000,""moneda"":""PYG"",""monedaDescripcion"":""Guarani""}]}," & _
        """factura"":{""presencia"":1}" & _
    "}]"
    
    ' Construir datos POST
    postData = "apiKey=" & API_KEY & _
               "&tenantId=" & TENANT_ID & _
               "&tenantPunto=001-001" & _
               "&cliente=" & UrlEncode("EMPRESA IMPORTADORA S.A.") & _
               "&email=" & UrlEncode("[email protected]") & _
               "&data=" & UrlEncode(jsonData)
    
    ' Enviar POST
    http.Open "POST", url, False
    http.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
    http.send postData
    
    ' Procesar respuesta
    Dim respuesta As String
    respuesta = http.responseText
    
    ' Parsear respuesta
    ' Formato: "Cliente: ...\nEstado: ok\nMensaje: ...\nNUM: 59-CDC: 0104..."
    If InStr(respuesta, "Estado: ok") > 0 Then
        MsgBox "Factura enviada correctamente"
        ' Extraer CDC para consultas posteriores
        Dim cdc As String
        cdc = Mid(respuesta, InStr(respuesta, "CDC: ") + 5)
    Else
        MsgBox "Error: " & respuesta
    End If
End Sub

5. Cancelación de Factura Electrónica

Permite cancelar una factura previamente emitida enviando el evento de cancelación a SIFEN.

Parámetros POST

Campo Tipo Obligatorio Descripción
apiKey string ✅ Clave API de la empresa
tenantId string ✅ Identificador del tenant (ej: puchi)
cdc string ✅ CDC de 44 dígitos de la factura a cancelar
motivo string ✅ Texto libre con el motivo de la cancelación

Ejemplo PHP (cliente que llama al servidor)

PHP 
<?php
$url      = 'https://tu-dominio.com/fact_elect/cancelar_api.php';
$apiKey   = 'MiClaveSecreta';
$tenantId = 'puchi';
$cdc      = '01800292774001001000005422026031919322167553';
$motivo   = 'Error en el monto facturado';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'apiKey'   => $apiKey,
        'tenantId' => $tenantId,
        'cdc'      => $cdc,
        'motivo'   => $motivo,
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);

$respuesta = curl_exec($ch);
$error     = curl_error($ch);
curl_close($ch);

if ($error) {
    echo "Error cURL: $error";
} else {
    $json = json_decode($respuesta, true);
    // $json['status']   => 'ok' o 'error'
    // $json['message']  => descripción
    // $json['protocolo'] => número de protocolo SIFEN (si ok)
    print_r($json);
}

Respuesta JSON

Respuesta exitosa
{
  "status": "ok",
  "message": "Cancelación procesada exitosamente",
  "protocolo": "123456789"
}
Respuesta con error
{
  "status": "error",
  "message": "CDC inválido: debe contener exactamente 44 dígitos numéricos."
}
⚠️
Solo se pueden cancelar facturas en estado Aprobado. El motivo de cancelación debe tener al menos 5 caracteres.

5b. Visualización del KUDE (kude.php)

Genera la representación gráfica (HTML imprimible) del Documento Electrónico a partir de su CDC. Soporta dos formatos de impresión.

Método y URL

http
GET kude.php?cdc={CDC44}&formato={FORMATO}

Parámetros GET

ParámetroTipoObligatorioValoresDescripción
cdc string ✅ 44 dígitos numéricos Código de Control del Documento Electrónico
formato string Opcional ticket / (omitir para A4) Formato del KUDE. ticket = 80 mm para impresoras térmicas. Si se omite, se genera en A4. También se acepta el alias format.

Ejemplos de URL

A4 (por defecto)
GET kude.php?cdc=01142345687001001000006612026051910238751318
Ticket 80 mm (impresora térmica)
GET kude.php?cdc=01142345687001001000006612026051910238751318&formato=ticket
ℹ️
La página devuelta es HTML puro. Para obtener un PDF, el cliente puede usar Ctrl+P → Guardar como PDF en el navegador, o procesarla con una herramienta de conversión HTML→PDF (Puppeteer, wkhtmltopdf, etc.).

6. Ejemplo con cURL

bash 
curl -X POST https://tu-dominio.com/fact_elect/index.php \
  -d "apiKey=TU_API_KEY" \
  -d "tenantId=puchi" \
  -d "tenantPunto=001-001" \
  -d "cliente=EMPRESA IMPORTADORA S.A." \
  -d "[email protected]" \
  --data-urlencode 'data=[{"tipoDocumento":1,...}]'

7. Departamentos de Paraguay

CódigoDepartamento
1CONCEPCION
2SAN PEDRO
3CORDILLERA
4GUAIRA
5CAAGUAZU
6CAAZAPA
7ITAPUA
8MISIONES
9PARAGUARI
10ALTO PARANA
11CENTRAL
12ÑEEMBUCU
13AMAMBAY
14CANINDEYU
15PRESIDENTE HAYES
16BOQUERON
17ALTO PARAGUAY
18CAPITAL
ℹ️
Si no se envían departamento/distrito/ciudad, el servidor intentará autocompletarlos a partir del campo direccion.

8. Unidades de Medida Comunes

CódigoDescripción
77Unidad (UNI)
83Kilogramo (KG)
79Litro (LT)
80Metro (MT)
81Metro cuadrado (M2)
82Metro cúbico (M3)
85Pieza
86Docena

9. Tipos de Transacción

CódigoDescripción
1Venta de mercadería
2Prestación de servicios
3Mixto (mercadería y servicios)
4Venta de activo fijo
5Venta de divisas
6Compra de divisas
7Promoción o entrega de muestras
8Donación
9Anticipo
10Compra de productos
11Compra de servicios
13Otro

10. Notas Importantes

✅
  1. El número de factura se asigna automáticamente por el servidor. No se envía en el JSON.
  2. El precio unitario es siempre con IVA incluido. El servidor calcula la base gravada y el IVA.
  3. Si iva=0 con ivaTipo=1, el servidor asume automáticamente que es Exento (afecIVA=3).
  4. Para no contribuyentes, no enviar campo ruc. Usar documentoTipo + documentoNumero.
  5. El campo data debe ir URL-encoded ya que se envía como form-data.
  6. La dirección es autoconciliada: si no se envían códigos de departamento/distrito/ciudad, el servidor busca coincidencias automáticas.
  7. Si el monto de la entrega es 0 en condición contado, se autocompletará con el total de la factura.
  8. Los reintentos por duplicado son automáticos: si SIFEN rechaza por número duplicado, el servidor incrementa y reintenta (hasta 3 veces).

11. Configuración Previa (Admin)

Antes de usar la API, la empresa debe estar configurada en el panel de administración (/admin/):

  1. Empresa registrada con RUC, certificado digital (.p12) y CSC.
  2. Punto de expedición creado (ej: 001-001).
  3. API Key generada para la empresa.
  4. Numeración inicializada en la tabla numero_fact.
Documentación generada para SIFEN v150 — Paraguay