# 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](https://cuenta.posdata.so) con ella.

## 1. Crea una API key

1. Entra a [cuenta.posdata.so](https://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:

```sh
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.

```sh
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`.

```sh
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](https://developers.posdata.so/paginacion/).

## 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.

```sh
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": "maria@example.com",
    "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](https://developers.posdata.so/sincronizacion/).

## Siguientes pasos

- [Autenticación](https://developers.posdata.so/autenticacion/): permisos, entornos y rotación de keys.
- [Errores](https://developers.posdata.so/errores/): qué hacer con cada código.
- [Webhooks](https://developers.posdata.so/webhooks/): recibe eventos en vez de consultar a cada rato.
- [Referencia de la API](https://developers.posdata.so/referencia/): todos los endpoints y objetos.

---

Fuente: https://developers.posdata.so/inicio-rapido/ · Índice para agentes: https://developers.posdata.so/llms.txt