Los adjuntos de pedido te permiten asociar archivos a un pedido: facturas, CFDI XML/PDF, guías de envío o cualquier documento personalizado. Los archivos se almacenan en S3 y se acceden mediante URLs prefirmadas de corta duración.
https://api.fenicia.ioTodos los endpoints requieren Authorization: Bearer fn_live_....
| Tipo | Descripción |
|---|---|
invoice | Factura comercial (PDF) |
cfdi | CFDI XML / PDF (comprobante fiscal mexicano) |
shipping_guide | Etiqueta / guía de envío del transportista |
custom | Cualquier otro documento |
Las subidas usan un flujo de tres pasos con URL prefirmada, de modo que los archivos viajan directamente a S3 sin pasar por los servidores de Fenicia.
Llama a POST /orders/{id}/attachments/upload-url. Recibirás una uploadUrl (válida 15 minutos) y un s3Key.
Sube los bytes del archivo directamente a la uploadUrl usando exactamente el Content-Type declarado.
Llama a POST /orders/{id}/attachments con el s3Key para registrar el adjunto en el pedido.
Lista todos los adjuntos asociados a un pedido. Requiere orders:read.
curl https://api.fenicia.io/orders/ord_123/attachments \
-H "Authorization: Bearer fn_live_tu_api_key"Devuelve una URL prefirmada de S3 de corta duración para descargar el archivo. Requiere orders:read.
curl https://api.fenicia.io/orders/ord_123/attachments/att_01HXYZ \
-H "Authorization: Bearer fn_live_tu_api_key"Solicita una URL prefirmada de S3 para subir un nuevo adjunto. Requiere orders:update.
Registra el adjunto después de subirlo a S3. Requiere orders:update.
# 1. Solicitar URL prefirmada
RESP=$(curl -s -X POST https://api.fenicia.io/orders/ord_123/attachments/upload-url \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"type":"invoice","filename":"factura-1001.pdf","contentType":"application/pdf"}')
UPLOAD_URL=$(echo $RESP | jq -r .uploadUrl)
S3_KEY=$(echo $RESP | jq -r .s3Key)
# 2. Subir el archivo a S3
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: application/pdf" \
--data-binary @factura-1001.pdf
# 3. Confirmar la subida
curl -X POST https://api.fenicia.io/orders/ord_123/attachments \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d "{\"s3Key\":\"$S3_KEY\",\"type\":\"invoice\",\"filename\":\"factura-1001.pdf\",\"contentType\":\"application/pdf\"}"Elimina un adjunto del pedido. El objeto en S3 también se elimina. Requiere orders:update.
curl -X DELETE https://api.fenicia.io/orders/ord_123/attachments/att_01HXYZ \
-H "Authorization: Bearer fn_live_tu_api_key"Las URLs prefirmadas expiran
Tanto las URLs de subida como las de descarga expiran en 15 minutos (expiresIn: 900). Solicita una nueva URL si la anterior ya expiró — no las almacenes a largo plazo.
Tip
Usa siempre el mismo contentType declarado en /upload-url cuando hagas PUT a S3. Si no coincide, S3 rechazará la subida con SignatureDoesNotMatch.