Sincronizar Comercios

POST /api/commerces/sync

Hace upsert masivo de comercios con direcciones y usuarios. Utiliza externalId como clave de coincidencia: crea nuevos comercios o actualiza los existentes.

Auth: Requerida — permiso SYNC_COMMERCES

Cuerpo de la Solicitud

Campo	Tipo	Requerido	Descripción
`commerces`	array	Sí	Arreglo de objetos de comercio a sincronizar

Cada objeto de comercio:

Campo	Tipo	Requerido	Descripción
`externalId`	string	Sí	Identificador del sistema externo (clave de coincidencia)
`name`	string	Sí	Nombre del comercio
`taxId`	string	No	RUT / ID tributario
`metadata`	object	No	JSON arbitrario
`addresses`	array	No	Direcciones a sincronizar
`users`	array	No	Usuarios a sincronizar

Ejemplo

curl -X POST https://api.reten.ai/api/commerces/sync \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "commerces": [
      {
        "externalId": "store-001",
        "name": "Main Street Store",
        "taxId": "12345678-9",
        "addresses": [
          {
            "street": "123 Main St",
            "city": "Santiago",
            "isPrimary": true,
            "latitude": -33.4489,
            "longitude": -70.6693
          }
        ],
        "users": [
          {
            "firstName": "Maria",
            "lastName": "Garcia",
            "roles": ["OWNER"],
            "contacts": [
              {
                "type": "PHONE",
                "value": "+56912345678",
                "isPrimary": true
              }
            ]
          }
        ]
      }
    ]
  }'

const response = await fetch("https://api.reten.ai/api/commerces/sync", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "x-tenant-id": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    commerces: [
      {
        externalId: "store-001",
        name: "Main Street Store",
        taxId: "12345678-9",
        addresses: [
          {
            street: "123 Main St",
            city: "Santiago",
            isPrimary: true,
            latitude: -33.4489,
            longitude: -70.6693,
          },
        ],
        users: [
          {
            firstName: "Maria",
            lastName: "Garcia",
            roles: ["OWNER"],
            contacts: [
              {
                type: "PHONE",
                value: "+56912345678",
                isPrimary: true,
              },
            ],
          },
        ],
      },
    ],
  }),
});
const result = await response.json();

import requests

response = requests.post(
    "https://api.reten.ai/api/commerces/sync",
    headers={
        "Authorization": "Bearer <token>",
        "x-tenant-id": "<tenant-id>",
    },
    json={
        "commerces": [
            {
                "externalId": "store-001",
                "name": "Main Street Store",
                "taxId": "12345678-9",
                "addresses": [
                    {
                        "street": "123 Main St",
                        "city": "Santiago",
                        "isPrimary": True,
                        "latitude": -33.4489,
                        "longitude": -70.6693,
                    }
                ],
                "users": [
                    {
                        "firstName": "Maria",
                        "lastName": "Garcia",
                        "roles": ["OWNER"],
                        "contacts": [
                            {
                                "type": "PHONE",
                                "value": "+56912345678",
                                "isPrimary": True,
                            }
                        ],
                    }
                ],
            }
        ]
    },
)
result = response.json()
print(f"Created: {result['created']}, Updated: {result['updated']}")

Respuesta `201 Created`

{
  "created": 1,
  "updated": 0,
  "total": 1
}

Notas

Utiliza externalId como clave de coincidencia para el upsert idempotente
Se crean comercios placeholder (isPlaceholder = true) para entradas referenciadas pero no definidas
Los metadatos usan semántica de fusión en las actualizaciones