📤 Emitir documentos

El flujo principal — emitir un documento desde el POS — se invoca con POST /api/v1/process-documents. Este es el endpoint que tu POS llamará en cada venta.

¿Prefieres partir del código? El mismo flujo está implementado en 8 lenguajes en Ejemplos de integración.

🔗 Integración REST

Qué parámetros lleva en la URL

Todos van como query params (?env=…&operation=…&…) y los cinco son obligatorios.

AtributoTipoDescripción

envsbx | prdAmbiente operativo. Debe coincidir con el del onboarding — ver Modelo de operación en Conceptos y conexión.

operationtest | consolidatetest valida sin emitir; consolidate emite y registra de verdad (ver flujo abajo).

typeDocstringTipo de documento (factura, boleta, NC, NV, etc.). Cada país usa su propia tabla — ver ficha del país.

countrycl | co | cr | sv | gt | pa | py | doCódigo ISO del país que opera el xPOS.

inputTypejson | xml | xdoc | txtFormato del documento que envías en el body. Cada país soporta un subconjunto — ver ficha del país.

Qué va en el body

El documento del POS, en el formato declarado en inputType:

• json: se envía tal cual, como JSON.
• xml / xdoc / txt: se envían codificados en base64 cuando el país así lo requiere.

Qué hace xPOS Core con tu documento

xPOS aplica uno de tres patrones internos según el país. La diferencia está en si el formato tributario final es XML o JSON, y en si hay bifurcación por tipo de documento.

Patrón A — XML con XSD (mayoría de países)

Cuando llega un documento con operation=consolidate:

1. Recibe el input (json, xml, xdoc o txt).
2. Si el input no es XML, lo transforma a XML <root>.
3. Aplica input_to_dte_<pais>.xslt → XML Gosocket.
4. Aplica dte_to_fiscal_<pais>.xslt → DTE tributario.
5. Valida el resultado contra el XSD oficial.
6. Asigna folio (si el Gestor de Folios está activo).
7. Firma el DTE.
8. Lo envía a la entidad tributaria.
9. Devuelve la respuesta al POS.
10. Publica el DTE en Gosocket (Inbox).

Patrón B — JSON con JSON Schema

Igual que el Patrón A, pero los pasos 4 y 5 generan JSON tributario y validan contra JSON Schema en lugar de XSD.

Patrón C — XML dual

Igual que el Patrón A, pero el paso 4 se bifurca según el tipo de documento (DTE tributario vs. equivalente, cada uno con su XSLT).

Qué cambia con operation = test

test ejecuta solo los pasos 1–5 (transformación + validación). No asigna folio, no firma, no envía a la entidad tributaria y no publica en Gosocket. Sirve para validar que el documento está bien armado antes de emitirlo en serio.

🔄 Integración por Socket

nota

El canal Socket no aparece en el Swagger (OpenAPI 3.0 no modela WebSockets). El contrato funcional descrito aquí es el acuerdo de implementación para la integración ws://localhost:3200.

Mismo flujo funcional que REST, con la diferencia de que los parámetros viajan dentro del objeto de request (no en query params).

Cómo se envía

Se arma un objeto con el mismo contenido que el POST REST:

{"env":"sbx","operation":"consolidate","typeDoc":<N>,"country":"<XX>","inputType":"json","document":{...}}

Ese objeto se serializa a string y el string se envía en base64. El servidor procesa y responde también en base64; al decodificar, la estructura es equivalente al response REST.

📬 ¿Y la respuesta?

Independientemente del canal (REST o Socket), xPOS Core devuelve el mismo objeto JSON. Está documentado campo a campo — incluido el contrato de errores — en Response y manejo de errores.