Emisso Connect


Tool ID	`shopify.pedidos.listar`
Nombre MCP	`shopify__pedidos__listar`
Conector	`shopify`
Plano	`action`
Scope (permiso)	`shopify:pedidos`
Auth	`connection_credentials`
Versión	`1`
Sensible	no
Deprecado	no
Comportamiento	readOnly=true, destructive=false, idempotent=true, openWorld=true

Requiere conexión. Indica cuál en cada llamada: header X-Connect-Connection en REST y campo connectionId en el execute de MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de conexiones.estado.consultar.

Qué hace

Trae estado, cancelación y montos (subtotal, descuentos, impuestos, envío, total, reembolsado y saldo). Filtra por rango de creación, estado de pago o nombre, y pagina con siguientePagina. Excluye pedidos de prueba salvo que pidas incluirlos. Sin el permiso read_all_orders, Shopify solo deja ver los últimos 60 días: historial lo dice. Connect consulta Shopify en vivo y no guarda nada: cada llamada lee la tienda de la conexión.

Entrada

Campo	Tipo	Requerido	Descripción
`desde`	string `^\d4-\d2-\d2T\d2:\d2(?::\d2(?:.\d9)?)?(?:Z	[+-]\d2:\d2)$`	no
`hasta`	string `^\d4-\d2-\d2T\d2:\d2(?::\d2(?:.\d9)?)?(?:Z	[+-]\d2:\d2)$`	no
`estadoFinanciero`	`"authorized"` · `"expired"` · `"paid"` · `"partially_paid"` · `"partially_refunded"` · `"pending"` · …	no	Filtra por estado de pago de Shopify.
`nombre`	string `^#?[A-Za-z0-9-]{1,32}$`	no	Nombre visible del pedido, por ejemplo `#1001`.
`incluirPrueba`	booleano	no · default `false`	true para incluir pedidos de prueba. Por defecto se excluyen.
`orden`	`"recientes"` · `"antiguos"`	no · default `"recientes"`	Orden por fecha de creación.
`maximo`	entero 1-25	no · default `20`	Pedidos por página, de 1 a 25.
`pagina`	string	no	El valor `siguientePagina` de una respuesta anterior, con los MISMOS filtros.

JSON Schema de entrada

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "desde": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d{1,9})?)?(?:Z|[+-]\\d{2}:\\d{2})$",
      "description": "Solo pedidos creados desde este instante (inclusive). Instante ISO 8601 con zona, por ejemplo `2026-10-01T00:00:00-03:00`."
    },
    "hasta": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d{1,9})?)?(?:Z|[+-]\\d{2}:\\d{2})$",
      "description": "Solo pedidos creados antes de este instante (exclusive). Instante ISO 8601 con zona, por ejemplo `2026-10-01T00:00:00-03:00`."
    },
    "estadoFinanciero": {
      "description": "Filtra por estado de pago de Shopify.",
      "type": "string",
      "enum": [
        "authorized",
        "expired",
        "paid",
        "partially_paid",
        "partially_refunded",
        "pending",
        "refunded",
        "voided"
      ]
    },
    "nombre": {
      "description": "Nombre visible del pedido, por ejemplo `#1001`.",
      "type": "string",
      "pattern": "^#?[A-Za-z0-9-]{1,32}$"
    },
    "incluirPrueba": {
      "default": false,
      "description": "true para incluir pedidos de prueba. Por defecto se excluyen.",
      "type": "boolean"
    },
    "orden": {
      "default": "recientes",
      "description": "Orden por fecha de creación.",
      "type": "string",
      "enum": [
        "recientes",
        "antiguos"
      ]
    },
    "maximo": {
      "default": 20,
      "description": "Pedidos por página, de 1 a 25.",
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    },
    "pagina": {
      "description": "El valor `siguientePagina` de una respuesta anterior, con los MISMOS filtros.",
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    }
  },
  "additionalProperties": false
}

Ejemplo

curl

curl -X POST https://connect.emisso.ai/api/v1/tools/shopify.pedidos.listar/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"desde":"2026-10-01T00:00:00-03:00","hasta":"2026-11-01T00:00:00-03:00","maximo":20}}'

MCP · meta-tool execute

{
  "tool": "shopify.pedidos.listar",
  "params": {
    "desde": "2026-10-01T00:00:00-03:00",
    "hasta": "2026-11-01T00:00:00-03:00",
    "maximo": 20
  },
  "connectionId": "conn_9tKfR2mQx4Vb"
}

Salida esperada (200):

{
  "data": {
    "pedidos": [
      {
        "pedidoId": "gid://shopify/Order/5612345678901",
        "numero": "5612345678901",
        "nombre": "#1042",
        "creadoEn": "2026-10-14T15:20:11.000Z",
        "procesadoEn": "2026-10-14T15:20:10.000Z",
        "actualizadoEn": "2026-10-15T12:02:45.000Z",
        "canceladoEn": null,
        "motivoCancelacion": null,
        "cerradoEn": null,
        "prueba": false,
        "estadoFinanciero": "PARTIALLY_REFUNDED",
        "estadoDespacho": "FULFILLED",
        "impuestosIncluidos": true,
        "canal": "web",
        "montos": {
          "subtotal": {
            "monto": "23980.0",
            "moneda": "CLP"
          },
          "descuentos": {
            "monto": "2000.0",
            "moneda": "CLP"
          },
          "impuestos": {
            "monto": "4466.0",
            "moneda": "CLP"
          },
          "envio": {
            "monto": "3990.0",
            "moneda": "CLP"
          },
          "total": {
            "monto": "27970.0",
            "moneda": "CLP"
          },
          "reembolsado": {
            "monto": "11990.0",
            "moneda": "CLP"
          },
          "totalActual": {
            "monto": "15980.0",
            "moneda": "CLP"
          },
          "pendiente": {
            "monto": "0.0",
            "moneda": "CLP"
          }
        },
        "totalComprador": {
          "monto": "27970.0",
          "moneda": "CLP"
        }
      }
    ],
    "siguientePagina": null,
    "historial": {
      "completo": false,
      "diasDisponibles": 60
    }
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "shopify.pedidos.listar",
    "plane": "action",
    "latency_ms": 7410,
    "audit_status": "recorded"
  }
}

Para las líneas, transacciones y reembolsos de un pedido usa shopify.pedido.leer con su pedidoId.

Salida

Campo	Tipo	Requerido	Descripción
`pedidos`	lista de objeto	sí	Pedidos de esta página, sin datos de clientes.
`pedidos[].pedidoId`	string `^gid:\/\/shopify\/`	sí	Identificador del pedido. Identificador global de Shopify (`gid://shopify/Order/…`), texto.
`pedidos[].numero`	string `^[0-9]{1,20}$`	null	sí
`pedidos[].nombre`	string	null	sí
`pedidos[].creadoEn`	string	sí	Cuándo se creó el pedido. Instante ISO 8601 en UTC (Z).
`pedidos[].procesadoEn`	string	null	sí
`pedidos[].actualizadoEn`	string	null	sí
`pedidos[].canceladoEn`	string	null	sí
`pedidos[].motivoCancelacion`	string	null	sí
`pedidos[].cerradoEn`	string	null	sí
`pedidos[].prueba`	booleano	sí	true si es un pedido de prueba.
`pedidos[].estadoFinanciero`	string	null	sí
`pedidos[].estadoDespacho`	string	null	sí
`pedidos[].impuestosIncluidos`	booleano	null	sí
`pedidos[].canal`	string	null	sí
`pedidos[].montos`	objeto	sí	Montos en la moneda de la tienda.
`pedidos[].montos.subtotal`	objeto	sí	Suma de las líneas después de descuentos y antes de devoluciones (`subtotalPriceSet`).
`pedidos[].montos.descuentos`	objeto	sí	Total descontado antes de devoluciones. Informativo: ya está restado del subtotal y del total.
`pedidos[].montos.impuestos`	objeto	sí	Total de impuestos antes de devoluciones.
`pedidos[].montos.envio`	objeto	sí	Total de envío según Shopify (`totalShippingPriceSet`).
`pedidos[].montos.total`	objeto	sí	Total del pedido antes de devoluciones (`totalPriceSet`), con descuentos ya aplicados. Refleja ediciones posteriores.
`pedidos[].montos.reembolsado`	objeto	sí	Total reembolsado hasta ahora.
`pedidos[].montos.totalActual`	objeto	sí	Total después de devoluciones (`currentTotalPriceSet`). Ya descuenta lo devuelto: no le restes `reembolsado`.
`pedidos[].montos.pendiente`	objeto	sí	Monto todavía no transado del pedido (`totalOutstandingSet`).
`pedidos[].totalComprador`	objeto	null	sí
`pedidos[].totalComprador.monto`	string `^-?[0-9]{1,19}(?:\.[0-9]{1,9})?$`	sí	Monto decimal exacto como texto, tal como lo entrega Shopify (`12990.0`). Nunca se redondea.
`pedidos[].totalComprador.moneda`	string `^[A-Z]{3}$`	sí	Código ISO 4217 de la moneda, por ejemplo `CLP`.
`siguientePagina`	string	null	sí
`historial`	objeto	sí	Cuánto historial de pedidos alcanza esta conexión según los permisos concedidos en Shopify.
`historial.completo`	booleano	null	sí
`historial.diasDisponibles`	entero	null	sí

JSON Schema de salida

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "pedidos": {
      "maxItems": 25,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "pedidoId": {
            "type": "string",
            "pattern": "^gid:\\/\\/shopify\\/",
            "description": "Identificador del pedido. Identificador global de Shopify (`gid://shopify/Order/…`), texto."
          },
          "numero": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[0-9]{1,20}$"
              },
              {
                "type": "null"
              }
            ],
            "description": "Identificador numérico del pedido (legacyResourceId), texto."
          },
          "nombre": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 64
              },
              {
                "type": "null"
              }
            ],
            "description": "Nombre visible del pedido, por ejemplo `#1001`."
          },
          "creadoEn": {
            "type": "string",
            "description": "Cuándo se creó el pedido. Instante ISO 8601 en UTC (Z)."
          },
          "procesadoEn": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cuándo se procesó el pedido. Instante ISO 8601 en UTC (Z); null si Shopify no lo informa."
          },
          "actualizadoEn": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Última actualización del pedido. Instante ISO 8601 en UTC (Z); null si Shopify no lo informa."
          },
          "canceladoEn": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cuándo se canceló; null si no está cancelado. Instante ISO 8601 en UTC (Z); null si Shopify no lo informa."
          },
          "motivoCancelacion": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 64
              },
              {
                "type": "null"
              }
            ],
            "description": "Motivo de cancelación de Shopify (`CUSTOMER`, `FRAUD`, `INVENTORY`, `DECLINED`, `STAFF`, `OTHER`); null si no aplica."
          },
          "cerradoEn": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cuándo se cerró (archivó) el pedido. Instante ISO 8601 en UTC (Z); null si Shopify no lo informa."
          },
          "prueba": {
            "type": "boolean",
            "description": "true si es un pedido de prueba."
          },
          "estadoFinanciero": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 64
              },
              {
                "type": "null"
              }
            ],
            "description": "Estado de pago según Shopify, por ejemplo `PAID`, `PENDING`, `PARTIALLY_REFUNDED`, `REFUNDED`."
          },
          "estadoDespacho": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 64
              },
              {
                "type": "null"
              }
            ],
            "description": "Estado de despacho según Shopify, por ejemplo `FULFILLED` o `UNFULFILLED`."
          },
          "impuestosIncluidos": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "true si los precios del pedido incluyen impuestos."
          },
          "canal": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 128
              },
              {
                "type": "null"
              }
            ],
            "description": "Origen del pedido según Shopify (`web`, `pos`, …)."
          },
          "montos": {
            "type": "object",
            "properties": {
              "subtotal": {
                "type": "object",
                "properties": {
                  "monto": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,19}(?:\\.[0-9]{1,9})?$",
                    "description": "Monto decimal exacto como texto, tal como lo entrega Shopify (`12990.0`). Nunca se redondea."
                  },
                  "moneda": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "Código ISO 4217 de la moneda, por ejemplo `CLP`."
                  }
                },
                "required": [
                  "monto",
                  "moneda"
                ],
                "additionalProperties": false,
                "description": "Suma de las líneas después de descuentos y antes de devoluciones (`subtotalPriceSet`)."
              },
              "descuentos": {
                "type": "object",
                "properties": {
                  "monto": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,19}(?:\\.[0-9]{1,9})?$",
                    "description": "Monto decimal exacto como texto, tal como lo entrega Shopify (`12990.0`). Nunca se redondea."
                  },
                  "moneda": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "Código ISO 4217 de la moneda, por ejemplo `CLP`."
                  }
                },
                "required": [
                  "monto",
                  "moneda"
                ],
                "additionalProperties": false,
                "description": "Total descontado antes de devoluciones. Informativo: ya está restado del subtotal y del total."
              },
              "impuestos": {
                "type": "object",
                "properties": {
                  "monto": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,19}(?:\\.[0-9]{1,9})?$",
                    "description": "Monto decimal exacto como texto, tal como lo entrega Shopify (`12990.0`). Nunca se redondea."
                  },
                  "moneda": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "Código ISO 4217 de la moneda, por ejemplo `CLP`."
                  }
                },
                "required": [
                  "monto",
                  "moneda"
                ],
                "additionalProperties": false,
                "description": "Total de impuestos antes de devoluciones."
              },
              "envio": {
                "type": "object",
                "properties": {
                  "monto": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,19}(?:\\.[0-9]{1,9})?$",
                    "description": "Monto decimal exacto como texto, tal como lo entrega Shopify (`12990.0`). Nunca se redondea."
                  },
                  "moneda": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "Código ISO 4217 de la moneda, por ejemplo `CLP`."
                  }
                },
                "required": [
                  "monto",
                  "moneda"
                ],
                "additionalProperties": false,
                "description": "Total de envío según Shopify (`totalShippingPriceSet`)."
              },
              "total": {
                "type": "object",
                "properties": {
                  "monto": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,19}(?:\\.[0-9]{1,9})?$",
                    "description": "Monto decimal exacto como texto, tal como lo entrega Shopify (`12990.0`). Nunca se redondea."
                  },
                  "moneda": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "Código ISO 4217 de la moneda, por ejemplo `CLP`."
                  }
                },
                "required": [
                  "monto",
                  "moneda"
                ],
                "additionalProperties": false,
                "description": "Total del pedido antes de devoluciones (`totalPriceSet`), con descuentos ya aplicados. Refleja ediciones posteriores."
              },
              "reembolsado": {
                "type": "object",
                "properties": {
                  "monto": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,19}(?:\\.[0-9]{1,9})?$",
                    "description": "Monto decimal exacto como texto, tal como lo entrega Shopify (`12990.0`). Nunca se redondea."
                  },
                  "moneda": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "Código ISO 4217 de la moneda, por ejemplo `CLP`."
                  }
                },
                "required": [
                  "monto",
                  "moneda"
                ],
                "additionalProperties": false,
                "description": "Total reembolsado hasta ahora."
              },
              "totalActual": {
                "type": "object",
                "properties": {
                  "monto": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,19}(?:\\.[0-9]{1,9})?$",
                    "description": "Monto decimal exacto como texto, tal como lo entrega Shopify (`12990.0`). Nunca se redondea."
                  },
                  "moneda": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "Código ISO 4217 de la moneda, por ejemplo `CLP`."
                  }
                },
                "required": [
                  "monto",
                  "moneda"
                ],
                "additionalProperties": false,
                "description": "Total después de devoluciones (`currentTotalPriceSet`). Ya descuenta lo devuelto: no le restes `reembolsado`."
              },
              "pendiente": {
                "type": "object",
                "properties": {
                  "monto": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,19}(?:\\.[0-9]{1,9})?$",
                    "description": "Monto decimal exacto como texto, tal como lo entrega Shopify (`12990.0`). Nunca se redondea."
                  },
                  "moneda": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "Código ISO 4217 de la moneda, por ejemplo `CLP`."
                  }
                },
                "required": [
                  "monto",
                  "moneda"
                ],
                "additionalProperties": false,
                "description": "Monto todavía no transado del pedido (`totalOutstandingSet`)."
              }
            },
            "required": [
              "subtotal",
              "descuentos",
              "impuestos",
              "envio",
              "total",
              "reembolsado",
              "totalActual",
              "pendiente"
            ],
            "additionalProperties": false,
            "description": "Montos en la moneda de la tienda."
          },
          "totalComprador": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "monto": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,19}(?:\\.[0-9]{1,9})?$",
                    "description": "Monto decimal exacto como texto, tal como lo entrega Shopify (`12990.0`). Nunca se redondea."
                  },
                  "moneda": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "description": "Código ISO 4217 de la moneda, por ejemplo `CLP`."
                  }
                },
                "required": [
                  "monto",
                  "moneda"
                ],
                "additionalProperties": false,
                "description": "Total en la moneda en que pagó el comprador; null si Shopify no lo informa."
              },
              {
                "type": "null"
              }
            ],
            "description": "Total en la moneda en que pagó el comprador; null si Shopify no lo informa."
          }
        },
        "required": [
          "pedidoId",
          "numero",
          "nombre",
          "creadoEn",
          "procesadoEn",
          "actualizadoEn",
          "canceladoEn",
          "motivoCancelacion",
          "cerradoEn",
          "prueba",
          "estadoFinanciero",
          "estadoDespacho",
          "impuestosIncluidos",
          "canal",
          "montos",
          "totalComprador"
        ],
        "additionalProperties": false
      },
      "description": "Pedidos de esta página, sin datos de clientes."
    },
    "siguientePagina": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 4096
        },
        {
          "type": "null"
        }
      ],
      "description": "Pásalo en `pagina` para la página siguiente; null si no hay más."
    },
    "historial": {
      "type": "object",
      "properties": {
        "completo": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "description": "true si la tienda concedió `read_all_orders` y se ve todo el historial; false si solo se ven los últimos 60 días; null si Shopify no informó los permisos."
        },
        "diasDisponibles": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ],
          "description": "60 cuando el historial está limitado; null en otro caso."
        }
      },
      "required": [
        "completo",
        "diasDisponibles"
      ],
      "additionalProperties": false,
      "description": "Cuánto historial de pedidos alcanza esta conexión según los permisos concedidos en Shopify."
    }
  },
  "required": [
    "pedidos",
    "siguientePagina",
    "historial"
  ],
  "additionalProperties": false
}

Errores de esta tool

Código	HTTP	Reintentable	Qué hacer
`connection_disabled`	403	no	Reactívala en /connections o usa otra conexión del mismo sistema.
`connection_not_found`	404	no	Usa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada.
`connection_credential_required`	428	no	Crea un enlace con conexiones.enlace.crear (modo reconectar si la conexión ya existe) y pide a la persona que entregue la credencial de nuevo. No reintentes con la credencial anterior.
`connection_busy`	409	sí	Espera unos segundos y reintenta. Es una espera transitoria: no necesitas volver a conectar ni ingresar la credencial otra vez.
`upstream_error`	502	sí	Reintenta más tarde. Si persiste, el problema está en el sistema externo, no en tu integración.
`timeout`	504	sí	Reintenta. Para sincronizaciones largas usa la vía asíncrona y consulta el estado del trabajo.
`connector_onboarding_required`	428	no	Lee el mensaje: dice qué falta. Se completa en el portal de ese sistema, no en Connect, y después la llamada funciona sin cambios.
`connection_scope_not_enabled`	403	no	Pide a un owner/admin que habilite el scope en /connections para esa conexión, o usa otra que ya lo tenga activo. Cambiar la credencial del actor no resuelve este error.
`rate_limited`	429	sí	Espera y reintenta con backoff exponencial.
`upstream_unexpected_response`	502	no	No reintentes: la respuesta es determinista. Repórtalo con el request_id para que actualicemos el conector.
`external_resource_not_found`	404	no	Verifica el identificador con la tool de búsqueda del mismo sistema. Reintentar con el mismo identificador da el mismo resultado.

Toda llamada puede devolver además los códigos transversales (validation_error, unauthorized, scope_not_granted, rate_limited, entre otros): el detalle vive en el catálogo de errores.

Listar pedidos de Shopify

Qué hace

Entrada

Ejemplo

Salida

Errores de esta tool

En esta página