API v1

API para Desarrolladores

Integra tu tienda Pidefy con sistemas externos: ERP, inventario, apps móviles y más.

Base URL: https://pidefy.com/api/v1

Autenticación

La API soporta dos métodos. Usa el que mejor se adapte a tu integración.

1. JWT Token

Recomendado para sesiones cortas. El token expira en 24 horas.

Obtén un token con tus credenciales de Pidefy:

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-03-13T19:00:00.000Z",
    "tenant": {
      "id": "abc123",
      "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..."

2. API Key

Recomendado para integraciones permanentes. Crea una key desde el dashboard en Llaves de API. Solo se muestra una vez.

bash

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

Scopes disponibles:

Scope	Descripción
`products:read`	Leer productos
`products:write`	Crear, editar y eliminar productos

Formato de respuesta

Todas las respuestas siguen la misma estructura:

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": "Fields name, price, purchasePrice, and stock are required"
  }
}

Códigos de error

Código	HTTP	Descripción
`UNAUTHORIZED`	401	Token o API Key inválido o ausente
`FORBIDDEN`	403	Scopes insuficientes para esta operación
`NOT_FOUND`	404	Recurso no encontrado
`VALIDATION_ERROR`	400	Datos inválidos en el request
`TENANT_NOT_FOUND`	404	Tienda no encontrada
`INVALID_CREDENTIALS`	401	Email o contraseña incorrectos
`NO_TENANT`	404	No hay tienda asociada a esta cuenta

Productos

GET/api/v1/products

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	Buscar por nombre de producto
`categoryId`	string	Filtrar por categoría (incluye subcategorías)
`tag`	string	Filtrar por tag

Ejemplo:

bash

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

Respuesta:

json

{
  "data": [
    {
      "_id": "abc123",
      "name": "Camisa Negra",
      "price": 25.00,
      "purchasePrice": 12.00,
      "stock": 50,
      "tags": ["camisa", "negro"],
      "image": "/uploads/camisa.jpg",
      "isActive": true,
      "categoryId": "cat456",
      "createdAt": "2026-03-01T10:00:00.000Z"
    }
  ],
  "meta": { "total": 45, "page": 1, "totalPages": 5 },
  "error": null
}

GET/api/v1/products/:id

Obtiene un producto por su ID.

Scope requerido: products:read

bash

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

POST/api/v1/products

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

Scope requerido: products:write

Body (JSON):

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
`description`	string	Descripción del producto
`image`	string	URL de la imagen
`categoryId`	string	ID de la categoría
`brandId`	string	ID de la marca
`tags`	string[]	Tags del producto
`isActive`	boolean (default: true)	Visible en la tienda
`sizes`	string[]	Tallas disponibles
`colors`	string[]	Colores disponibles

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.00,
    "purchasePrice": 7.00,
    "stock": 100,
    "tags": ["franela", "básico"],
    "sizes": ["S", "M", "L", "XL"]
  }'

PUT/api/v1/products/:id

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

Scope requerido: products:write

bash

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

DELETE/api/v1/products/:id

Elimina un producto y todo su stock de sucursales.

Scope requerido: products:write

bash

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

Respuesta:

json

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

Ejemplo completo

Flujo completo: autenticar, listar, crear, actualizar y eliminar un producto.

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. Listar productos
curl -s https://pidefy.com/api/v1/products \
  -H "Authorization: Bearer $TOKEN" | jq

# 3. Crear producto
curl -s -X POST https://pidefy.com/api/v1/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Producto Nuevo",
    "price": 20.00,
    "purchasePrice": 10.00,
    "stock": 50
  }' | jq

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

# 5. Eliminar producto
curl -s -X DELETE https://pidefy.com/api/v1/products/PRODUCT_ID \
  -H "Authorization: Bearer $TOKEN" | jq