Tu primera orden.
Un paso a la vez.

PASO 01 · CONFIGURACIÓN

Preparar el tenant y el acceso

Antes de enviar datos, asegurate de trabajar con la empresa y el ambiente correctos.

1. En Administrar tenant → Nueva integración, elegí eCommerce. Confirmá que la empresa corresponde a la tienda.
2. Identificá la tienda y el backend acordado. Configurá los secretos únicamente en sus campos protegidos, nunca en nombres, URLs, capturas o manuales.
3. Solicitá una credencial técnica de prueba de AGo vinculada a esa empresa y mantenela en tu backend. Registrar Auth Token en el tenant no emite una credencial ni demuestra que sea válida.
4. Dejá ¿Activo? desmarcado hasta validar el circuito. Guardar la ficha no instala un conector de Shopify ni confirma sincronización.
5. Prepará un cliente, productos, moneda y tasas de IVA reales del entorno de prueba. No uses los identificadores ilustrativos siguientes sin reemplazarlos.

PASO 02 · CREACIÓN

Crear la primera orden

Desde tu backend: POST {{base_url}}/orders, con Content-Type: application/json. Confirmá la URL del ambiente de prueba. Ejemplo ilustrativo, no ejecutado:

{
  "token": "TOKEN_TECNICO_DE_PRUEBA",
  "orden": {
    "configurations": {
      "NuevoUpdate": 1,
      "IdExterno": "TIENDA-PRUEBA-0001",
      "Cliente": 999,
      "ClienteDsc": "CLIENTE DE PRUEBA",
      "IdMon": 0,
      "Payment": {"pending": true, "total": 100, "shipping": 0, "discounts": {"total": 0}}
    },
    "items": [
      {"sku": "SKU-PRUEBA", "Articulo": "Producto de prueba", "cantidad": 1,
       "preciounitario": 100, "PorCenIva": 22, "modifiers": []}
    ]
  }
}

Reemplazá token, Cliente, IdMon, SKU y PorCenIva con valores autorizados del entorno. NuevoUpdate: 1 solicita creación; IdExterno identifica la compra externa. Payment.pending: true evita presentar este ejemplo como cobrado.

Control de resultado: revisá HTTP y el JSON, no solo el código HTTP. Una respuesta de creación contiene status: true e IdVenta. Guardá ese identificador y la referencia externa en tu sistema.

PASO 03 · UN CASO MÁS COMPLETO

Varios artículos y un descuento

Usá la misma estructura anterior, otra referencia externa para una compra diferente y estos componentes. No son un cuerpo completo por sí solos:

"Payment": {"pending": true, "total": 190, "shipping": 0, "discounts": {"total": 10}}

"items": [
  {"sku": "SKU-A", "Articulo": "Producto A", "cantidad": 1,
   "preciounitario": 100, "PorCenIva": 22, "modifiers": []},
  {"sku": "SKU-B", "Articulo": "Producto B", "cantidad": 2,
   "preciounitario": 50, "PorCenIva": 22, "modifiers": []}
]

Comprobación: 100 + (2 × 50) − 10 = 190. Los ejemplos mantienen shipping en cero: el controlador revisado tiene comprobaciones financieras diferentes para envío, por lo que no damos por validado ese caso. Modificadores y medios de pago requieren sus propios IDs y pruebas.

PASO 04 · COMPROBACIÓN

Leer y comprobar la orden

Para la consulta puntual: POST {{base_url}}/orders/get, con el mismo token técnico de la empresa:

{"token": "TOKEN_TECNICO_DE_PRUEBA", "idventa": 12345}

Reemplazá 12345 con el IdVenta recibido. Consultá los campos de respuesta vigentes en API completa → Órdenes. Abrí Gestión de Órdenes y verificá cliente, artículos, moneda, importe y estado de pago.

• Recibida: existe una IdVenta; no significa facturada.
• Reintento: una compra debe conservar su IdExterno. El controlador consulta la referencia y puede responder Orden ya procesada con la IdVenta existente. Verificá que solo haya una orden; la concurrencia también requiere una prueba.
• Facturación: se gestiona desde la orden. Una orden guardada no confirma emisión ni aceptación fiscal.

PASO 05 · FACTURACIÓN

De la orden a la factura y su resultado fiscal

La creación de la orden es el primer paso. Cuando corresponda facturar, prepará el documento fiscal, solicitá su creación, vinculalo con la orden y consultá el CFE. Este recorrido sigue la secuencia de Mercado Libre y permite conservar la misma orden.

1. POST /orders → conservar IdVenta e IdExterno.
2. POST /setInvoicyUY → crear el documento y conservar Documento, Terminal y CodM.
3. POST /orders/fiscal-result → vincular ese documento con la misma IdVenta.
4. POST /getResponseCfe → consultar el resultado fiscal, la serie, el número y la representación.

Antes de enviar: confirmá empresa y ambiente, credencial técnica habilitada, cliente y datos fiscales del receptor, artículos, impuestos, moneda/cambio, acción documental, terminal, vendedor y caja cuando aplique. Cliente = 9998 no determina por sí solo el tipo de CFE. La acción y el receptor se resuelven con los catálogos y la configuración de la empresa.

Todos los ejemplos son ilustrativos. Usá la URL base acordada; por ejemplo, https://api.bestroute.io si es el ambiente autorizado. Enviá Content-Type: application/json y el token técnico de AGo en el cuerpo desde tu backend. Sustituí los valores REEMPLAZAR_... y los IDs ilustrativos antes de una prueba autorizada. Las llamadas de creación generan efectos reales; esta guía no las ejecuta.

1. Preparar y solicitar el documento

Ejemplo sin descuentos ni envío: una unidad a 122, IVA incluido al 22%; neto 100, IVA 22 y total 122. Conservá la IdVenta: 12345 recibida de la orden. No es el número de factura.

{
  "token": "REEMPLAZAR_TOKEN_AGO",
  "data": {
    "cabezal": {
      "Nivel": "9",
      "serie": "REEMPLAZAR_TERMINAL",
      "pde": "REEMPLAZAR_PUNTO_EMISION",
      "numerofact": "0",
      "numerocliente": "REEMPLAZAR_CLIENTE",
      "accion": "REEMPLAZAR_ACCION_DOCUMENTAL",
      "vendedor": "REEMPLAZAR_VENDEDOR",
      "forma_pago": "REEMPLAZAR_FORMA_PAGO",
      "fechaDoc": "27/10/2026",
      "fechaVto": "27/10/2026",
      "FecCobro": "2026-10-27",
      "moneda": "REEMPLAZAR_MONEDA",
      "tc": "REEMPLAZAR_TIPO_CAMBIO",
      "Email": "",
      "Name": "CLIENTE DE EJEMPLO",
      "attach": "",
      "bono": "0",
      "boni": 0,
      "obs": "Orden Vita 12345 / SHOPIFY-PEDIDO-EJEMPLO",
      "importBoni": 0,
      "dtoGral": 0,
      "imporDto": 0,
      "netoTot": 100,
      "ivaTot": 22,
      "totGral": 122,
      "IMP": "S",
      "mediopag": [
        {"medios": {"IdMedio": "REEMPLAZAR_MEDIO_PAGO", "Importe": 122, "Detalle": "Referencia del pago confirmado"}}
      ],
      "EstPedido": "1",
      "IdVenta": 12345,
      "IdUserCaja": "REEMPLAZAR_USUARIO_CAJA",
      "IdAperturaCaja": "REEMPLAZAR_APERTURA_CAJA",
      "mozo": "0",
      "mesa": "0",
      "OrdenCompra": "12345",
      "CodCC": "0",
      "CodDepo": "REEMPLAZAR_DEPOSITO",
      "CodMandante": "0",
      "INCOTERM": "",
      "cmbRetail": "0",
      "channel": "0",
      "IdReprese": "0",
      "IdSucursal": "REEMPLAZAR_SUCURSAL",
      "IdDistri": "0"
    },
    "items": [
      {
        "prodid": "REEMPLAZAR_ID_ARTICULO_AGO",
        "desc": "Producto de ejemplo",
        "cnT": 1,
        "precio": 122,
        "imp": 22,
        "dtoLinea": 0,
        "dtoPor": 0,
        "uni": "0",
        "unidst": "0",
        "cntConver": "0",
        "Stk": -1,
        "totalN": 122,
        "totalCiva": 122
      }
    ]
  }
}

Convención de importes del ejemplo: reproduce el constructor de Mercado Libre: precio bruto y totalN/totalCiva de línea con el total final; el motor realiza la apertura del IVA. El cabezal conserva neto, IVA y total por separado. No mezcles esta convención con un constructor que envía netos e impuestos por línea. Validá una operación controlada con la configuración de tu empresa.

• prodid es el identificador interno del artículo de AGo; resolvelo desde el catálogo. No asumas que coincide con el SKU externo.
• accion, serie/terminal, medio de pago, moneda, depósito y sucursal deben salir de los catálogos autorizados. No copies IDs, cambio o cajero de otra integración. Para moneda local, usá el cambio que corresponda a su configuración.
• El ejemplo corresponde a una operación con pago confirmado y medios por el total. Para crédito, elegí la acción autorizada y el cliente identificado; los medios se adaptan a ese contrato. Declarar un medio no verifica ni ejecuta un cobro en Shopify.
• IMP: "S" conserva el comportamiento documental utilizado por Mercado Libre. No lo cambies a "N" para evitar impresión: el motor puede tratarlo como pedido. ML_SIN_IMPRESORA es un alias específico del conector, no un PDE genérico.
• Reemplazá fechas por las de la operación. Si hay descuentos, envío, IVA mixto o modificadores, conciliá líneas, bases y total antes de emitir; no dupliques descuentos en cabezal y renglones. Este ejemplo no valida esos casos.

Referencia de orden: enviá data.cabezal.IdVenta. OrdenCompra y obs aportan trazabilidad en este ejemplo; no sustituyen el vínculo. En el adaptador actual, IdVenta no se traslada al XML SOAP: para completar el circuito público realizá también el paso siguiente. Mercado Libre efectúa su propia actualización interna después de obtener el documento.

Respuesta ilustrativa de creación documental:

[
  {"Coderror": "0", "DscError": "", "Documento": "45678", "CodM": "1", "Terminal": "1"}
]

Verificá HTTP, que la respuesta sea un array, Coderror = "0" y la presencia de los tres identificadores. Guardalos antes del siguiente paso. CodM es el código de movimiento devuelto, no el tipo de CFE. El servicio puede devolver campos adicionales de caja; conservá sus advertencias. Crear el documento ejecuta los procesos ERP configurados —por ejemplo stock y contabilidad— y puede despachar el CFE si la empresa tiene emisión habilitada. Esta respuesta no acredita aceptación fiscal.

2. Vincular el documento con la orden

Usá la misma IdVenta y copiá exactamente los identificadores devueltos por setInvoicyUY. No uses el número Shopify ni el número CFE como Documento.

{
  "token": "REEMPLAZAR_TOKEN_AGO",
  "data": {
    "IdVenta": 12345,
    "Documento": "45678",
    "Terminal": "1",
    "CodM": "1",
    "Estado": "FACTURADA",
    "raw": [{"Coderror": "0", "DscError": "", "Documento": "45678", "CodM": "1", "Terminal": "1"}]
  }
}

Esperá status: true y verificá los datos devueltos. Este paso guarda Doc/Ter/CodM en la orden y la deja operativamente facturada. No crea otro documento, no emite un CFE y no certifica su aceptación. Si falla el vínculo, conservá el documento y corregí o repetí únicamente este paso después de comprobar que la orden no tenga otro vínculo.

Podés comprobar la orden mediante POST {{base_url}}/orders/get-operational:

{"token": "REEMPLAZAR_TOKEN_AGO", "idventa": 12345}

3. Consultar el resultado fiscal

Consultá con la identidad del documento ERP; no con IdVenta. El emisor se procesa en segundo plano, por lo que el resultado puede no estar disponible inmediatamente.

{
  "token": "REEMPLAZAR_TOKEN_AGO",
  "data": {
    "cabezal": {"Documento": "45678", "Terminal": "1", "CodM": "1"}
  }
}

Ejemplo de respuesta sin resultado disponible todavía:

{
  "status": false,
  "coderror": "",
  "dscError": "",
  "codigoSeguridad": "",
  "Serie": "",
  "cfeNumero": "",
  "cfeRepImpresa": "",
  "msgCod": "",
  "msgDsc": "",
  "statusMotivo": ""
}

Consultá nuevamente con espera progresiva y un plazo de seguimiento acordado. Al agotar ese plazo, conservá el estado pendiente de conciliación e informá la incidencia. No vuelvas a llamar a setInvoicyUY porque aún no haya respuesta fiscal. Para detalle de XML, errores y representación, también existe POST /workflow/documents/cfe-detail con el siguiente cuerpo y autorización correspondiente:

{"token": "REEMPLAZAR_TOKEN_AGO", "Doc": 45678, "Ter": 1, "CODM": 1}

4. Corregir y recuperar sin duplicar

Controles de integración: conservá una relación estable entre empresa, referencia externa, IdVenta y Documento/Terminal/CodM; serializá la facturación de cada orden y guardá la respuesta antes de enlazar. IdExterno evita determinados duplicados de orden, pero no es una garantía de idempotencia fiscal en setInvoicyUY. No inventes un header de idempotencia que este contrato no implementa.

Antes de habilitar: validar una operación autorizada de extremo a extremo: orden → documento → vínculo → resultado fiscal → representación, incluyendo los movimientos ERP que correspondan. Para órdenes ya existentes, conciliar documentos y CFE antes de cualquier regularización. No procesar masivamente por un rango de IDs supuesto.

Contrato revisado el 27/10/2026: OrdersController, InvoicyUYController, MercadoLibreWebhookController y motor ws_facturas.php. Confirmar versión publicada y acceso de la credencial técnica a cada ruta. Los ejemplos no fueron enviados a una API ni al proveedor.

PASO 06 · CIERRE DEL RECORRIDO

Resolver incidencias y preparar la activación

• Token vencido o inexistente: revisar la credencial técnica y su empresa; no sustituirla por una sesión personal.
• Orden inválida, sin items o sin SKU: corregir la estructura y campos indicados.
• Cliente requerido: usar un cliente válido de la empresa.
• Inconsistencia de total: revisar cantidad × precio, descuentos y Payment.total.
• Rechazo fiscal: revisar el resultado del comprobante desde la orden; no crear otra compra para ocultar el rechazo.

Antes de activar: demostrar una creación, consulta y reintento sin duplicados; validar el estado de pago y el circuito fiscal cuando corresponda. Registrar evidencia sin secretos. Activar únicamente la integración acordada para la empresa, con autorización.

Base de esta guía: rutas locales de Órdenes y validaciones de OrdersController/AuthController. Son ejemplos de contrato; la aceptación en el servidor publicado y el uso del token independiente aún requieren prueba controlada.