Autenticación

La API pública se autentica con una API key de cuenta. Cada key pertenece a una sola cuenta de Posdata, y la cuenta siempre sale de la key: nunca de un parámetro, del cuerpo ni de la URL.

Cómo enviar la key

Solo en el header Authorization, con el esquema Bearer:

GET /public/v1/me HTTP/1.1
Host: api.posdata.so
Authorization: Bearer pdk_live_…

La API no acepta la key en la URL (?api_key=…): las URLs terminan en logs, historiales y encabezados Referer.

Formato de la key

• Una key de producción llamando a pruebas, o al revés, recibe 401 API_KEY_WRONG_ENVIRONMENT con un mensaje que te dice cuál usar.
• El entorno de pruebas tiene datos de prueba y puede reiniciarse: úsalo para desarrollar, no para guardar información.
• En cuenta.posdata.so → Desarrolladores ves el inicio de cada key (sus primeros caracteres) para reconocerla. Posdata guarda solo una huella (hash) de la key: si la pierdes, no hay forma de recuperarla.

Permisos (scopes)

Cada key tiene una lista de permisos. Marca solo los que tu integración necesita: una key de solo lectura no puede cambiar nada aunque se filtre.

• GET /me funciona con cualquier key válida, sin importar sus permisos.
• Si la key no tiene el permiso de un endpoint, la respuesta es 403 INSUFFICIENT_SCOPE y el error trae required_scope con el permiso que falta. Los permisos de una key no se editan: crea otra con los permisos correctos y revoca la anterior.
• Los permisos :write no incluyen el :read del mismo recurso: si vas a leer y escribir, marca ambos.
• inventory:costs se pide aparte porque un costo es un dato comercial sensible: con solo inventory:read el kardex trae cantidades y saldos, pero todo costo y valor viene en null (costs_hidden: true). GET /inventory/valuation exige inventory:costs. Marca inventory:costs solo en las integraciones que de verdad lo necesitan (contabilidad, reportes).
• Los webhooks no se gestionan con la API: se crean y administran solo en cuenta.posdata.so.

La página de cada endpoint en la referencia dice qué permiso requiere.

Crear keys: verificación por correo

Crear una key (y crear un endpoint de webhooks o rotar su secreto) exige un código de 6 dígitos que llega al correo de la cuenta y vence a los 10 minutos. Así, alguien que robe la sesión de un dispositivo no puede crearse acceso permanente a tus datos. Cada vez que se crea una key o un endpoint, la cuenta recibe un correo de aviso de seguridad.

Una cuenta puede tener hasta 10 keys activas al mismo tiempo.

Vencimiento y revocación

• Al crearla puedes darle a la key un vencimiento de 30, 90 o 365 días, o dejarla sin vencimiento. Una key vencida responde 401 API_KEY_EXPIRED.
• Revocar una key es inmediato y no pide código: lo defensivo debe ser fácil. Una key revocada responde 401 API_KEY_REVOKED. La revocación no se deshace.

Si la cuenta baja de plan

La API pública está incluida en el plan Pro (con o sin facturación electrónica), y el plan se revisa en cada petición:

• Sin Pro, toda llamada responde 403 PLAN_REQUIRED. Las keys no se borran: quedan en pausa y vuelven a funcionar solas cuando la cuenta recupere Pro. No tienes que crear keys nuevas.
• Los webhooks tampoco se envían mientras la cuenta no tenga Pro, y esas entregas no se reintentan después. Para recuperar lo que pasó en ese tiempo, usa GET /events (el registro de eventos solo se llena mientras la cuenta tiene Pro).

Solo desde servidores

La API es servidor a servidor. Cualquier petición con el header Origin (lo que envía un navegador) recibe 403 BROWSER_REQUESTS_NOT_ALLOWED. Una key dentro de una página web o de una app móvil es una key pública: cualquiera puede extraerla. Si necesitas datos de Posdata en un front-end, pídelos a tu propio servidor y que él llame a la API.

La API tampoco restringe por dirección IP en esta versión.

Buenas prácticas

• Una key por integración. Si tu tienda en línea y tu BI usan keys distintas, puedes revocar una sin tumbar la otra, y en Desarrolladores → Actividad ves qué hizo cada una.
• Mínimo privilegio. Un tablero de BI solo necesita permisos :read.
• Rota periódicamente. Crea la key nueva, despliégala, verifica que tus llamadas funcionan con ella (GET /me te dice qué key estás usando) y revoca la anterior. Las dos pueden convivir mientras cambias.
• Guárdala como secreto (variables de entorno o un gestor de secretos), nunca en el repositorio.
• Si sospechas que una key se filtró, revócala de inmediato y crea otra.