Ir al contenido
docs

Inicio rápido

Crea tu API key, haz tu primera llamada y crea un cliente sin riesgo de duplicarlo.

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

Nota

Necesitas una cuenta con plan Pro (con o sin facturación electrónica) y poder entrar a cuenta.posdata.so con ella.

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:

Terminal
export POSDATA_API_KEY="pdk_live_…"
Atención

La key es para tu servidor. No la pongas en un navegador, en una app móvil ni en un front-end: la API rechaza cualquier petición que traiga el header Origin (403 BROWSER_REQUESTS_NOT_ALLOWED).

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.

Terminal
curl https://api.posdata.so/public/v1/me \
  -H "Authorization: Bearer $POSDATA_API_KEY"
JSON
{
  "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

Necesitas el permiso products:read.

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):

JSON
{
  "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

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.

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