Facturar con tu propia facturadora (en vez de FacturaMax)

MaxTiendas factura con FacturaMax de fábrica. Si tu empresa ya trabaja con otra facturadora electrónica, podés usarla en su lugar: el módulo de Facturación del panel funciona igual (facturar pedidos y ventas del POS, notas de crédito y débito, notas de remisión, recibos, el KuDE en PDF), sólo que los documentos los emite tu facturadora.

Cómo se conecta

¿Puedo usar las dos cosas?

Sí, y se pueden combinar como te sirva:

• Facturar desde la tienda y que tu sistema use la tienda (pasos 3 y 4, la misma facturadora): una factura que emitís desde la tienda queda en la tienda una sola vez, aunque después tu facturadora también la registre como venta. No se duplica el pedido ni se descuenta el stock dos veces.
• FacturaMax para la tienda y otro sistema en tu local (por ejemplo, el de la caja): dejá elegido FacturaMax y, en la misma pantalla, abrí «¿Además tenés otro sistema que factura en tu local?» para crearle su llave. Las ventas de cada uno quedan separadas.

Lo que no se puede es emitir desde la tienda con dos facturadoras a la vez: la tienda factura con una sola, la que elegís arriba.

Guía técnica (para el soporte de la facturadora)

1. Transporte

URL base

Ustedes definen la URL base, por ejemplo https://api.sufacturadora.com/maxtiendas/v1. Todas las rutas de esta guía van debajo de ella: GET <base>/me, POST <base>/sifen/de, etc.

Autenticación

Cada llamada trae:

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json        (en POST)
X-Client-Origin: <dominio de la tienda>

• El token identifica a la empresa (al emisor). MaxTiendas no manda ningún otro identificador.
• Un token por comercio. Lo genera el comercio en su cuenta de su sistema (o ustedes, como lo resuelvan), y él mismo lo carga en MaxTiendas.
• X-Client-Origin viene siempre; pueden usarlo para restringir desde dónde se usa el token.

Tiempos y reintentos

• Las llamadas JSON esperan 30 segundos; las descargas (PDF, XML), 60.
• Los GET se reintentan una vez si falla la conexión (no si responden con error).
• Los POST nunca se reintentan, para no emitir dos veces.

Errores

Respondan con el código HTTP correcto y un cuerpo JSON:

{ "message": "El RUC del receptor no es válido.", "errors": { "receptor.ruc": ["Formato inválido."] } }

Código	Cuándo	Qué hace MaxTiendas
401 / 403	Token inválido o sin permiso	Muestra el mensaje y pide revisar el token.
404	No existe	Muestra el mensaje.
409	Conflicto (ej. timbrado vencido)	Muestra el mensaje.
422	Validación	Muestra message y los errors por campo en el formulario.
429	Demasiadas llamadas	Muestra el mensaje.
5xx	Error interno	”La facturadora respondió con un error”.

También se acepta {"error": "..."} o {"messages": ["...", "..."]} en lugar de message.

Formas de respuesta (atención)

No todas las rutas se leen igual. Respeten la forma de cada una:

Ruta	Forma
POST /sifen/de y GET /sifen/de/{id}	Objeto plano, sin envolver: {"id":120,"cdc":"…",…}
GET /sifen/de	{"data":[…],"meta":{"current_page":1,"last_page":3,"per_page":20,"total":55}}
GET /sifen/recibos	Paginador plano: {"data":[…],"current_page":1,"last_page":3,"per_page":25,"total":55,"from":1,"to":25}
Listas (timbrados, clientes/search, catálogos)	{"data":[…]}
Lo demás	Plano o {"data":{…}}, los dos sirven

Los importes pueden venir como número o como texto ("150000.00").

---

2. Qué implementar

Nivel	Rutas	Sin esto…
Obligatorio	GET /me · GET /sifen/timbrados · POST /sifen/de · GET /sifen/de · GET /sifen/de/{id} · GET /sifen/de/{id}/pdf · POST /sifen/de/{id}/cancel · catálogo geográfico	no se puede facturar
Recomendado	GET /sifen/de/{id}/xml · POST /sifen/de/{id}/resend · POST /sifen/de/{id}/email · GET /sifen/emisor · GET /sifen/ruc/{ruc} · GET /sifen/clientes/search · catálogos SIFEN	faltan botones o autocompletados (el resto anda)
Recibos	todo /sifen/recibos*	el comercio no puede emitir recibos de dinero desde MaxTiendas

No implementen /integraciones/maxtiendas/*: es exclusivo de FacturaMax. Para que su sistema le avise a la tienda las ventas que factura por su cuenta (en el local, sin pedido en la tienda), usen la API inversa: https://docs.maxtiendas.app/guias/conectar-tu-sistema-de-facturacion

---

3. Conexión

Lo usa el botón “Probar conexión”. Un 2xx = conectado.

{ "tenant": { "razon_social": "Mi Empresa SA", "ruc": "80012345-6", "ambiente": "test", "slug": "mi-empresa" } }

• ambiente: "test" o "prod". Con "test" el panel avisa que las facturas no tienen validez fiscal.

{ "razon_social": "Mi Empresa SA", "ruc": "80012345-6", "direccion": "Av. España", "numero_casa": "1234",
  "departamento_codigo": 1, "distrito_codigo": 1, "ciudad_codigo": 1 }

La dirección se usa como punto de salida por defecto en las notas de remisión.

{ "data": [
  { "id": 3, "numero": "12345678", "establecimiento": "001", "punto_expedicion": "002",
    "activo": true, "vigente": true, "tipo_de": 1, "fecha_inicio": "2026-01-01", "fecha_fin": null }
] }

• id es el que MaxTiendas manda después como timbrado_id al emitir.
• Manden activo y vigente: se leen los dos.
• MaxTiendas permite asignar timbrados a cada usuario de la tienda (el cajero de una sucursal sólo factura con su punto).

---

4. Catálogos

Geográfico · obligatorio

Para la dirección del receptor y los puntos de la remisión. Códigos de la SET.

• GET /catalogos/departamentos
• GET /catalogos/departamentos/{codigo}/distritos
• GET /catalogos/distritos/{codigo}/ciudades

{ "data": [ { "codigo": 1, "descripcion": "CAPITAL" } ] }

SIFEN · recomendado

GET /catalogos/tipos-transaccion · /tipos-pago · /condiciones-operacion · /monedas · /unidades-medida · /tipos-documento-identidad

{ "data": [ { "codigo": 1, "descripcion": "Venta de mercadería" } ] }

Si no existen, MaxTiendas usa su propia lista.

---

5. Receptor

El buscador del receptor. MaxTiendas lo mezcla con sus propios clientes.

{ "data": [ { "id": 17, "nombre": "Juan Pérez", "ruc": "1234567-8", "naturaleza": 1, "tipo_documento": null,
              "numero_documento": null, "direccion": "Asunción", "email": "j@x.com", "telefono": "0981111222" } ] }

El botón “Buscar RUC” (autocompleta el nombre).

{ "data": { "ruc": "80012345-6", "razon_social": "Empresa SA", "nombre": "Empresa SA" } }

---

6. Emitir

Una sola ruta para los cuatro documentos. Se llama una sola vez por emisión, sin reintentos.

Campos comunes

Campo	Tipo	Qué es
tipo_de	int	1 Factura · 5 Nota de crédito · 6 Nota de débito · 7 Nota de remisión
fecha_emision	string	Hora local del servidor, 2026-10-01T14:03:22 (sin zona horaria)
timbrado_id	int, opcional	El id de /sifen/timbrados. Si no viene, elijan ustedes el vigente.
moneda	string	PYG, USD…
tipo_cambio	number, opcional
info_adicional	string, opcional	Ej. "Pedido ABC123" (máx. 5000)
receptor	objeto	Ver abajo
items	array (1 a 999)	Ver abajo

Los campos vacíos no se mandan (no esperen null).

receptor

Campo	Qué es
nombre	Razón social o nombre
naturaleza	1 contribuyente · 2 no contribuyente
ruc	Con dígito verificador (80012345-6). Viene si naturaleza = 1
tipo_documento, numero_documento	Sólo si naturaleza = 2. 1 cédula paraguaya · 5 innominado
tipo_operacion	1 B2B · 2 B2C · 3 B2G · 4 B2F
direccion, numero_casa	Opcionales
telefono (6–15), celular (10–20), email	Opcionales
codigo_cliente	MT-<id> si es un cliente de la tienda (SIFEN D206)
departamento_codigo, departamento, distrito_codigo, distrito, ciudad_codigo, ciudad	Sólo si se cargó la ciudad

items[]

Campo	Qué es
codigo	Código del producto (opcional)
descripcion	Obligatorio
cantidad	> 0
precio_unitario	IVA incluido
iva_tasa	0, 5 o 10
iva_tipo	1 gravado · 3 exento (cuando iva_tasa = 0)
unidad_medida	Código SIFEN (77 = Unidad)
descuento	Importe de descuento de la línea (puede venir 0)

Sólo factura (tipo_de = 1)

Campo	Qué es
condicion_operacion	1 contado · 2 crédito
tipo_transaccion	SIFEN D011 (1 a 13)
tipo_pago	Uno: 1 efectivo · 2 cheque · 3 tarjeta de crédito · 4 tarjeta de débito · 5 transferencia · 9 anticipo
orden_venta	Opcional (máx. 15)
credito	Si es a crédito: {"condicion":1,"plazo":"30 días"} o {"condicion":2,"cuotas":3}

Sólo notas de crédito y débito (tipo_de = 5 o 6)

Campo	Qué es
motivo_emision	SIFEN E401: 1 devolución y ajuste de precios · 2 devolución · 3 descuento · 4 bonificación · 5 crédito incobrable · 6 recupero de costo · 7 recupero de gasto · 8 ajuste de precio
documentos_asociados	Un elemento. Factura electrónica: {"tipo":1,"cdc":"<44 dígitos>"}. Factura de papel: {"tipo":2,"timbrado":"12345678","establecimiento":"001","punto_expedicion":"001","numero":"0000123","tipo_documento_impreso":1,"fecha":"2026-09-01"}

Antes de una nota sobre una factura electrónica, MaxTiendas consulta GET /sifen/de/{id} y exige tipo_de = 1, estado = APPROVED y cdc.

Sólo nota de remisión (tipo_de = 7)

Campo	Qué es
motivo_remision	1 venta · 2 consignación · 3 exportación · 4 compra · 5 importación · 6 devolución · 7 traslado entre locales · 8 transformación · 9 reparación · 10 emisor móvil · 11 exhibición · 12 ferias · 13 encomienda · 14 decomiso · 99 otro
responsable_remision	1 emisor · 2 poseedor · 3 transportista · 4 despachante · 5 agente
km_recorridos	Opcional
fecha_futura_factura	Opcional, si se factura después
documentos_asociados	[{"tipo":1,"cdc":"…"}] si el pedido ya tiene factura
transporte	Ver abajo

Los ítems de la remisión traen precio e IVA igual; no los pongan en el XML de la remisión.

transporte:

{
  "tipo": 1, "modalidad": 1, "responsable_flete": 1,
  "fecha_inicio": "2026-10-01", "fecha_fin": "2026-10-02",
  "salida":   { "direccion": "Av. España", "numero_casa": "1234", "departamento_codigo": 1, "distrito_codigo": 1, "ciudad_codigo": 1 },
  "entregas": [ { "direccion": "Ruta 2 km 20", "numero_casa": "0", "departamento_codigo": 11, "distrito_codigo": 150, "ciudad_codigo": 3200 } ],
  "vehiculos": [ { "tipo": "Camioneta", "marca": "Toyota", "tipo_identificacion": 2, "matricula": "ABC123" } ],
  "transportista": { "naturaleza": 2, "nombre": "Pedro Gómez", "tipo_documento": 1, "numero_documento": "1234567",
                     "domicilio_fiscal": "Asunción", "chofer_documento": "1234567", "chofer_nombre": "Pedro Gómez", "chofer_direccion": "Asunción" }
}

• tipo: 1 propio · 2 terceros. modalidad: 1 terrestre · 2 fluvial · 3 aéreo · 4 multimodal.
• responsable_flete: 1 emisor · 2 receptor · 3 tercero · 4 agente · 5 propio.
• Vehículo: tipo_identificacion 1 chasis (viene numero_identificacion) · 2 matrícula (viene matricula).
• Transportista: con naturaleza 1 viene ruc; con 2, tipo_documento (1 CI · 2 pasaporte · 3 cédula extranjera · 4 carnet de residencia) y numero_documento.

Ejemplo: factura a crédito

{
  "tipo_de": 1, "fecha_emision": "2026-10-01T14:03:22", "timbrado_id": 3, "moneda": "PYG",
  "condicion_operacion": 2, "tipo_transaccion": 1, "tipo_pago": 5,
  "info_adicional": "Pedido ABC123", "orden_venta": "ABC123",
  "credito": { "condicion": 1, "plazo": "30 días" },
  "receptor": { "nombre": "Empresa SA", "naturaleza": 1, "ruc": "80012345-6", "tipo_operacion": 1,
                "email": "a@b.com", "codigo_cliente": "MT-42" },
  "items": [
    { "codigo": "SKU-1", "descripcion": "Remera - Talle M", "cantidad": 2, "precio_unitario": 150000,
      "iva_tasa": 10, "iva_tipo": 1, "unidad_medida": 77, "descuento": 10000 },
    { "descripcion": "Envío - AEX", "cantidad": 1, "precio_unitario": 25000,
      "iva_tasa": 10, "iva_tipo": 1, "unidad_medida": 77, "descuento": 0 }
  ]
}

Respuesta · plana

{ "id": 120, "cdc": "01800123456001001000012312026100112345678901", "numero": "001-001-0000123",
  "estado": "PENDING", "total": 315000 }

• id es su identificador del documento. MaxTiendas lo guarda y lo usa en todas las rutas /sifen/de/{id}.
• Sin envolver en data: si viene {"data":{…}}, la tienda no encuentra el id.
• El cdc puede llegar vacío si todavía no lo generaron; se completa después con GET /sifen/de/{id}.

---

7. Estados del documento

estado	Qué significa	MaxTiendas…
DRAFT	Borrador	—
PENDING	Emitido, esperando a la SET	consulta el detalle cada tanto
PROCESSING	Enviado, en proceso	consulta el detalle cada tanto
APPROVED	Aprobado	permite anular y hacer notas
REJECTED	Rechazado	permite reenviar; el pago se puede volver a facturar
ERROR	Falló el envío	permite reenviar; el pago se puede volver a facturar
CANCELLED	Anulado	el pago se puede volver a facturar

Manden también estado_label con el texto en castellano (“Aprobado”); si no viene, se muestra estado.

Correo: MaxTiendas no pide el envío del KuDE al emitir. Espera que ustedes lo manden solos al receptor cuando el documento queda APPROVED, si tiene correo.

---

8. Listar y ver

Parámetros (los vacíos no se mandan): page, per_page (20, máx. 100), q, estado, tipo_de, fecha_desde, fecha_hasta, receptor_ruc, sort (por defecto created_at), order (asc/desc).

{
  "data": [ { "id": 120, "cdc": "0180…", "tipo_de": 1, "estado": "APPROVED", "estado_label": "Aprobado",
              "numero": "001-001-0000123", "fecha_emision": "2026-10-01T14:03:22", "receptor_ruc": "80012345-6",
              "receptor_nombre": "Empresa SA", "moneda": "PYG", "total": "315000.00",
              "sifen_codigo_respuesta": "0260", "created_at": "2026-10-01T14:03:23" } ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 20, "total": 55 }
}

{
  "id": 120, "cdc": "0180…", "tipo_de": 1, "estado": "APPROVED", "estado_label": "Aprobado",
  "numero": "001-001-0000123", "fecha_emision": "2026-10-01T14:03:22", "ambiente": "prod",
  "receptor": { "ruc": "80012345-6", "nombre": "Empresa SA", "tipo_documento": null, "numero_documento": null,
                "naturaleza": 1, "tipo_operacion": 1, "direccion": "Av. España", "telefono": "021555111", "email": "a@b.com" },
  "condicion_operacion": 1, "tipo_pago": 5, "moneda": "PYG", "tipo_cambio": null,
  "total": 315000, "total_iva": 28636,
  "items": [ { "codigo": "SKU-1", "descripcion": "Remera - Talle M", "cantidad": 2, "precio_unitario": 150000,
               "iva_tasa": 10, "subtotal": 290000, "unidad_medida": 77, "descuento": 10000 } ],
  "eventos": [ { "id": 1, "tipo_evento": "cancelacion", "motivo": "…", "estado": "APPROVED",
                 "sifen_codigo": "0600", "sifen_mensaje": "…", "created_at": "…" } ],
  "sifen": { "codigo_respuesta": "0260", "mensaje": "Aprobado", "protocolo": "…" },
  "sifen_lote": null, "lote_numero": null, "lote_enviado_at": null, "retry_count": 0,
  "sent_at": "…", "approved_at": "…", "created_at": "…", "updated_at": "…"
}

• Con REJECTED o ERROR el panel muestra sifen.mensaje: pongan ahí el motivo.
• eventos, sifen_lote, retry_count, sent_at, approved_at: opcionales, sólo para mostrar.
• puede_reenviar (opcional, true/false): si el botón Reenviar sirve ahora. Si no viene, el panel lo muestra con ERROR o REJECTED, y con un PENDING que lleva más de 10 minutos sin moverse (updated_at).

KuDE y XML

Devuelvan el archivo con su Content-Type (application/pdf, application/xml). MaxTiendas lo pasa tal cual al navegador.

---

9. Después de emitir

Anular un documento APPROVED (evento ante la SET). Cuerpo: {"motivo":"texto de 5 a 500"}. Con 2xx la tienda lo marca anulado.

Volver a mandar a la SET uno en ERROR, REJECTED o PENDING trabado. Cuerpo: {}. Sin tope de intentos: quien factura lo toca cuando la SET o la conexión se cayeron. Respondan {"estado":"PENDING","message":"…"}; si no se puede, 422 con message en castellano. Sin esta ruta, el panel le dice al comercio que lo reenvíe desde su facturadora.

Reenviar el KuDE por correo. Cuerpo: {"email":"x@y.com"}, o {} para el correo del receptor.

Respuesta: cualquier 2xx; si traen message, se muestra.

---

10. Recibos de dinero · opcional

Si su sistema emite recibos, implementen esta sección y el comercio los usa desde MaxTiendas.

Parámetros: q, estado (EMITIDO/ANULADO), desde, hasta, page, per_page (25), documento_electronico_id.

{
  "data": [ { "id": 45, "numero": "REC-0045", "fecha": "2026-10-01", "receptor_nombre": "Empresa SA",
              "receptor_documento": "80012345-6", "receptor_email": "a@b.com",
              "documento_electronico_id": 120, "documento_origen": "ELECTRONICO", "documento_numero": "001-001-0000123",
              "documento_impreso_total": null, "forma_pago": 2, "forma_pago_label": "Transferencia bancaria",
              "numero_transaccion": "TRX991", "entidad_financiera": "Banco X", "concepto": "Pago de la factura 001-001-0000123",
              "importe": "500000.00", "moneda": "PYG", "estado": "EMITIDO", "estado_label": "Emitido",
              "anulacion_motivo": null, "email_enviado_at": null, "created_at": "…" } ],
  "current_page": 1, "last_page": 1, "per_page": 25, "total": 1, "from": 1, "to": 1
}

{ "fecha": "2026-10-01", "receptor_nombre": "Empresa SA", "receptor_documento": "80012345-6", "receptor_email": "a@b.com",
  "documento_origen": "ELECTRONICO", "documento_electronico_id": 120,
  "forma_pago": 2, "numero_transaccion": "TRX991", "entidad_financiera": "Banco X",
  "concepto": "Pago de la factura 001-001-0000123", "importe": 500000, "moneda": "PYG", "enviar_email": true }

• El documento que se paga es uno de tres:
  • documento_origen: "ELECTRONICO" + documento_electronico_id (su id de DE);
  • "EXTERNO" + documento_externo_cdc (CDC de 44 dígitos que empieza con 01). Si el CDC es de una factura de ustedes, resuélvanlo y devuelvan su documento_electronico_id;
  • "IMPRESO" + documento_impreso_timbrado, _establecimiento, _punto, _numero, _fecha, _total.
• forma_pago de recibos (distinto del tipo_pago de las facturas): 1 efectivo · 2 transferencia bancaria · 3 cheque · 4 tarjeta · 5 otro.

Respuesta (plana o en data): { "id": 45, "numero": "REC-0045", "documento_electronico_id": 120 }. Con documento_electronico_id, MaxTiendas aplica el cobro al pedido de esa factura.

Las demás

El recibo, con los mismos campos que en la lista.

Cuerpo: {"motivo":"3 a 255","enviar_email":true}. Respuesta: el recibo con documento_electronico_id (la tienda revierte el cobro).

Cuerpo: {"email":"…"} o {}.

El PDF del recibo.

Cuánto falta cobrar de esa factura: {"data":{"total":1500000,"cobrado":500000,"saldo":1000000,"moneda":"PYG"}}.

---

11. Lista para probar

1. El comercio carga URL y token → “Probar conexión” dice Conectado (/me, /sifen/timbrados).
2. Facturación → Nuevo documento → Factura manual → se emite y aparece en la lista (POST /sifen/de, GET /sifen/de).
3. Abrir el documento → se ve el detalle y el estado cambia a Aprobado (GET /sifen/de/{id}).
4. Botón PDF → abre el KuDE (/pdf).
5. Facturar un pedido pagado de la tienda y una venta del POS.
6. Nota de crédito sobre la factura aprobada (GET /sifen/de/{id} + POST /sifen/de).
7. Nota de remisión de un pedido (con transporte).
8. Anular la factura (/cancel).
9. Si implementaron recibos: recibo sobre la factura y su PDF.