Facturación electrónica (SIFEN) por API — guía para sistemas externos

Para empresas que ya tienen su propio sistema (ERP, facturador, e-commerce, software a medida) y solo necesitan emitir factura electrónica en Paraguay. Su sistema sigue gestionando ventas, stock y cobros; CDEpos se encarga de la parte fiscal: numera con el timbrado electrónico, firma con el certificado del contribuyente, envía al SET (SIFEN), devuelve el CDC + QR + KuDE (PDF) + XML, consulta la aprobación, anula, emite notas de crédito y envía el comprobante al cliente por email.

Base URL: https://app.micdepos.com/connector/api · Formato: JSON · Auth: OAuth2 (Bearer). Documentación general de la API: https://app.micdepos.com/doc.

1. Cómo funciona (resumen)

Su sistema                                CDEpos                                  SET / SIFEN
──────────                                ──────                                  ───────────
POST /sell  {cliente, ítems, pago,        crea la venta, numera (timbrado
            sifen_emit: true}      ───►   electrónico), arma el XML del DE,
                                          lo firma y lo envía por lote    ───►    recibe el lote (0300)
            ◄─── 200 {id, invoice_no,
                     sifen: {cdc, qr}}
                                          cron cada 10 min consulta el lote ───►  aprobado / rechazado
◄── webhook sifen.aprobado (POST firmado a su URL)   o   GET /sell/{id}/sifen/status
GET /sell/{id}/pdf           ───►         KuDE (PDF) / XML / email al cliente

• Una sola llamada crea la factura y la emite (sifen_emit: true).
• La aprobación del SET es asíncrona: normalmente en minutos. CDEpos le avisa por webhook (§5.1) o se consulta con GET /sell/{id}/sifen/status. El KuDE es válido desde que tiene CDC; el QR apunta a ekuatia.set.gov.py.
• No hace falta cargar productos ni clientes por adelantado: la venta puede traer el cliente por RUC/CI y los ítems por SKU, y CDEpos los crea la primera vez (ver §4).
• La numeración (001-001-0000123) la asigna CDEpos según el timbrado electrónico: guarde id, invoice_no y cdc en su sistema.

2. Requisitos previos (una sola vez)

Lo configura CDEpos junto con el contribuyente:

1. Negocio en CDEpos con el módulo de factura electrónica activo (sifen_active en el negocio y en la sucursal emisora).
2. Certificado digital (.p12 del contribuyente, emitido por una PSC habilitada) cargado en la sucursal, con su contraseña.
3. Timbrado electrónico vigente (esquema de numeración electrónico con timbrado, fecha de inicio/fin, establecimiento y punto de expedición) asignado a la sucursal.
4. Ambiente: test para homologar, produccion cuando el SET habilita al contribuyente. (En demo el XML se firma localmente y no se envía.)
5. Tasas de IVA del negocio: IVA 10%, IVA 5% y Exenta (vienen por defecto).
6. Usuario API con permisos: sell.create, customer.view, customer.create (alta de clientes), product.create (alta automática de ítems por SKU), invoice.view_pdf (emitir / KuDE / XML), sell.view.
7. Credenciales OAuth (Client ID, Client Secret, usuario y contraseña API): las genera el administrador del negocio en CDEpos → Conector / Clientes API. El secret se muestra una sola vez.

3. Autenticación

curl -X POST https://app.micdepos.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "password",
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "username": "<USUARIO_API>",
    "password": "<PASSWORD_API>",
    "scope": "*"
  }'

Respuesta: {"token_type":"Bearer","expires_in":...,"access_token":"...","refresh_token":"..."}. Enviar en cada llamada Authorization: Bearer <access_token> y Accept: application/json. Renovar con grant_type: refresh_token antes de que venza.

4. Emitir una factura electrónica (una llamada)

POST /connector/api/sell — el cuerpo es un arreglo sells (normalmente con una venta).

{
  "sells": [
    {
      "location_id": 1,
      "status": "final",
      "idempotency_key": "ERP-FAC-2026-000123",
      "sifen_emit": true,
      "transaction_date": "2026-08-19 10:30:00",
      "contact": {
        "ruc": "80012345-6",
        "name": "Distribuidora Ejemplo SA",
        "email": "[email protected]",
        "mobile": "0981123456",
        "address": "Av. Monseñor Rodríguez 123, Ciudad del Este"
      },
      "products": [
        { "sku": "SRV-MANT-01", "name": "Servicio de mantenimiento", "quantity": 1,
          "unit_price_inc_tax": 550000, "tax_rate": 10 },
        { "sku": "LIB-0001", "name": "Libro técnico", "quantity": 2,
          "unit_price_inc_tax": 120000, "tax_rate": 5 },
        { "sku": "EXE-0001", "name": "Ítem exento", "quantity": 1,
          "unit_price_inc_tax": 30000, "tax_rate": 0 }
      ],
      "payments": [
        { "method": "cash", "amount": 820000 }
      ],
      "sale_note": "Pedido ERP #98765"
    }
  ]
}

Campos clave

Cabecera Idempotency-Key. Desde el 15/10/2026, si el cuerpo no trae idempotency_key y el pedido trae una sola venta, la cabecera Idempotency-Key también se guarda con la venta como su clave. Deduplica de forma persistente, por comercio, y no vence. Antes la cabecera sólo deduplicaba 24 h y se perdía en cada actualización del servidor. Si manda las dos, manda la del cuerpo.

• Una cabecera de más de 64 caracteres no se guarda con la venta: sólo deduplica 24 h, como antes.
• No reutilice una clave para otra venta:
  • dentro de las 24 h, con otro cuerpo, recibe 422 ("Idempotency-Key reutilizado con body distinto");
  • después, si la clave vino de la cabecera, CDEpos compara sucursal, cliente (si lo manda) y cantidad de productos con la venta guardada. Si no coinciden, 422 CLAVE_YA_USADA y la venta no se crea. Si coinciden, la toma como un reintento y devuelve la venta guardada con duplicate: true.

contact — cliente por documento

Para validar un RUC contra el SET antes de facturar: GET /connector/api/contactapi-lookup?doc=80012345-6.

products[] — ítems

Respuesta (200)

[
  {
    "id": 614885,
    "invoice_no": "001-001-0000123",
    "transaction_date": "2026-08-19 10:30:00",
    "final_total": "820000.0000",
    "payment_status": "paid",
    "contact_id": 8415,
    "sifen_cdc": "01023665700001001000001212026081910119614641",
    "sifen_qr": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=0102366570...",
    "sifen_process": "lote_recibido",
    "sifen": {
      "emitted": true,
      "cdc": "01023665700001001000001212026081910119614641",
      "qr": "https://ekuatia.set.gov.py/consultas/qr?...",
      "process": "lote_recibido",
      "links": {
        "status": "https://app.micdepos.com/connector/api/sell/614885/sifen/status",
        "pdf":    "https://app.micdepos.com/connector/api/sell/614885/pdf",
        "xml":    "https://app.micdepos.com/connector/api/sell/614885/sifen/xml"
      }
    },
    "invoice_url": "https://app.micdepos.com/invoice/…"
  }
]

• Si la emisión falla, la venta igual queda creada y sifen.emitted = false con sifen.error.code / message (ver §8). Se reintenta con POST /sell/{id}/sifen/emit sin volver a crear la venta.
• Reintento con la misma idempotency_key → misma venta, duplicate: true, mismo CDC. En la respuesta repetida sólo se garantizan id, invoice_no, invoice_url y payment_link (iguales a la primera); para el estado SIFEN consulte GET /sell/{id}/sifen/status.
• Si el reintento llega mientras la primera todavía se está guardando, espera hasta 10 s; si sigue en curso recibe 503 OPERACION_EN_CURSO (ver §8).

5. Consultar el estado SIFEN

GET /connector/api/sell/{id}/sifen/status

{ "data": {
    "transaction_id": 614885,
    "invoice_no": "001-001-0000123",
    "sifen_cdc": "0102…",
    "sifen_process": "aprobado_set",
    "ambiente": "produccion",
    "ultimo_envio": { "estado": "APROBADO", "cod_res_envio": "0260",
                      "msg_res_envio": "Autorización del DE satisfactoria", "intentos": 1 },
    "qr_url_set": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=0102…",
    "email": { "state": "sent" }
} }

Sugerencia: consultar cada 1–2 minutos hasta estado final (el proceso interno revisa los lotes cada 10 minutos). Una factura con CDC ya puede imprimirse y entregarse; el SET la valida en ese lapso. Mejor aún: suscribir un webhook (§5.1) y no consultar.

5.1 Webhooks (recomendado): CDEpos le avisa a su sistema

En vez de consultar el estado, registre una URL y CDEpos le hace un POST cuando el documento cambia de estado:

Registrar (usuario administrador del negocio o con business_settings.access):

curl -X POST https://app.micdepos.com/connector/api/sifen/webhooks \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{ "url": "https://mi-erp.com/webhooks/cdepos", "events": ["sifen.aprobado","sifen.rechazado","sifen.error","sifen.anulado"], "description": "ERP producción" }'

Respuesta: {"data": {"id": 1, "url": "...", "secret": "whsec_…"}} — guarde el secret: se muestra una sola vez (se puede rotar con PUT /sifen/webhooks/{id} { "rotate_secret": true }). Máximo 5 webhooks por negocio; la URL debe ser https pública.

Lo que recibe su endpoint (POST, Content-Type: application/json):

X-CDEpos-Event: sifen.aprobado
X-CDEpos-Delivery: 3f0c…-uuid            (id único de la entrega; úselo para no procesar dos veces)
X-CDEpos-Timestamp: 1755610000
X-CDEpos-Signature: sha256=<HMAC-SHA256 del cuerpo crudo con el secret>
User-Agent: CDEpos-Webhooks/1.0

{
  "id": "3f0c…", "event": "sifen.aprobado", "created_at": "2026-08-19T10:42:00-03:00",
  "business_id": 12,
  "data": {
    "transaction_id": 614885, "type": "sell",
    "invoice_no": "001-001-0000123", "idempotency_key": "ERP-FAC-2026-000123",
    "transaction_date": "2026-08-19 10:30:00", "final_total": 820000, "payment_status": "paid",
    "cdc": "0102366570…", "qr": "https://ekuatia.set.gov.py/consultas/qr?…", "sifen_process": "aprobado_set",
    "contact": { "id": 8415, "name": "Distribuidora Ejemplo SA", "tax_number": "80012345-6" },
    "ultimo_envio": { "tipo": "ASYNC", "estado": "APROBADO", "cod_res_envio": "0260", "msg_res_envio": "Autorización del DE satisfactoria" },
    "links": { "status": "…/sell/614885/sifen/status", "pdf": "…/sell/614885/pdf", "xml": "…/sell/614885/sifen/xml" }
  }
}

type = sell (factura) o sell_return (nota de crédito). idempotency_key es la clave que usted mandó al crear la venta: con eso enlaza el aviso con su registro sin guardar ids ajenos.

Verificar la firma (obligatorio): calcule HMAC-SHA256(secret, cuerpo crudo) y compárelo con X-CDEpos-Signature (sin sha256=). Ejemplo PHP:

$raw = file_get_contents('php://input');
$ok  = hash_equals('sha256='.hash_hmac('sha256', $raw, $SECRET), $_SERVER['HTTP_X_CDEPOS_SIGNATURE'] ?? '');

Responder 2xx rápido (< 8 s). Cualquier otra respuesta o timeout se reintenta con espera creciente: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h (6 intentos). Un mismo evento de una misma factura se entrega una sola vez por webhook, pero diseñe su receptor idempotente por X-CDEpos-Delivery.

Gestión: GET /sifen/webhooks · PUT /sifen/webhooks/{id} (url, events, is_active, rotate_secret) · DELETE /sifen/webhooks/{id} · POST /sifen/webhooks/{id}/test (ping) · GET /sifen/webhooks/{id}/deliveries (historial con estado, intentos y último error) · POST /sifen/webhooks/{id}/deliveries/{deliveryId}/retry.

5.2 Reconciliación

Para cruzar su sistema con CDEpos (cierre del día, reproceso tras una caída):

• GET /connector/api/sell?idempotency_key=ERP-FAC-2026-000123 → la venta que corresponde a su clave (devuelve id, invoice_no, sifen_cdc, sifen_process, líneas y pagos).
• GET /connector/api/sell?sifen_process=rechazado_set,error_envio&start_date=2026-08-01&end_date=2026-08-31 → documentos con problemas en el período. También sifen_cdc= e invoice_no=.
• Todas las ventas devuelven idempotency_key, sifen_cdc, sifen_qr y sifen_process en su JSON.

6. Documentos

El negocio también puede activar el email automático al aprobarse el DE (sin llamadas de su parte).

7. Anulación y notas de crédito

• Anular (evento de cancelación): POST /connector/api/sell/{id}/sifen/cancel { "motivo": "Error en los datos del cliente" } (mínimo 10 caracteres). Reglas del SET: dentro de las 48 h de la aprobación; después corresponde nota de crédito.
• Nota de crédito electrónica (devolución total/parcial): POST /connector/api/sell-return

  { "transaction_id": 614885,
    "products": [ { "sell_line_id": 990001, "quantity": 1, "unit_price_inc_tax": 550000 } ],
    "sifen_motivo_nc_nd": 1 }
  

  Los sell_line_id salen de GET /sell/{id}. La NC se emite asociada al CDC de la factura y se consulta igual que una venta. Motivos: GET /sifen-catalogs/motivos-nc.

8. Errores

9. Buenas prácticas

1. Usar siempre idempotency_key (el número interno de su factura/pedido) y reintentar con la misma ante timeouts.
2. Guardar id, invoice_no, sifen_cdc y sifen_qr en su sistema; mostrar el QR / link qr_url_set en sus comprobantes.
3. Enviar el RUC con dígito verificador y el nombre como figura en el SET (contactapi-lookup lo consulta); para consumidor final usar sin_nombre.
4. Mandar precios con IVA (unit_price_inc_tax) y la tasa (tax_rate): así el DE refleja exactamente lo que cobró.
5. Homologar primero en ambiente test (mismos endpoints, la sucursal en sifen_ambiente = test), luego pasar a producción.
6. Suscribir un webhook (§5.1) para enterarse de aprobado_set / rechazado_set sin consultar; atender los rechazos el mismo día. Si no puede exponer una URL, consulte el estado hasta el final.
7. No borrar facturas: si hubo error, anular (≤ 48 h) o nota de crédito.

10. Checklist de salida a producción

• Certificado de producción cargado en la sucursal y contraseña válida.
• Timbrado electrónico vigente con establecimiento/punto de expedición correctos.
• sifen_ambiente = produccion en la sucursal; sifen_active en negocio y sucursal.
• Usuario API con los permisos del §2 y credenciales OAuth entregadas.
• Prueba real: 1 factura contado + 1 crédito + 1 nota de crédito → aprobado_set.
• KuDE descargado por GET /sell/{id}/pdf y QR verificado en ekuatia.set.gov.py.
• Email automático al cliente activado (opcional).

Referencia rápida de endpoints

CDEpos — CDE Online · Ciudad del Este, Paraguay · soporte: [email protected]