Cómo enviar tu JSON a la API

00 Qué hace esta API

El sistema emisor solo arma el JSON de la venta y lo manda. La API se encarga de todo lo de SIFEN:

• genera el CDC (los 44 dígitos de control)
• genera el XML rDE y lo firma digitalmente con el certificado de la empresa
• calcula el código QR (dCarQR / cHashQR)
• arma el lote, lo envía a SIFEN y hace el seguimiento del estado
• guarda el XML firmado y el JSON original
• genera el KUDE (la representación gráfica en PDF para el cliente)

El sistema emisor no necesita certificado, CSC, librerías de XML o firma, ni conocer los WebServices de SIFEN.

Tipos de comprobante que emite la API — campo tipoDocumento

Por defecto solo están habilitados 1, 5 y 6. Para emitir Autofactura (4) o Nota de Remisión (7) el proveedor debe habilitarlas para tu empresa; si mandás un tipo no habilitado la API responde 422 (ver N13).

01 La URL de la API puede variar

Esta API funciona bajo cualquier URL: dominio propio, subdominio, IP con puerto o incluso una subcarpeta. Ejemplos válidos de base:

https://facturacion.miempresa.com
https://erp.miempresa.com.py:8443
http://192.168.10.20:8080
https://apps.miempresa.com/facturacion

En este manual esa parte se escribe como {BASE_URL} (sin barra final). El proveedor de la API te entrega el valor real al dar de alta la empresa. Todos los endpoints se arman igual: {BASE_URL} + ruta.

API nueva — recomendada para sistemas nuevos

API legacy — compatible con el sistema PHP anterior

El cliente Delphi existente sigue funcionando cambiando solo el host de la URL. La ruta y el formato de respuesta no cambian.

02 Autenticación

API nueva — token Bearer

Cabecera Authorization: Bearer <TOKEN>. El token se genera una vez en el panel de administración: {BASE_URL}/admin/tokens (o {BASE_URL}/e/{tu-slug}/admin/tokens si tu proveedor activó el modo multiempresa, ver §15) → «Nuevo token» → se copia (no se vuelve a mostrar). Un token por sistema consumidor.

API legacy (/api-py/*)

Sin token de sesión. El acceso se restringe opcionalmente por lista de IPs y/o una cabecera X-Legacy-Token, ambas configuradas del lado del servidor. Si tu IP está permitida, no mandás nada.

El ambiente (test / producción) lo decide la API por su propia configuración. El sistema emisor no lo envía.

03 Reglas que debe cumplir el sistema emisor

Leer antes de integrar. Cada regla tiene un identificador (N0…N14) que se referencia en el resto del manual.

dBasGravIVA = 100 * totalItem * ivaBase / (10000 + ivaBase * tasa)
dLiqIVAItem = dBasGravIVA * tasa / 100

ejemplo:  totalItem 45000 al 10%  →  basGravIVA 40909.09090909
                                     liqIVAItem  4090.90909091
Exento (ivaTipo 3) / Exonerado (ivaTipo 2):  basGravIVA = 0 ; liqIVAItem = 0

04 Contrato JSON — campo por campo

Leyenda: R requerido   O opcional   C condicional.

Raíz

factura — obligatorio solo si tipoDocumento = 1

vendedor — obligatorio solo si tipoDocumento = 4 (Autofactura, N11)

cliente

compraPublica — obligatorio solo si cliente.tipoOperacion = 3 (B2G, N14)

Estos 5 datos los emite la Dirección Nacional de Contrataciones Públicas (DNCP) para el proceso de compra; sin ellos SIFEN rechaza la Factura a un organismo del Estado (código 1400 del Manual Técnico SIFEN). No enviar este bloque si tipoOperacion es 1, 2 o 4.

condicion

Si tipo = 2 sin bloque credito, la API inyecta { iCondCred: 1, dDCondCred: "Plazo", dPlazoCre: "30 dias" }. En infoTarjeta: si la procesadora no tiene RUC, "ruc": "-"; si tipo = 99, agregar tipoDescripcion.

items[] — al menos 1

C = obligatorio salvo en la Nota de Remisión (tipoDocumento 7), que describe la mercadería sin precio ni IVA: ahí no enviar precioUnitario / descuento* / anticipo* / totalItem / ivaTipo / ivaBase / iva. Para el resto de los tipos son obligatorios.

totales, notaCreditoDebito

documentoAsociado — obligatorio si tipoDocumento 5 o 6 (N9); opcional para el resto

Referencia libre a otro comprobante. El campo formato decide qué otros campos van:

remision — obligatorio solo si tipoDocumento = 7 (N12)

transporte — obligatorio solo si tipoDocumento = 7 (N12)

05 Ejemplos

Factura electrónica al contado — el caso más común

// Headers: Content-Type: application/json · Accept: application/json
//          Authorization: Bearer <TOKEN> · Idempotency-Key: FE-001-001-0000001
{
  "recordID": "5F-7111E5F9",
  "tipoDocumento": 1,
  "tipoEmision": 1,
  "establecimiento": "001",
  "punto": "001",
  "numero": "0000001",
  "fecha": "2026-05-27T10:15:00",
  "moneda": "PYG",
  "tipoImpuesto": 1,
  "tipoTransaccion": 1,
  "condicionAnticipo": 1,
  "descripcion": "Venta mostrador",
  "factura": { "presencia": 1 },
  "cliente": {
    "contribuyente": false,
    "tipoOperacion": 2,
    "pais": "PRY",
    "paisDescripcion": "PARAGUAY",
    "razonSocial": "DUARTE GONZALEZ, DERLIS ARIEL",
    "TipoDocumentoIdentidad": 1,
    "NumeroDocumentoIdentidad": "4829212"
  },
  "condicion": {
    "tipo": 1,
    "contado": [ { "tipo": 1, "monto": 45000, "moneda": "PYG" } ]
  },
  "items": [
    {
      "codigo": "1",
      "descripcion": "CARNAZA DE PRIMERA",
      "unidadMedida": 77, "unidadMedidaDesc": "UNI",
      "cantidad": 1, "precioUnitario": 45000,
      "pais": "PRY", "paisDescripcion": "PARAGUAY",
      "descuento": 0, "descuentoPorcentaje": 0, "descuentoGlobal": 0,
      "anticipo": 0, "anticipoGlobal": 0,
      "totalItem": 45000,
      "ivaTipo": 1, "ivaBase": 100, "iva": 10,
      "basGravIVA": 40910, "liqIVAItem": 4090
    }
  ],
  "totales": {
    "dTotDesc": 0, "dTotDescGlotem": 0, "dTotAntItem": 0, "dTotAnt": 0,
    "dPorcDescTotal": 0, "dDescTotal": 0, "dAnticipo": 0, "dRedon": 0
  }
}

{
  "success": true,
  "cdc": "01042214610001001000000112026052717799105109",
  "record_id": "5F-7111E5F9",
  "numero_completo": "001-001-0000001",
  "estado": "enviado",
  "estado_sifen": "Pendiente",
  "mensaje_sifen": "Lote recibido por SIFEN. Pendiente de consulta automatica.",
  "nro_lote": "1234567890",
  "qr_url": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=...",
  "links": {
    "xml":  "{BASE_URL}/api/v1/documentos/01042214.../xml",
    "json": "{BASE_URL}/api/v1/documentos/01042214.../json",
    "kude": "{BASE_URL}/api/v1/documentos/01042214.../kude?format=pdf",
    "qr":   "{BASE_URL}/api/v1/documentos/01042214.../qr"
  },
  "documento": { /* recurso completo */ }
}

Equivalente por la ruta legacy — siempre HTTP 200

{
  "respuesta_sifen": { "dCodRes": "0300", "dMsgRes": "Lote recibido con exito",
                       "dProtConsLote": "1234567890" },
  "cdc": "01042214610001001000000112026052717799105109",
  "nro_lote": "1234567890",
  "estado_sifen": "Pendiente",
  "mensaje_sifen": "Lote recibido por SIFEN. Pendiente de consulta automatica."
}

Cliente contribuyente (con RUC) y varios ítems, uno exento

"cliente": {
  "contribuyente": true,
  "tipoOperacion": 1,
  "pais": "PRY", "paisDescripcion": "PARAGUAY",
  "ruc": "80012345-6",
  "tipoContribuyente": 2,
  "razonSocial": "CONSTRUCTORA DEL ESTE S.A.",
  "nombreFantasia": "CONESA",
  "email": "compras@conesa.com.py", "codigo": "CLI-000123"
},
"items": [
  { "codigo": "CEM-50", "descripcion": "CEMENTO PORTLAND 50KG",
    "cantidad": 10, "precioUnitario": 55000, "totalItem": 550000,
    "pais": "PRY", "paisDescripcion": "PARAGUAY",
    "descuento": 0, "descuentoPorcentaje": 0, "descuentoGlobal": 0,
    "anticipo": 0, "anticipoGlobal": 0,
    "ivaTipo": 1, "ivaBase": 100, "iva": 10,
    "basGravIVA": 500000, "liqIVAItem": 50000 },
  { "codigo": "LIB-01", "descripcion": "LIBRO TECNICO (EXENTO)",
    "cantidad": 1, "precioUnitario": 80000, "totalItem": 80000,
    "pais": "PRY", "paisDescripcion": "PARAGUAY",
    "descuento": 0, "descuentoPorcentaje": 0, "descuentoGlobal": 0,
    "anticipo": 0, "anticipoGlobal": 0,
    "ivaTipo": 3, "ivaBase": 0, "iva": 0,
    "basGravIVA": 0, "liqIVAItem": 0 }
]
// La API calcula: dSub10 = 550000  dSubExe = 80000  dTotGralOpe = 630000
//                dIVA10 = 50000   dTotIVA = 50000   dBaseGrav10 = 500000

Nota de crédito electrónica

{
  "recordID": "5F-7111E5F9",
  "tipoDocumento": 5,
  "tipoEmision": 1,
  "establecimiento": "001", "punto": "001", "numero": "0000045",
  "fecha": "2026-06-02T10:15:00",
  "moneda": "PYG", "tipoImpuesto": 1, "condicionAnticipo": 1,
  "notaCreditoDebito": { "motivo": 2 },
  "documentoAsociado": {
    "formato": 1,
    "cdc": "01042214610001001000000112026052717799105109"
  },
  "cliente": { /* igual que en la factura original */ },
  "condicion": { "tipo": 1,
                 "contado": [ { "tipo": 1, "monto": 45000, "moneda": "PYG" } ] },
  "items": [ /* los items que se devuelven, con su IVA */ ],
  "totales": { "dTotDesc": 0, "dTotDescGlotem": 0, "dTotAntItem": 0,
               "dTotAnt": 0, "dPorcDescTotal": 0, "dDescTotal": 0,
               "dAnticipo": 0, "dRedon": 0 }
}
// Para NOTA DE DEBITO: tipoDocumento = 6 (el resto idéntico). En NC/ND no se envía "factura".

Autofactura Electrónica (tipoDocumento 4)

Compra a un proveedor no contribuyente. El receptor (cliente) es el propio emisor; vendedor identifica a quién se le compró. No se envía factura.

{
  "recordID": "5F-7111E5F9",
  "tipoDocumento": 4,
  "tipoEmision": 1,
  "establecimiento": "001", "punto": "001", "numero": "0000010",
  "fecha": "2026-06-03T09:00:00",
  "moneda": "PYG", "tipoImpuesto": 1, "tipoTransaccion": 10,
  "condicionAnticipo": 1,
  "cliente": {
    "contribuyente": true,
    "tipoOperacion": 1,
    "pais": "PRY", "paisDescripcion": "PARAGUAY",
    "ruc": "3010353-3",
    "tipoContribuyente": 1,
    "razonSocial": "DANIA SOFIA CORONEL NOGUERA"
  },
  "vendedor": {
    "naturaleza": 1,
    "tipoDocumentoIdentidad": 1,
    "numeroDocumentoIdentidad": "2345678",
    "nombre": "JUAN PEREZ",
    "direccion": "RUTA 2 KM 45", "numeroCasa": "0",
    "departamento": 5, "departamentoDescripcion": "GUAIRA",
    "ciudad": 2657, "ciudadDescripcion": "VILLARRICA"
  },
  "condicion": { "tipo": 1,
                 "contado": [ { "tipo": 1, "monto": 150000, "moneda": "PYG" } ] },
  "items": [
    { "codigo": "MAIZ", "descripcion": "MAIZ A GRANEL",
      "unidadMedida": 79, "unidadMedidaDesc": "kg",
      "cantidad": 100, "precioUnitario": 1500,
      "pais": "PRY", "paisDescripcion": "PARAGUAY",
      "totalItem": 150000,
      "ivaTipo": 1, "ivaBase": 100, "iva": 10 }
  ],
  "totales": { "dTotDesc": 0, "dTotDescGlotem": 0, "dTotAntItem": 0, "dTotAnt": 0,
               "dPorcDescTotal": 0, "dDescTotal": 0, "dAnticipo": 0, "dRedon": 0 },
  "documentoAsociado": { "formato": 3, "tipoConstancia": 1 }
}
// "cliente.ruc" / "cliente.razonSocial" son los del PROPIO emisor. El CDC de una Autofactura empieza con "04".

Nota de Remisión Electrónica (tipoDocumento 7)

Ampara un traslado de mercadería. Sin factura, sin condicion, sin totales, sin tipoImpuesto/condicionAnticipo. Los ítems no llevan precio ni IVA.

{
  "recordID": "5F-7111E5F9",
  "tipoDocumento": 7,
  "tipoEmision": 1,
  "establecimiento": "001", "punto": "001", "numero": "0000011",
  "fecha": "2026-06-04T07:30:00",
  "moneda": "PYG",
  "cliente": {
    "contribuyente": true, "tipoOperacion": 1,
    "pais": "PRY", "paisDescripcion": "PARAGUAY",
    "ruc": "80012345-6", "tipoContribuyente": 2,
    "razonSocial": "CONSTRUCTORA DEL ESTE S.A."
  },
  "remision": { "motivo": 1, "responsable": 1, "kmRecorrido": 180,
                "fechaEmisionFactura": "2026-06-04" },
  "transporte": {
    "tipoTransporte": 1,
    "modalidad": 1,
    "responsableFlete": 5,
    "fechaInicioTraslado": "2026-06-04",
    "fechaFinTraslado": "2026-06-04",
    "localSalida": {
      "direccion": "DEPOSITO CENTRAL", "numeroCasa": "0",
      "departamento": 5, "departamentoDescripcion": "GUAIRA",
      "ciudad": 2657, "ciudadDescripcion": "VILLARRICA"
    },
    "localEntrega": {
      "direccion": "OBRA AVDA. MCAL. LOPEZ 1234", "numeroCasa": "1234",
      "departamento": 1, "departamentoDescripcion": "CAPITAL",
      "ciudad": 1, "ciudadDescripcion": "ASUNCION"
    },
    "vehiculo": {
      "tipo": "CAMION", "marca": "HINO",
      "tipoIdentificacion": 2, "numeroMatricula": "ABC123"
    },
    "transportista": {
      "naturaleza": 1, "nombre": "FLETES DEL SUR SRL", "ruc": "80099999-0",
      "choferDocumentoIdentidad": "1234567", "choferNombre": "PEDRO GOMEZ"
    }
  },
  "items": [
    { "codigo": "CEM-50", "descripcion": "CEMENTO PORTLAND 50KG",
      "unidadMedida": 77, "unidadMedidaDesc": "UNI",
      "cantidad": 200,
      "pais": "PRY", "paisDescripcion": "PARAGUAY" }
  ]
}
// El CDC de una Nota de Remision empieza con "07". Puede quedar "Pendiente" igual que una factura; el KUDE se imprime para acompañar la carga.

Venta al Estado / B2G — ej. un ministerio (N14)

Factura Electrónica normal (tipoDocumento 1), pero el receptor es una entidad de gobierno: cliente.tipoOperacion = 3, y es obligatorio el bloque compraPublica con los datos del código de contratación (DNCP).

{
  "recordID": "5F-7111E5F9",
  "tipoDocumento": 1,
  "tipoEmision": 1,
  "establecimiento": "001", "punto": "001", "numero": "0000012",
  "fecha": "2026-06-05T10:00:00",
  "moneda": "PYG", "tipoImpuesto": 1, "tipoTransaccion": 1,
  "condicionAnticipo": 1,
  "factura": { "presencia": 1 },
  "cliente": {
    "contribuyente": true,
    "tipoOperacion": 3,
    "pais": "PRY", "paisDescripcion": "PARAGUAY",
    "ruc": "80000000-2",
    "tipoContribuyente": 2,
    "razonSocial": "MINISTERIO DE EDUCACION Y CIENCIAS (EJEMPLO)"
  },
  "compraPublica": {
    "modalidad": "LC",
    "entidad": "00001",
    "anio": "26",
    "secuencia": "0000001",
    "fechaCodigo": "2026-05-20"
  },
  "condicion": { "tipo": 1,
                 "contado": [ { "tipo": 1, "monto": 550000, "moneda": "PYG" } ] },
  "items": [
    { "codigo": "SERV-01", "descripcion": "MATERIAL DIDACTICO",
      "unidadMedida": 77, "unidadMedidaDesc": "UNI",
      "cantidad": 1, "precioUnitario": 500000,
      "pais": "PRY", "paisDescripcion": "PARAGUAY",
      "totalItem": 500000,
      "ivaTipo": 1, "ivaBase": 100, "iva": 10 }
  ],
  "totales": { "dTotDesc": 0, "dTotDescGlotem": 0, "dTotAntItem": 0, "dTotAnt": 0,
               "dPorcDescTotal": 0, "dDescTotal": 0, "dAnticipo": 0, "dRedon": 0 }
}
// El RUC del ministerio y los datos de "compraPublica" son de EJEMPLO: usá el RUC real del organismo y el código de contratación que te entregó la DNCP.

06 Respuestas HTTP

API nueva — POST /api/v1/documentos

API legacy — POST /api-py/firmar-enviar.php

Siempre HTTP 200. El resultado se lee en el cuerpo:

Estados posibles (estado_sifen): Pendiente · Aprobado · Aprobado con observacion · Rechazado · ERROR.

07 Idempotencia — cabecera Idempotency-Key

Recomendada siempre en la API nueva.

• 1.er POST con esa clave → emite normal (201).
• 2.º POST con la misma clave y el mismo JSON → no duplica: devuelve el documento ya emitido con HTTP 200 (mismo cdc).
• Sin Idempotency-Key, repetir el número da 409.

Uso típico: ante un timeout de red, reintentás el mismo request con la misma clave y recuperás el CDC sin arriesgarte a emitir dos veces. La ruta legacy no usa la cabecera: repetir el mismo número devuelve igual (200) el documento ya emitido.

08 Consultar el estado

Al emitir casi siempre vuelve Pendiente: SIFEN procesa el lote de forma asíncrona. La API consulta sola el estado final con reintentos a 5 s, 15 s, 1 min, 5 min, 15 min y 1 h. El comprobante ya es válido para entregar al cliente (el KUDE se puede imprimir) aunque esté Pendiente.

El sistema emisor puede consultar cuando quiera:

09 Descargar XML / JSON / QR / KUDE

Legacy: get_xml.php?cdc= · get_json.php?cdc= · get_qr.php?cdc= · kude.php?cdc=&format=pdf.

El KUDE en PDF ya trae el QR embebido. Nunca reconstruir el QR por cuenta propia: usar el PDF de la API o el qr_url que devuelve la emisión.

10 Anular un documento

POST {BASE_URL}/api/v1/documentos/{cdc}/anular
// Header: Authorization: Bearer <TOKEN>
{ "motivo": "Error en los datos del cliente" }

POST {BASE_URL}/api-py/anular.php
{ "id": 1, "cdc": "0104...", "motivo": "Error en los datos del cliente" }

{ "success": true, "estado_sifen": "Aprobado", "codigo_sifen": "0600",
  "mensaje_sifen": "Evento registrado con exito", "respuesta_sifen": { /* ... */ } }

Reglas SIFEN: el motivo debe tener entre 5 y 500 caracteres; la anulación se acepta dentro de las 48 horas de la emisión.

10.1 Reenviar (reintentar el envío de un documento ya firmado)

Se usa cuando el documento ya tiene cdc (quedó firmado) pero el envío a SIFEN falló o quedó en un estado no final — por ejemplo recibiste un 502, o el estado_sifen quedó en Rechazado/ERROR por un problema de red (no por un rechazo de negocio de SIFEN). Reenviar no genera un CDC nuevo ni cambia el número: reutiliza el XML ya firmado tal cual.

POST {BASE_URL}/api/v1/documentos/{cdc}/reenviar
// Header: Authorization: Bearer <TOKEN>
// (sin body)

Respuesta: mismo formato que POST /api/v1/documentos (success, cdc, estado, estado_sifen, nro_lote, qr_url, links, documento). 200 si SIFEN aceptó el lote, 502 si volvió a fallar (el documento sigue firmado; se puede reintentar más tarde o forzar una consulta).

Si el documento ya está aprobado o anulado el reenvío no aplica → 422 { "message": "El documento ya esta aprobado; no se puede reenviar." }

Diferencia con la Idempotencia: la cabecera Idempotency-Key es para cuando el POST /api/v1/documentos ORIGINAL no responde (timeout de red) — ahí todavía no sabés si la API llegó a procesar el JSON, así que reintentás el mismo POST con el mismo número. /reenviar es para cuando ya tenés confirmado el cdc (el documento SÍ se creó y firmó) pero el envío de ESE documento a SIFEN falló: no hace falta mandar el JSON de nuevo, solo el CDC en la URL.

API legacy: no tiene endpoint de reenvío. Usá el panel de administración (botón "Reenviar" en el detalle del documento) o el reintento con Idempotency-Key.

11 Manejo de errores en el sistema emisor

1. Guardá siempre el cdc que devuelve la API, aunque estado_sifen sea Rechazado o ERROR: ese CDC ya quedó asignado a ese número y no se puede reutilizar.
2. Si no hay respuesta (timeout): no generes número nuevo. Reintentá el mismo JSON con la misma Idempotency-Key.
3. Si estado_sifen = "Rechazado": leé mensaje_sifen y codigo_sifen, corregí y emití un comprobante nuevo con número nuevo (un DE rechazado no se corrige, se reemplaza).
4. Si estado_sifen = "Pendiente": es lo normal. Entregá el comprobante / imprimí el KUDE. Consultá el estado final más tarde.
5. 429: esperá y reintentá.
6. 502: el CDC ya existe. Guardalo. La API reintenta el envío sola cada 10 minutos (hasta 5 intentos); si no querés esperar, forzá el reenvío ya mismo con POST .../reenviar, o consultá el estado con POST .../consultar.

12 Código de ejemplo

Reemplazá {BASE_URL} y <TOKEN>.

curl -X POST {BASE_URL}/api/v1/documentos \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <TOKEN>" \
     -H "Idempotency-Key: FE-001-001-0000001" \
     --data-binary "@factura.json"
# En Windows (cmd): cambiar \ por ^

$base  = getenv('SIFEN_API_URL');   // https://facturacion.miempresa.com
$token = getenv('SIFEN_API_TOKEN');
$json  = json_encode($factura, JSON_UNESCAPED_UNICODE);

$ch = curl_init(rtrim($base, '/') . '/api/v1/documentos');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => $json,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT        => 90,
  CURLOPT_HTTPHEADER     => [
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer ' . $token,
    'Idempotency-Key: FE-' . $est . '-' . $punto . '-' . $numero,
  ],
]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$resp = json_decode($body, true);
if (!empty($resp['cdc'])) {
  // guardar $resp['cdc'] y $resp['nro_lote'] en el ERP
}

var baseUrl = Environment.GetEnvironmentVariable("SIFEN_API_URL")!.TrimEnd('/');
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(90) };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);
http.DefaultRequestHeaders.Add("Idempotency-Key", $"FE-{est}-{pto}-{nro}");
var content = new StringContent(
    JsonSerializer.Serialize(factura), Encoding.UTF8, "application/json");
var resp = await http.PostAsync($"{baseUrl}/api/v1/documentos", content);
var body = await resp.Content.ReadAsStringAsync();

import os, json, requests
base = os.environ["SIFEN_API_URL"].rstrip("/")
r = requests.post(
    f"{base}/api/v1/documentos",
    headers={"Authorization": f"Bearer {token}",
             "Content-Type": "application/json",
             "Idempotency-Key": f"FE-{est}-{pto}-{nro}"},
    data=json.dumps(factura, ensure_ascii=False).encode("utf-8"),
    timeout=90)
print(r.status_code, r.json())

// El sistema actual sigue funcionando: solo cambia el host.
Http.Request.ContentType := 'application/json';
Http.Request.CharSet     := 'utf-8';
Http.ConnectTimeout := 15000;
Http.ReadTimeout    := 90000;
Body := TStringStream.Create(JsonFactura, TEncoding.UTF8);
Resp := Http.Post(BaseUrl + '/api-py/firmar-enviar.php', Body);
// Resp trae: cdc, nro_lote, estado_sifen, mensaje_sifen
// BaseUrl es una CONSTANTE de configuración: cambiar solo eso al migrar.
// La ruta /api-py/firmar-enviar.php y el formato de la respuesta NO cambian.

13 Tablas de códigos SIFEN

Los textos van tal cual; respetar tildes.

Autofactura Electrónica — tipoDocumento 4

Nota de Remisión Electrónica — tipoDocumento 7

Códigos de respuesta SIFEN más comunes

14 Checklist de integración

• Tengo el {BASE_URL} y un token (API nueva) o mi IP está permitida (legacy).
• El {BASE_URL} es una constante de configuración en mi sistema (puede cambiar sin recompilar).
• Envío recordID en cada request.
• establecimiento / punto / numero con 3 / 3 / 7 dígitos y ceros a la izquierda.
• No repito números; uso Idempotency-Key.
• fecha en YYYY-MM-DDTHH:MM:SS, hora de Paraguay.
• Importes como número JSON (sin separador de miles, punto decimal).
• Calculo basGravIVA y liqIVAItem por ítem (fórmula N5).
• Mando el bloque totales con los 8 campos del emisor (0 si no hay).
• Si contado: la suma de pagos = total del comprobante.
• Guardo el cdc y el nro_lote de la respuesta siempre.
• Manejo 201 / 200 / 409 / 422 / 403 / 502 / 429 (o, en legacy, leo el cuerpo).
• Imprimo el KUDE desde la API (no reconstruyo el QR).
• Probé en ambiente test antes de producción.
• Si emito Autofactura (4): cliente = mi propio emisor + bloque vendedor.
• Si emito Nota de Remisión (7): bloques remision y transporte; ítems sin precio/IVA; sin factura/condicion/totales.
• Autofactura (4) / Nota de Remisión (7): el proveedor las habilitó para mi empresa.

15 Si tu proveedor activó el modo multiempresa (SaaS)

Todo lo de arriba sigue igual (URLs, JSON, Idempotency-Key, capa legacy). Lo que cambia:

Códigos de error nuevos

Mismo formato de siempre, con un campo codigo además de error:

Cabeceras nuevas en la emisión

X-Empresa-Slug, X-Cupo-Usado, X-Cupo-Limite, X-Suscripcion-Vence.

Endpoint nuevo

GET {BASE_URL}/api/v1/cuenta (solo lectura, no consume cupo) → { empresa, ruc, estado, plan, modulos[], vence_at, ambiente, produccion_habilitada }.

{
  "success": false,
  "error": "El modulo 'api_rest' no esta contratado.",
  "codigo": "MODULO_NO_CONTRATADO"
}

Guía completa para integraciones nuevas contra el SaaS: MANUAL_FOR_SAAS.md (en el repositorio de la API).