Actividad, exportación y sincronización

Audita quién hizo qué sobre un pedido, exporta datos masivos a CSV para reportería y fuerza una sincronización contra los canales conectados.

URL base

https://api.fenicia.io

Todos los endpoints requieren Authorization: Bearer fkapi_....

Historial de actividad de un pedido

Devuelve la traza cronológica del pedido: eventos de creación, transiciones de estado, envíos, cancelaciones, reembolsos, etc. Requiere orders:read.

orderIdstringrequired

ID del pedido (path).

limitnumber

Número máximo de entradas por página. Default: 50.

offsetnumber

Número de entradas a saltar desde el inicio. Default: 0.

200

{
  "data": {
    "entries": [
      {
        "id": "act_65f3a1b2c4d5e6f7a8b9c0f1",
        "eventType": "status_changed",
        "source": "api",
        "timestamp": "2026-04-10T14:30:00.000Z",
        "userId": "usr_123",
        "userName": "María López",
        "userEmail": "maria@merchant.example.com",
        "userRole": "admin",
        "details": { "fromStatus": "accepted", "toStatus": "preparing" }
      },
      {
        "id": "act_65f3a1b2c4d5e6f7a8b9c0f0",
        "eventType": "order_accepted",
        "source": "system",
        "timestamp": "2026-04-10T13:10:00.000Z"
      }
    ],
    "totalCount": 14,
    "hasMore": true,
    "pagination": { "limit": 50, "offset": 0, "nextOffset": 50 }
  }
}

Shape real de una entrada

Cada entrada es { id?, timestamp, eventType, source, details?, userId?, userName?, userEmail?, userRole?, quotaImpact? }. El campo del evento es eventType, no action; los datos de la transición (por ejemplo fromStatus/toStatus) van dentro de details cuando aplican, no como campos de primer nivel.

curl "https://api.fenicia.io/orders/65f3a1b2c4d5e6f7a8b9c0d1/activity-log?limit=100&offset=0" \
  -H "Authorization: Bearer fkapi_tu_api_key"

Tip

Para paginar hacia adelante usa pagination.nextOffset como el próximo offset. Cuando hasMore es false, ya no hay más entradas.

Exportar pedidos a CSV

Exporta los pedidos que cumplen los filtros a un archivo CSV. Requiere orders:export.

columnsstringrequired

Lista separada por comas con las rutas de columnas a incluir. Soporta rutas anidadas, ej. customerInfo.email.

localestring

Locale usado para formatear valores en el CSV. Default: es.

maxRecordsnumber

Número máximo de registros a exportar. Default: 10000.

startDatestring

Fecha ISO de inicio del rango (inclusiva).

endDatestring

Fecha ISO de fin del rango (inclusiva).

orderStatusstring

Filtra por estado del pedido. También acepta el alias status.

channelIdsstring

Filtra por uno o varios canales.

metafieldsstring

Filtro adicional por metafields, en formato JSON.

200El resto de los filtros de listado (ver Listar pedidos) también aplica a este endpoint.

Content-Type: text/csv
Content-Disposition: attachment; filename="pedidos-2026-04-11.csv"
 
externalId,customerInfo.email,total,orderStatus
1001,ana@example.com,1500.00,accepted
1002,luis@example.com,780.50,fulfilled

No existe el parámetro format

Este endpoint siempre devuelve CSV crudo (Content-Type: text/csv), nunca JSON. No hay un parámetro format para elegir otra salida — si lo envías, se ignora. columns es obligatorio: sin él, la API responde con un error de validación.

El rango de fechas usa startDate / endDate, no from / to

Este endpoint reutiliza el mismo normalizador de filtros que GET /orders (ver Listar pedidos). El rango de fechas se filtra con startDate y endDate — los nombres from/to no existen en esta API.

curl "https://api.fenicia.io/orders/export?columns=externalId,customerInfo.email,total,orderStatus&startDate=2026-04-01&endDate=2026-04-30" \
  -H "Authorization: Bearer fkapi_tu_api_key" \
  -o pedidos.csv

Listar pedidos con liquidación vencida

Lista paginada de pedidos cuya liquidación (settlement) del canal está vencida más allá del periodo de gracia configurado. Requiere orders:read.

pagenumber

Número de página.

limitnumber

Elementos por página.

gracePeriodDaysnumber

Días de gracia antes de considerar una liquidación vencida.

channelIdstring

Filtra por canal.

startDatestring

Fecha ISO de inicio del rango (inclusiva).

endDatestring

Fecha ISO de fin del rango (inclusiva).

200

{
  "data": [
    {
      "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
      "externalId": "FEN-10042",
      "channelId": "chn_shopify_01",
      "orderStatus": "delivered",
      "total": 1986.26
    }
  ],
  "meta": {
    "pagination": { "page": 0, "limit": 20, "total": 6, "totalPages": 1, "hasMore": false }
  }
}

Endpoint sin documentación previa

Este endpoint existe y funciona en la API pública, pero no tenía documentación hasta esta página. A diferencia del listado de carritos abandonados, sigue el envelope estándar del dominio: { data: [...], meta: { pagination } }.

Exportar pedidos con liquidación vencida

Exporta a CSV los pedidos con liquidación vencida, con los mismos filtros que el listado. Requiere orders:export.

gracePeriodDaysnumber

Días de gracia antes de considerar una liquidación vencida.

channelIdstring

Filtra por canal.

startDatestring

Fecha ISO de inicio del rango (inclusiva).

endDatestring

Fecha ISO de fin del rango (inclusiva).

200Análogo a GET /orders/export.

Content-Type: text/csv
Content-Disposition: attachment; filename="liquidacion-vencida-2026-04-11.csv"

Endpoint sin documentación previa

Igual que GET /orders/settlement-overdue, este endpoint existe y funciona pero no tenía documentación hasta esta página.

Sincronizar todos los pedidos

Encola una sincronización asíncrona de pedidos desde todos los canales conectados y activos. Requiere orders:manage.

{}

202

{
  "data": {
    "message": "Sync initiated",
    "status": "processing",
    "channelCount": 4
  }
}

No requiere cuerpo; el mensaje viaja en inglés

Este endpoint no lee ningún campo del body — envía {} o ningún cuerpo, es indistinto. La respuesta real trae channelCount (número de canales encolados), no channelsQueued, y el campo message es literalmente "Sync initiated" (en inglés, tal cual lo devuelve el handler) — no lo traduzcas al mostrarlo a tu usuario final sin antes confirmar que es un valor de datos, no una clave i18n. También incluye siempre status: "processing".

curl -X POST https://api.fenicia.io/orders/sync \
  -H "Authorization: Bearer fkapi_tu_api_key"

Sincronizar un pedido

Fuerza la sincronización de un pedido específico contra su canal de origen. Requiere orders:manage.

orderIdstringrequired

ID del pedido.

{}

202

{
  "data": {
    "message": "Order sync initiated",
    "status": "processing",
    "orderId": "65f3a1b2c4d5e6f7a8b9c0d1"
  }
}

404

{ "error": { "code": "sync:channel_not_found", "message": "Cannot sync order 65f3a1b2c4d5e6f7a8b9c0d1" } }

curl -X POST https://api.fenicia.io/orders/65f3a1b2c4d5e6f7a8b9c0d1/sync \
  -H "Authorization: Bearer fkapi_tu_api_key"

Tip

Ambos endpoints de sincronización son asíncronos. Suscríbete al webhook order.updated o vuelve a consultar GET /orders/{orderId} para detectar cuándo termina.

Errores

Código	Status	Descripción
`orders:not_found`	404	No existe un pedido con ese ID en tu tenant.
`sync:channel_not_found`	404	El canal a sincronizar no existe o no pertenece al tenant.
`sync:channel_disabled`	409	El canal existe pero está deshabilitado.
`sync:integration_error`	502	La integración del canal devolvió un error al sincronizar.
`sync:rate_limited`	429	Se alcanzó el límite de sincronizaciones permitidas en la ventana actual.
`validation:invalid_pagination`	400	`page`, `limit` u `offset` tienen un valor fuera de rango.
`validation:invalid_date_range`	400	`startDate` es posterior a `endDate`.
`auth:invalid_token`	401	La API key es inválida o fue revocada.
`auth:permission_denied`	403	La API key no tiene el permiso requerido (`orders:read`, `orders:export` u `orders:manage` según el endpoint).