Autenticación

Todas las requests autenticadas a Pickwise Public API usan Bearer tokens (API Keys) en el header Authorization. Cada key tiene permisos granulares asignados al momento de emitirla.

Formato de la API Key

pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefijo pk_live_ identifica que es una key productiva
• El resto son caracteres aleatorios (40 chars)
• Inmutable — si necesitás rotarla, Pickwise emite una nueva y desactiva la anterior

Usar la API Key

Incluir el header Authorization: Bearer <TU_API_KEY> en cada request.

curl

curl https://api-{CLIENTE}.pickwise.com.ar/api/v1/public/products \
  -H "Authorization: Bearer pk_live_xxxx"

Node.js

const res = await fetch('https://api-{CLIENTE}.pickwise.com.ar/api/v1/public/products', {
  headers: {
    'Authorization': `Bearer ${process.env.PICKWISE_API_KEY}`
  }
});

PHP

<?php
$apiKey = getenv('PICKWISE_API_KEY');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . $apiKey
]);

Permisos granulares

Cada API Key tiene un subset de los siguientes permisos:

Permiso	Qué permite
products:read	GET /products, GET /products/{externalId}
products:write	POST /products, POST /products/batch
orders:read	GET /orders, GET /orders/{externalId}
orders:write	POST /orders, POST /orders/batch, POST /orders/{externalId}/cancel
webhooks:manage	Todo el CRUD de webhooks

El endpoint GET /health no requiere ningún permiso (ni siquiera key).

Errores de autenticación

401 Unauthorized

Tu request no incluye una API Key válida.

Causas posibles:

• Header Authorization ausente
• Formato incorrecto (ej: Authorization: pk_live_... sin Bearer )
• Key inválida o revocada
• Key expirada

Ejemplo de respuesta:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API Key inválida o ausente."
  },
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

403 Forbidden

Tu API Key es válida, pero no tiene el permiso requerido para ese endpoint.

Ejemplo: intentás hacer POST /products pero tu key solo tiene products:read.

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Tu API Key no tiene el permiso products:write."
  },
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Si recibís 403 sistemáticamente, contactá a soporte para revisar los permisos asignados.

Buenas prácticas de seguridad

Nunca committear keys

No commitear API Keys en el repositorio. Usá variables de entorno o un secret manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, etc.).

Separá keys por ambiente

Usá keys distintas para cada ambiente (dev, staging, producción). Si una se filtra, limitás el blast radius.

Rotá las keys periódicamente

Recomendado cada 90 días. Contactá a soporte para emitir una nueva key — Pickwise deja la anterior activa 24h para facilitar el cutover sin downtime.

IP allowlist (opcional)

Si tu integración corre desde IPs estáticas conocidas, podés pedir a Pickwise que restrinja tu API Key a un rango específico de IPs. Esto mitiga el impacto si la key se filtra.

Requests desde IPs no permitidas reciben 403 IP_NOT_ALLOWED.

Para habilitarlo, contactá a soporte@lubee.com.ar con la lista de IPs a permitir.

Siguiente paso

Rate limiting Cuántas requests por minuto permite cada API Key.

Manejo de errores Formato estándar de errores y códigos de error.