Ir al contenido
PosdataPosdataPosdata para desarrolladores

Inicio rápido

En cinco minutos vas a tener una API key, a consultar tu cuenta, a listar productos y a crear un cliente.

1. Crea una API key

Sección titulada «1. Crea una API key»
  1. Entra a cuenta.posdata.so y abre Desarrolladores.
  2. En API keys, elige Crear API key. Ponle un nombre que te diga para qué es (por ejemplo «Tienda en línea»), marca solo los permisos que tu integración necesita y, si quieres, un vencimiento de 30, 90 o 365 días.
  3. Por seguridad te pedimos un código de 6 dígitos que enviamos al correo de la cuenta. El código vence a los 10 minutos. Además, te llega un correo de aviso cada vez que se crea una key.
  4. Copia la key. Solo se muestra una vez: Posdata guarda una huella de ella, no la key, así que no podemos volver a mostrártela. Si la pierdes, revócala y crea otra.

Guárdala como variable de entorno en tu servidor, nunca en el código ni en un repositorio:

Ventana de terminal
export POSDATA_API_KEY="pdk_live_…"

2. Tu primera llamada: GET /me

Sección titulada «2. Tu primera llamada: GET /me»

/me funciona con cualquier key válida, sin importar sus permisos. Te dice qué cuenta es, qué permisos tiene la key y cuándo subió cada caja su último cambio.

Ventana de terminal
curl https://api.posdata.so/public/v1/me \
  -H "Authorization: Bearer $POSDATA_API_KEY"
{
  "object": "account",
  "id": "0b6f2f0e-5c1d-4d0b-9a57-3f1c2e8d7a10",
  "business": { "name": "Panadería La Espiga", "currency": "COP" },
  "plan": "pro",
  "api_key": {
    "id": "4e2d1c0b-7a8f-4b3e-9c2d-1a0f9e8d7c6b",
    "name": "Tienda en línea",
    "environment": "live",
    "scopes": ["products:read", "customers:read", "customers:write"],
    "expires_at": null
  },
  "data_freshness": {
    "last_device_sync_at": "2026-09-28T14:58:12.000Z",
    "devices": [
      { "name": "Caja 01", "kind": "primary", "platform": "windows", "last_sync_at": "2026-09-28T14:58:12.000Z" }
    ]
  }
}

Cada respuesta trae el header Request-Id (y cada error, el campo request_id). Guárdalo en tus logs: es lo primero que te pedirá soporte.

3. Lista tus productos

Sección titulada «3. Lista tus productos»

Necesitas el permiso products:read.

Ventana de terminal
curl "https://api.posdata.so/public/v1/products?limit=2&active=true" \
  -H "Authorization: Bearer $POSDATA_API_KEY"

La respuesta es una lista paginada, del más reciente al más antiguo (aquí, recortada):

{
  "object": "list",
  "data": [
    { "object": "product", "id": "8d2c…", "name": "Pan de bono", "final_price": 2500, "active": true },
    { "object": "product", "id": "3a91…", "name": "Almojábana", "final_price": 2800, "active": true }
  ],
  "has_more": true,
  "next_cursor": "eyJjIjoiMjAyNi0wOS0yOFQxNDo1…"
}

Para la página siguiente, pasa next_cursor tal cual en starting_after. Más en Paginación y filtros.

4. Crea un cliente sin duplicarlo

Sección titulada «4. Crea un cliente sin duplicarlo»

Necesitas el permiso customers:write. Todo POST exige el header Idempotency-Key: un valor único por operación (un UUID sirve). Si la red falla y reintentas con el mismo valor, Posdata te devuelve la respuesta original en vez de crear otro cliente.

Ventana de terminal
curl https://api.posdata.so/public/v1/customers \
  -H "Authorization: Bearer $POSDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c3b0e-2d4a-4f7b-8e9c-0a1b2c3d4e5f" \
  -d '{
    "name": "María",
    "last_name": "Gómez",
    "email": "[email protected]",
    "document_type": "CC",
    "document_number": "1020304050"
  }'

Responde 201 con el cliente creado. El cliente llega a las cajas del negocio por su sincronización normal: en segundos si están en línea; si están sin conexión, cuando se reconecten. Mira Cómo se sincroniza con las cajas.

Siguientes pasos

Sección titulada «Siguientes pasos»