API v1

Conecta tu tienda con lo que ya usas

Sincroniza productos, categorías, pedidos e inventario con tu ERP, tu punto de venta o la app que estés construyendo.

Base URLhttps://pidefy.com/api/v1

Autenticación

Hay dos formas de identificarte. Elige según el tipo de integración que estés haciendo.

1. Token JWT

Para scripts y sesiones cortas. El token dura 24 horas y tiene acceso completo a tu tienda: no está limitado por scopes.

bash

curl -X POST https://pidefy.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "tu@email.com",
    "password": "tu-password"
  }'

Respuesta

json

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresAt": "2026-07-23T19:00:00.000Z",
    "tenant": {
      "id": "6659a0d1c2b81e0012a3f4c9",
      "name": "Mi Tienda",
      "slug": "mi-tienda"
    }
  },
  "meta": null,
  "error": null
}

Luego usa el token en tus peticiones:

bash

curl https://pidefy.com/api/v1/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Existe también POST /api/v1/auth/login, que devuelve lo mismo más el perfil del usuario y el logo de la tienda. Es el que usa la app de Pidefy.

2. API Key

Para integraciones permanentes. Sigue funcionando hasta que la revoques y la limitas a los permisos que necesite tu integración.

bash

curl https://pidefy.com/api/v1/products \
  -H "X-Api-Key: pk_live_abc123..."

Las API Keys son parte del plan Negocio y se habilitan por solicitud. Escríbenos desde contacto y te la entregamos. La key completa se muestra una sola vez: guárdala apenas la recibas.

Scopes

Cada API Key lleva la lista de permisos que puede usar. Si le falta uno, la petición responde 403.

Scope	Permite
`products:read`	Leer productos
`products:write`	Crear, editar y eliminar productos
`categories:read`	Leer categorías
`categories:write`	Crear, editar y eliminar categorías
`orders:read`	Leer pedidos
`orders:write`	Crear pedidos y actualizar su estado
`customers:read`	Leer clientes
`coupons:read`	Validar cupones antes de cobrar
`store:read`	Leer los datos de la tienda
`store:write`	Editar los datos de la tienda
`analytics:read`	Leer ventas y visitas
`dashboard:read`	Leer el resumen del dashboard
`files:write`	Subir imágenes
`me:read`	Leer el perfil del usuario (solo con JWT)
`me:write`	Editar o eliminar la cuenta (solo con JWT)

Formato de respuesta

Todas las respuestas traen las mismas tres llaves, salga bien o salga mal.

Respuesta exitosa

json

{
  "data": { ... },
  "meta": { "total": 50, "page": 1, "totalPages": 5 },
  "error": null
}

Respuesta con error

json

{
  "data": null,
  "meta": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Los campos name, price, purchasePrice y stock son requeridos"
  }
}

meta es null salvo en los listados, donde trae total, page y totalPages. En el listado de pedidos también trae counts por estado.

Los mensajes de error vienen en español, listos para mostrarle al usuario.

Códigos de error

Usa el campo code para reaccionar en tu integración, no el mensaje: el texto puede cambiar.

Código	HTTP	Cuándo aparece
`UNAUTHORIZED`	401	Autenticación faltante o inválida
`INVALID_CREDENTIALS`	401	Email o contraseña incorrectos
`FORBIDDEN`	403	No tienes permisos para realizar esta acción
`RATE_LIMITED`	429	Superaste el límite de peticiones por minuto
`VALIDATION_ERROR`	400	Datos inválidos en el request
`NOT_FOUND`	404	Recurso no encontrado
`TENANT_NOT_FOUND`	404	Tienda no encontrada
`NO_TENANT`	404	No hay una tienda asociada a esta cuenta
`FETCH_ERROR`	500	No se pudo cargar la información
`CREATE_ERROR`	500	No se pudo crear el registro
`UPDATE_ERROR`	500	No se pudieron guardar los cambios
`DELETE_ERROR`	500	No se pudo eliminar el registro
`UPLOAD_ERROR`	500	No se pudo subir el archivo
`INTERNAL_ERROR`	500	Algo salió mal. Intenta de nuevo

Cada credencial tiene su propio límite de 120 peticiones por minuto, así que una segunda key no compite con la primera. Al pasarte recibes un 429 con la cabecera Retry-After, que te dice cuántos segundos esperar antes de reintentar. Tómalo como un mínimo garantizado y no como un tope exacto: el conteo es por servidor, así que en horas de mucho tráfico puedes llegar un poco más lejos antes de que te frenemos.

Productos

Tu catálogo. Los precios van en la moneda que tengas configurada en la tienda.

GET/api/v1/products

Listar productos

Lista los productos de tu tienda con paginación y filtros.

Scope requerido: products:read

Parámetros de query

Parámetro	Tipo	Descripción
`page`	number (default: 1)	Número de página
`limit`	number (default: 50)	Resultados por página (máx. 100)
`search`	string	Busca por nombre de producto
`categoryId`	string	Filtra por una categoría de tu tienda
`tag`	string	Filtra por tag

El filtro categoryId hace coincidencia exacta contra categoryIds. No incluye categorías hijas.

Ejemplo

bash

curl "https://pidefy.com/api/v1/products?page=1&limit=10&search=camisa" \
  -H "Authorization: Bearer TOKEN"

Respuesta

json

{
  "data": [
    {
      "_id": "6659a1f4c2b81e0012a3f4d1",
      "name": "Camisa Negra",
      "price": 25,
      "purchasePrice": 12,
      "stock": 50,
      "image": "https://cdn.pidefy.com/images/camisa.jpg",
      "images": [],
      "barcode": "7591234567890",
      "categoryIds": ["6659a2b0c2b81e0012a3f4e7"],
      "tags": ["camisa", "negro"],
      "sizes": ["S", "M", "L"],
      "colors": [{ "name": "Negro", "hex": "#000000" }],
      "variants": [
        { "size": "S", "color": "Negro", "stock": 20 },
        { "size": "M", "color": "Negro", "stock": 30 }
      ],
      "tenantId": "6659a0d1c2b81e0012a3f4c9",
      "createdAt": "2026-07-01T10:00:00.000Z",
      "updatedAt": "2026-07-01T10:00:00.000Z"
    }
  ],
  "meta": { "total": 45, "page": 1, "totalPages": 5 },
  "error": null
}

GET/api/v1/products/:id

Obtener producto

Devuelve un producto por su ID.

Scope requerido: products:read

Ejemplo

bash

curl https://pidefy.com/api/v1/products/6659a1f4c2b81e0012a3f4d1 \
  -H "Authorization: Bearer TOKEN"

POST/api/v1/products

Crear producto

Crea un producto nuevo. Responde 201.

Scope requerido: products:write

Body

Parámetro	Tipo	Descripción
`name`requerido	string	Nombre del producto
`price`requerido	number	Precio de venta
`purchasePrice`requerido	number	Precio de compra
`stock`requerido	number	Cantidad en inventario
`image`	string	URL de la imagen principal
`images`	string[]	URLs de imágenes adicionales
`barcode`	string	Código de barras
`categoryIds`	string[]	IDs de categorías de tu tienda
`tags`	string[]	Tags del producto
`sizes`	string[]	Tallas disponibles
`colors`	{ name, hex }[]	Colores disponibles, con su código hex
`variants`	{ size, color, stock }[]	Stock por combinación de talla y color
`metadata`	object	Datos libres para tu integración

Si mandas variants, el stock de cada combinación manda: el campo stock del producto pasa a ser la suma y se calcula solo.

Cada talla y cada color que uses en variants tiene que estar también en sizes y colors, o la combinación no se podría comprar.

Si no mandas variants, el producto sigue funcionando con un solo stock, como siempre.

Si tu tienda tiene sucursales, el stock se inicializa automáticamente en todas.

Cualquier campo que no esté en esta tabla se descarta en silencio.

Ejemplo

bash

curl -X POST https://pidefy.com/api/v1/products \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Franela Básica",
    "price": 15,
    "purchasePrice": 7,
    "stock": 100,
    "tags": ["franela", "básico"],
    "sizes": ["S", "M", "L", "XL"],
    "colors": [
      { "name": "Blanco", "hex": "#FFFFFF" },
      { "name": "Negro", "hex": "#000000" }
    ]
  }'

PUT/api/v1/products/:id

Actualizar producto

Actualiza un producto. Envía solo los campos que quieres modificar.

Scope requerido: products:write

Los campos tenantId y createdBy se ignoran aunque los envíes.

Ejemplo

bash

curl -X PUT https://pidefy.com/api/v1/products/6659a1f4c2b81e0012a3f4d1 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 18,
    "stock": 75
  }'

DELETE/api/v1/products/:id

Eliminar producto

Elimina el producto y todo su stock de sucursales.

Scope requerido: products:write

Ejemplo

bash

curl -X DELETE https://pidefy.com/api/v1/products/6659a1f4c2b81e0012a3f4d1 \
  -H "Authorization: Bearer TOKEN"

Respuesta

json

{
  "data": { "deleted": true },
  "meta": null,
  "error": null
}

Categorías

Las categorías son propias de cada tienda y son las que ve el cliente en tu catálogo. El slug se genera solo a partir del nombre.

GET/api/v1/categories

Listar categorías

Devuelve todas tus categorías, ordenadas por el campo order.

Scope requerido: categories:read

Ejemplo

bash

curl https://pidefy.com/api/v1/categories \
  -H "Authorization: Bearer TOKEN"

Respuesta

json

{
  "data": [
    {
      "_id": "6659a2b0c2b81e0012a3f4e7",
      "tenantId": "6659a0d1c2b81e0012a3f4c9",
      "name": "Camisas",
      "slug": "camisas",
      "image": "https://cdn.pidefy.com/images/camisas.jpg",
      "order": 0,
      "isActive": true,
      "createdAt": "2026-07-01T10:00:00.000Z",
      "updatedAt": "2026-07-01T10:00:00.000Z"
    }
  ],
  "meta": { "total": 1 },
  "error": null
}

POST/api/v1/categories

Crear categoría

Crea una categoría. Responde 201.

Scope requerido: categories:write

Body

Parámetro	Tipo	Descripción
`name`requerido	string	Nombre de la categoría
`image`	string	URL de la imagen de portada
`order`	number (default: 0)	Posición en el catálogo
`isActive`	boolean (default: true)	Visible en la tienda

Si ya tienes una categoría con ese nombre responde 409 VALIDATION_ERROR.

Ejemplo

bash

curl -X POST https://pidefy.com/api/v1/categories \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Camisas", "order": 1 }'

PUT/api/v1/categories/:id

Actualizar categoría

Actualiza nombre, imagen, orden o visibilidad.

Scope requerido: categories:write

Ejemplo

bash

curl -X PUT https://pidefy.com/api/v1/categories/6659a2b0c2b81e0012a3f4e7 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Camisas de vestir", "isActive": false }'

DELETE/api/v1/categories/:id

Eliminar categoría

Elimina la categoría y la quita de todos los productos que la tenían.

Scope requerido: categories:write

Los productos no se eliminan, solo pierden esa categoría.

Ejemplo

bash

curl -X DELETE https://pidefy.com/api/v1/categories/6659a2b0c2b81e0012a3f4e7 \
  -H "Authorization: Bearer TOKEN"

Pedidos

Los pedidos de tu catálogo entran solos. Por la API los consultas, los mueves de estado y registras ventas hechas en persona. Si tienes sucursales, se incluyen sus pedidos.

Estados de un pedido

Estado	Significa
`pending`	Pedido recibido, sin pagar
`payment_pending`	Pago iniciado, esperando confirmación
`paid`	Pago confirmado
`preparing`	En preparación
`shipped`	Enviado
`delivered`	Entregado
`cancelled`	Cancelado

GET/api/v1/orders

Listar pedidos

Lista los pedidos ordenados del más reciente al más antiguo.

Scope requerido: orders:read

Parámetros de query

Parámetro	Tipo	Descripción
`page`	number (default: 1)	Número de página
`limit`	number (default: 20)	Resultados por página (máx. 100)
`status`	string	Filtra por estado (ver tabla de estados)
`search`	string	Busca por nombre, teléfono o número de pedido

El meta incluye counts: cuántos pedidos tienes en cada estado.

Ejemplo

bash

curl "https://pidefy.com/api/v1/orders?status=pending&limit=20" \
  -H "Authorization: Bearer TOKEN"

Respuesta

json

{
  "data": [
    {
      "_id": "6659b3c1c2b81e0012a3f501",
      "orderNumber": 1042,
      "status": "pending",
      "customer": {
        "name": "María Pérez",
        "email": "maria@email.com",
        "phone": "+584121234567",
        "address": "Av. Principal, Caracas"
      },
      "items": [
        {
          "productId": "6659a1f4c2b81e0012a3f4d1",
          "productName": "Camisa Negra",
          "image": "https://cdn.pidefy.com/images/camisa.jpg",
          "quantity": 2,
          "price": 25,
          "subtotal": 50,
          "selectedSize": "M",
          "selectedColor": "Negro"
        }
      ],
      "subtotal": 50,
      "total": 50,
      "paymentMethod": "pago_movil",
      "createdAt": "2026-07-15T14:20:00.000Z"
    }
  ],
  "meta": {
    "total": 128,
    "page": 1,
    "totalPages": 7,
    "counts": { "pending": 12, "paid": 40, "delivered": 76 }
  },
  "error": null
}

GET/api/v1/orders/:id

Obtener pedido

Devuelve un pedido completo.

Scope requerido: orders:read

Si algún item quedó sin imagen, se completa con la imagen actual del producto.

Ejemplo

bash

curl https://pidefy.com/api/v1/orders/6659b3c1c2b81e0012a3f501 \
  -H "Authorization: Bearer TOKEN"

PUT/api/v1/orders/:id

Cambiar estado del pedido

Lo único que se puede actualizar de un pedido es su estado.

Scope requerido: orders:write

Body

Parámetro	Tipo	Descripción
`status`requerido	string	Uno de los estados válidos

Ejemplo

bash

curl -X PUT https://pidefy.com/api/v1/orders/6659b3c1c2b81e0012a3f501 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "shipped" }'

POST/api/v1/orders

Registrar una venta

Registra una venta hecha en persona. Queda como pagada, descuenta stock y no te manda notificación, porque la venta la hiciste tú.

Scope requerido: orders:write

Body

Parámetro	Tipo	Descripción
`items`requerido	object[]	Cada item con productId y quantity. Opcionalmente selectedSize y selectedColor
`paymentMethod`requerido	string	Cómo te pagaron
`paymentReference`	string	Referencia del pago
`customer`	object	name, phone y email. Si no lo mandas, la venta queda como Cliente ocasional
`coupon`	object	Con code para aplicar un descuento

Los precios salen de tu catálogo: lo que mandes como precio se ignora.

Si algún producto no tiene stock responde 409 INSUFFICIENT_STOCK y no se crea nada.

Estas ventas quedan con channel "pos". Sin datos del cliente no aparecen en tu lista de clientes.

Ejemplo

bash

curl -X POST https://pidefy.com/api/v1/orders \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "productId": "6659a1f4c2b81e0012a3f4d1", "quantity": 2, "selectedSize": "M" }],
    "paymentMethod": "cash",
    "customer": { "name": "María Pérez", "phone": "04121234567" }
  }'

Clientes

Tus clientes salen de los pedidos: no hay que crearlos. Se agrupan por teléfono, se excluyen los pedidos cancelados y las ventas de mostrador sin datos del cliente. Si tienes sucursales, se incluyen sus clientes.

GET/api/v1/customers

Listar clientes

Lista tus clientes del que compró más recientemente al que hace más tiempo no compra.

Scope requerido: customers:read

Parámetros de query

Parámetro	Tipo	Descripción
`page`	number (default: 1)	Número de página
`limit`	number (default: 20)	Resultados por página (máx. 100)
`search`	string	Busca por nombre, teléfono o correo
`minOrders`	number (default: 1)	Solo clientes con al menos esta cantidad de pedidos
`inactiveDays`	number	Solo clientes que llevan al menos estos días sin comprar

totalSpent suma el total de todos los pedidos no cancelados del cliente.

daysSinceLastPurchase se calcula al momento de la consulta.

Ejemplo

bash

curl "https://pidefy.com/api/v1/customers?minOrders=2&limit=20" \
  -H "Authorization: Bearer TOKEN"

Respuesta

json

{
  "data": [
    {
      "phone": "+584121234567",
      "name": "María Pérez",
      "email": "maria@email.com",
      "totalOrders": 3,
      "totalSpent": 145,
      "lastPurchase": "2026-06-10T14:20:00.000Z",
      "firstPurchase": "2026-01-08T09:05:00.000Z",
      "daysSinceLastPurchase": 47
    }
  ],
  "meta": {
    "total": 84,
    "page": 1,
    "totalPages": 5
  },
  "error": null
}

GET/api/v1/customers/:phone

Obtener cliente

Devuelve el resumen de un cliente y sus pedidos, del más reciente al más antiguo. El teléfono va tal como aparece en la lista de clientes, codificado para la URL.

Scope requerido: customers:read

Parámetros de query

Parámetro	Tipo	Descripción
`page`	number (default: 1)	Número de página de los pedidos
`limit`	number (default: 10)	Pedidos por página (máx. 100)

Los pedidos incluyen los cancelados; el resumen no los cuenta.

Si el cliente no tiene pedidos responde 404 NOT_FOUND.

Ejemplo

bash

curl "https://pidefy.com/api/v1/customers/%2B584121234567" \
  -H "Authorization: Bearer TOKEN"

Respuesta

json

{
  "data": {
    "customer": {
      "phone": "+584121234567",
      "name": "María Pérez",
      "email": "maria@email.com",
      "totalOrders": 3,
      "totalSpent": 145,
      "lastPurchase": "2026-06-10T14:20:00.000Z",
      "firstPurchase": "2026-01-08T09:05:00.000Z"
    },
    "orders": [
      {
        "_id": "6659b3c1c2b81e0012a3f501",
        "orderNumber": 1042,
        "status": "delivered",
        "total": 50,
        "createdAt": "2026-06-10T14:20:00.000Z"
      }
    ]
  },
  "meta": { "total": 3, "page": 1, "totalPages": 1 },
  "error": null
}

Cupones

Los cupones se crean y editan desde tu panel. Por la API los validas antes de cobrar, para saber cuánto descontar y mostrarle el total correcto al cliente.

POST/api/v1/coupons/validate

Validar cupón

Comprueba si un cupón se puede aplicar a un subtotal y devuelve el descuento. No consume un uso del cupón: eso ocurre al crear el pedido.

Scope requerido: coupons:read

Body

Parámetro	Tipo	Descripción
`code`requerido	string	Código del cupón
`subtotal`requerido	number	Subtotal sobre el que se calcula
`customerPhone`	string	Necesario para los cupones de bienvenida (primera compra)
`customerEmail`	string	Alternativa al teléfono

Si el cupón no aplica responde 400 INVALID_COUPON y el mensaje explica por qué (expirado, no alcanza el mínimo, ya usado).

Ejemplo

bash

curl -X POST https://pidefy.com/api/v1/coupons/validate \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code": "BIENVENIDO10", "subtotal": 50 }'

Respuesta

json

{
  "data": {
    "code": "BIENVENIDO10",
    "type": "percentage",
    "value": 10,
    "discountAmount": 5,
    "total": 45
  },
  "meta": null,
  "error": null
}

Tienda

Los datos públicos de tu tienda: identidad, métodos de pago y opciones de entrega.

GET/api/v1/store

Obtener tienda

Devuelve la configuración completa de tu tienda.

Scope requerido: store:read

Ejemplo

bash

curl https://pidefy.com/api/v1/store \
  -H "Authorization: Bearer TOKEN"

PUT/api/v1/store

Actualizar tienda

Actualiza los datos de tu tienda. Envía solo lo que quieras cambiar.

Scope requerido: store:write

Body

Parámetro	Tipo	Descripción
`name`	string	Nombre de la tienda
`logo`	string	URL del logo
`banner`	string	URL del banner
`whatsapp`	string	Número de WhatsApp de contacto
`slogan`	string	Frase corta de la tienda
`description`	string	Descripción de la tienda
`valueProposition`	string	Propuesta de valor
`theme`	object	Colores y tipografía del catálogo
`paymentMethods`	string[]	Formas de cobro activas de la tienda
`paymentMethodDetails`	object	Datos de cada método de pago
`socialMedia`	object	Redes sociales de la tienda
`customTags`	string[]	Tags propios de la tienda
`storeAddress`	object	Dirección física
`deliveryOptions`	object	Opciones y zonas de entrega

Cualquier otro campo se ignora. Si no envías ninguno de estos, responde 400 VALIDATION_ERROR.

Ejemplo

bash

curl -X PUT https://pidefy.com/api/v1/store \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "slogan": "Ropa que dura", "whatsapp": "+584121234567" }'

Analytics

Ventas y visitas de tu tienda. Ambos endpoints aceptan period con los valores today, week o month (por defecto month).

GET/api/v1/analytics/sales

Ventas

Ingresos, pedidos y ticket promedio del período, comparados contra el período anterior.

Scope requerido: analytics:read

Parámetros de query

Parámetro	Tipo	Descripción
`period`	string (default: month)	today, week o month

Los pedidos cancelados no se cuentan.

Ejemplo

bash

curl "https://pidefy.com/api/v1/analytics/sales?period=week" \
  -H "Authorization: Bearer TOKEN"

Respuesta

json

{
  "data": {
    "period": "week",
    "revenue": 1240.5,
    "prevRevenue": 980,
    "orders": 42,
    "prevOrders": 35,
    "avgTicket": 29.54,
    "prevAvgTicket": 28,
    "dailyRevenue": [{ "label": "lun", "value": 180 }],
    "topProducts": [
      { "name": "Camisa Negra", "units": 24, "revenue": 600 }
    ],
    "paymentBreakdown": [
      { "method": "pago_movil", "amount": 900.5 }
    ]
  },
  "meta": null,
  "error": null
}

GET/api/v1/analytics/visits

Visitas

Tráfico del catálogo: visitas, visitantes únicos, vistas de producto, carritos, checkouts y clics a WhatsApp.

Scope requerido: analytics:read

Parámetros de query

Parámetro	Tipo	Descripción
`period`	string (default: month)	today, week o month

Ejemplo

bash

curl "https://pidefy.com/api/v1/analytics/visits?period=month" \
  -H "Authorization: Bearer TOKEN"

Respuesta

json

{
  "data": {
    "period": "month",
    "stats": {
      "totalViews": 3120,
      "uniqueVisitors": 890,
      "productViews": 1450,
      "addToCart": 210,
      "checkouts": 64,
      "whatsappClicks": 128
    },
    "daily": [{ "date": "2026-07-01", "views": 120, "visitors": 45 }],
    "topProducts": [
      {
        "productId": "6659a1f4c2b81e0012a3f4d1",
        "productName": "Camisa Negra",
        "image": "https://cdn.pidefy.com/images/camisa.jpg",
        "views": 340,
        "visitors": 210
      }
    ]
  },
  "meta": null,
  "error": null
}

GET/api/v1/dashboard

Resumen del dashboard

Los cuatro números de cabecera: pedidos de hoy, productos, ventas del mes y visitas de hoy.

Scope requerido: dashboard:read

Ejemplo

bash

curl https://pidefy.com/api/v1/dashboard \
  -H "Authorization: Bearer TOKEN"

Respuesta

json

{
  "data": {
    "ordersToday": 8,
    "productsCount": 132,
    "monthSales": 4210.75,
    "visitsToday": 96
  },
  "meta": null,
  "error": null
}

Archivos

Sube las imágenes antes de crear el producto y usa la URL que te devuelve.

POST/api/v1/upload

Subir imagen

Sube una imagen y devuelve su URL pública. Responde 201.

Scope requerido: files:write

Body

Parámetro	Tipo	Descripción
`file`requerido	file	JPG, PNG, GIF o WEBP. Máximo 10 MB
`folder`	string (default: images)	Carpeta destino

Este endpoint recibe multipart/form-data, no JSON.

Ejemplo

bash

curl -X POST https://pidefy.com/api/v1/upload \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@camisa.jpg" \
  -F "folder=images"

Respuesta

json

{
  "data": {
    "url": "https://cdn.pidefy.com/images/camisa-1721049600.jpg",
    "key": "images/camisa-1721049600.jpg"
  },
  "meta": null,
  "error": null
}

Cuenta

Estos endpoints actúan sobre el usuario dueño del token, así que solo funcionan con JWT. Con API Key responden 403.

GET/api/v1/me

Obtener perfil

Devuelve nombre, email y rol del usuario del token.

Scope requerido: me:read

Ejemplo

bash

curl https://pidefy.com/api/v1/me \
  -H "Authorization: Bearer TOKEN"

PUT/api/v1/me

Actualizar perfil

Cambia el nombre del usuario.

Scope requerido: me:write

Body

Parámetro	Tipo	Descripción
`name`requerido	string	Nuevo nombre

Ejemplo

bash

curl -X PUT https://pidefy.com/api/v1/me \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "María Pérez" }'

DELETE/api/v1/me

Eliminar cuenta

Elimina la cuenta del usuario y sus datos asociados.

Scope requerido: me:write

Esta acción no se puede deshacer. Se elimina la cuenta completa, no solo el acceso por API.

Ejemplo

bash

curl -X DELETE https://pidefy.com/api/v1/me \
  -H "Authorization: Bearer TOKEN"

Ejemplo completo

Cargar un producto de punta a punta: token, categoría, imagen, producto, stock y revisión de pedidos.

bash

# 1. Obtener token
TOKEN=$(curl -s -X POST https://pidefy.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "tu@email.com", "password": "tu-password"}' \
  | jq -r '.data.token')

# 2. Crear la categoría y guardar su ID
CATEGORY_ID=$(curl -s -X POST https://pidefy.com/api/v1/categories \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Franelas"}' | jq -r '.data._id')

# 3. Subir la imagen del producto
IMAGE_URL=$(curl -s -X POST https://pidefy.com/api/v1/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@franela.jpg" | jq -r '.data.url')

# 4. Crear el producto con su categoría e imagen
PRODUCT_ID=$(curl -s -X POST https://pidefy.com/api/v1/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Franela Básica\",
    \"price\": 15,
    \"purchasePrice\": 7,
    \"stock\": 50,
    \"image\": \"$IMAGE_URL\",
    \"categoryIds\": [\"$CATEGORY_ID\"]
  }" | jq -r '.data._id')

# 5. Actualizar el stock
curl -s -X PUT https://pidefy.com/api/v1/products/$PRODUCT_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stock": 40}' | jq

# 6. Revisar los pedidos pendientes
curl -s "https://pidefy.com/api/v1/orders?status=pending" \
  -H "Authorization: Bearer $TOKEN" | jq '.meta.counts'

¿Te falta un endpoint?

Cuéntanos qué necesitas integrar. La API crece según lo que nos piden las tiendas.

Escribirnos