💻 Ejemplos de integración REST

Esta página asume que conoces el protocolo de comunicación xPOS-Core. Aquí encontrarás el mismo flujo implementado en los lenguajes más comunes, listo para adaptar a tu POS.

Código de referencia — no copiar tal cual

Estos ejemplos son material de referencia para entender el flujo de integración con xPOS Core: no son SDKs oficiales ni código listo para producción. Ilustran el contrato del protocolo (endpoints, parámetros, manejo de errores), pero antes de usarlos en tu proyecto debes adaptarlos a tu realidad: país y tipo de documento, estructura real del document, reintentos, timeouts, logging y manejo de excepciones de tu plataforma. Valida siempre tu implementación contra el ambiente Sandbox (env=sbx) antes de pasar a Producción.

Todos los ejemplos implementan el flujo completo recomendado:

1. 1

   Healthcheck

   GET /health

   Verificar que el xPOS está sano antes de emitir.

2. 2

   Validación previa

   POST /process-documents · operation=test

   Valida el documento sin asignar folio, firmar ni enviar a la entidad tributaria.

3. 3

   Emisión real

   POST /process-documents · operation=consolidate

   El mismo endpoint con operation=consolidate.

4. 4

   Manejo de errores

   Si message es Operation Error, stage y error_description indican la causa; la acción a tomar está en el catálogo de códigos de errores.

5. 5

   Recuperación de estado

   GET /status

   Si el POS perdió el response, no reenvíes el documento; recupera la respuesta original.

Valores de ejemplo

Los ejemplos usan Chile (country=cl, typeDoc=39 boleta electrónica) en Sandbox (env=sbx). Ajusta country, typeDoc e inputType según la ficha de tu país. El body document es un placeholder: la estructura real del documento depende del país y del tipo de documento — consulta la ficha correspondiente y el Swagger local (http://localhost:3200/api/v1/doc/).

El origin de los ejemplos (<taxId>) es el identificador tributario del emisor. Si tu instalación tiene un solo emisor puedes omitir el parámetro; con dos o más es obligatorio.

Cliente de ejemplo por lenguaje

Terminal

Web

Backend

>_cURLTerminal (cURL)ejemplo.sh

# taxId del emisor. Opcional con 1 onboarding; obligatorio con 2 o mas
ORIGIN="<taxId>"

# Healthcheck: 500 o status != "ok" → el xPOS no está listo para emitir
curl "http://localhost:3200/api/v1/health"

# Validar el armado del documento sin emitir (operation=test)
curl -X POST "http://localhost:3200/api/v1/process-documents?env=sbx&operation=test&typeDoc=39&country=cl&inputType=json&origin=$ORIGIN" \
  -H "Content-Type: application/json" \
  -d @documento.json

# Emitir de verdad (operation=consolidate)
curl -X POST "http://localhost:3200/api/v1/process-documents?env=sbx&operation=consolidate&typeDoc=39&country=cl&inputType=json&origin=$ORIGIN" \
  -H "Content-Type: application/json" \
  -d @documento.json

# Recuperar el response de un documento ya procesado (no reenviar el documento)
curl "http://localhost:3200/api/v1/status?transactionId=1ebf7ddc-94e2-4255-a741-de7e6cd0e439"

Recordatorios del protocolo

• Base URL: http://localhost:3200/api/v1 — xPOS Core se consume por loopback; no se publica a la red y no requiere autenticación.
• Los 5 query params de /process-documents son obligatorios: env, operation, typeDoc, country, inputType. El sexto, origin, es condicional: opcional con un solo emisor instalado, obligatorio con dos o más (sin él, HTTP 400). Ver Multiroot.
• inputType=txt es la excepción del body: va con Content-Type: text/plain y el cuerpo es el texto plano tal cual, sin JSON ni base64. Los ejemplos de esta página usan inputType=json.
• El ambiente (sbx | prd) lo fija el onboarding: no se alterna en caliente con el query param.
• Campos base64 del response: output, signedXml, input, applicationResponse y barcodeBase64 (PDF417 en Chile, QR en el resto).
• Países asíncronos (Chile, Paraguay): el eco de la entidad tributaria no viene en el response inicial — ver la ficha del país para saber cómo obtener el estado fiscal final.