Stores y POS

Gestión de sucursales y cajas POS. Mapea IDs del ERP con IDs de MercadoPago.

Modelo

graph TD
    STORE["🏪 Store (Sucursal)<br/>external_id: SUC001"] --> POS1["📟 POS (Caja)<br/>external_id: SUC001-POS001"]
    STORE --> POS2["📟 POS (Caja)<br/>external_id: SUC001-POS002"]
    POS1 --> TERM1["🔌 Terminal<br/>NEWLAND_N950__XXX"]
    POS2 --> TERM2["🔌 Terminal<br/>PAX_A910__YYY"]

Endpoints

`GET /stores`

Lista todas las sucursales del cliente con sus POS.

RequestResponse

curl https://api.example.com/stores \
  -H "x-api-token: mk_client_key"

{
  "stores": [
    {
      "id": "uuid",
      "external_id": "SUC001",
      "name": "Sucursal Centro",
      "mp_store_id": "12345678",
      "location": {
        "street_name": "Av. Corrientes",
        "street_number": "1234",
        "city_name": "Rosario",
        "state_name": "Santa Fe",
        "latitude": -32.9468,
        "longitude": -60.6393,
        "reference": null
      },
      "pos": [
        {
          "id": "uuid",
          "external_id": "SUC001-POS001",
          "name": "Caja 1",
          "mp_pos_id": "87654321"
        }
      ],
      "created_at": "2025-01-15T10:00:00.000Z"
    }
  ],
  "total": 1
}

`GET /stores/:storeExternalId`

Detalle de una sucursal específica.

`POST /stores`

Crea una sucursal en MercadoPago y opcionalmente POS en la misma request.

RequestResponse 201

curl -X POST https://api.example.com/stores \
  -H "Content-Type: application/json" \
  -H "x-api-token: mk_client_key" \
  -d '{
    "name": "Sucursal Centro",
    "external_id": "SUC001",
    "location": {
      "street_name": "Av. Corrientes",
      "street_number": "1234",
      "city_name": "Rosario",
      "state_name": "Santa Fe",
      "latitude": -32.9468,
      "longitude": -60.6393
    },
    "pos": [
      { "name": "Caja 1", "external_id": "SUC001-POS001" },
      { "name": "Caja 2", "external_id": "SUC001-POS002" }
    ]
  }'

{
  "message": "Store created successfully",
  "store": {
    "id": "uuid",
    "mpStoreId": "12345678",
    "externalId": "SUC001",
    "name": "Sucursal Centro"
  },
  "pos": [
    { "id": "uuid", "mpPosId": "111", "externalId": "SUC001-POS001", "name": "Caja 1" },
    { "id": "uuid", "mpPosId": "222", "externalId": "SUC001-POS002", "name": "Caja 2" }
  ]
}

Importante

Hay un delay de 2 segundos entre la creación de cada POS para evitar problemas de consistencia eventual en la API de MercadoPago.

`POST /stores/:storeExternalId/pos`

Agrega POS a una sucursal existente.

Request

curl -X POST https://api.example.com/stores/SUC001/pos \
  -H "Content-Type: application/json" \
  -H "x-api-token: mk_client_key" \
  -d '{
    "pos": [
      { "name": "Caja 3", "external_id": "SUC001-POS003" }
    ]
  }'

`DELETE /stores/:storeExternalId/pos/:posExternalId`

Elimina un POS de MercadoPago y de la base de datos.

`DELETE /stores/:storeExternalId`

Elimina una sucursal y todos sus POS tanto en MercadoPago como en la base de datos.

Operación destructiva

Primero elimina todos los POS de la sucursal en MP, luego la sucursal. No se puede deshacer.