# Conectar una tienda

`POST https://api.fiscalisto.com/v1/store_connections`

Shopify: con el dominio y las llaves de la app de la tienda (Dev Dashboard, permisos read_orders y write_orders) registra los webhooks y queda active. Mercado Libre: queda pending hasta que el vendedor autorice en authorize_url. Desde entonces cada pedido pagado es un ticket (folio SHOP-1001 o ML-…), que su comprador factura en el portal o entra en la factura global; un pedido cancelado o reembolsado completo cancela su ticket.

## Parámetros

| Nombre | Dónde | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `Idempotency-Key` | encabezado |  | Opcional (los SDK la mandan solos). Si la respuesta se pierde, repita la solicitud con el mismo valor durante 24 horas: contesta lo mismo, con idempotent-replayed: true, y no lo hace dos veces (ni crea, ni manda correos, ni cobra). |

## Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `issuer` | string |  | El emisor (iss_…) dueño de la tienda. Por omisión, su único emisor. |
| `platform` | `shopify`, `mercadolibre` | sí | shopify o mercadolibre. |
| `shop` | string |  | Shopify: el dominio de la tienda (mi-tienda.myshopify.com). |
| `client_id` | string |  | Shopify: el Client ID de la app de la tienda (Dev Dashboard). (hasta 200 caracteres) |
| `client_secret` | string |  | Shopify: el Client secret de esa app; con él se firman los webhooks. Se guarda cifrado y nunca se muestra. (hasta 200 caracteres) |
| `access_token` | string |  | Shopify, solo apps personalizadas antiguas: su token de la Admin API (shpat_…); client_secret es entonces su API secret key. |
| `return_url` | string (uri) |  | Mercado Libre: a dónde volver después de autorizar (se agregan store_connection y status). (hasta 500 caracteres) |
| `settings` | objeto |  | Cómo se vuelve ticket cada pedido. |
| `settings.product_key` | string |  | c_ClaveProdServ de lo que vende (8 dígitos). |
| `settings.unit_key` | string |  | c_ClaveUnidad. Por omisión, la de la clave del producto. |
| `settings.iva` | `0`, `0.16`, `0.08`, `exento` |  | Tasa de IVA incluida en los precios. Por omisión 0.16. |
| `settings.description` | string |  | El concepto de cada ticket. Por omisión, el pedido y sus artículos («Pedido 1001: Playera (2), Gorra»). (hasta 200 caracteres) |
| `settings.folio_prefix` | string |  | Lo que va antes del número del pedido en el folio del ticket. Por omisión SHOP- o ML-. |
| `settings.payment_form` | string |  | c_FormaPago cuando la forma de pago del pedido no está en payment_forms. Por omisión 04 (Shopify) o 31 (Mercado Libre). |
| `settings.payment_forms` | objeto |  | c_FormaPago por pasarela de Shopify (shopify_payments, paypal, manual…) o tipo de pago de Mercado Libre (credit_card, debit_card, account_money, ticket, bank_transfer). |
| `settings.auto_invoice` | boolean |  | Mercado Libre: timbrar en cuanto se paga si el comprador dejó sus datos fiscales completos. Por omisión true. |

Ejemplo:

```json
{
  "platform": "shopify",
  "shop": "mi-tienda.myshopify.com",
  "client_id": "8c1f0e7a2b3d4e5f6a7b8c9d0e1f2a3b",
  "client_secret": "shpss_0123456789abcdef0123456789abcdef",
  "settings": {
    "product_key": "53101600",
    "payment_forms": {
      "paypal": "31"
    }
  }
}
```

## Con el SDK de TypeScript

```ts
import { Fiscalisto } from "fiscalisto";

// La llave viene de FISCALISTO_API_KEY.
const fiscalisto = new Fiscalisto();

const storeConnection = await fiscalisto.storeConnections.create({
  platform: "shopify",
  shop: "mi-tienda.myshopify.com",
  client_id: "8c1f0e7a2b3d4e5f6a7b8c9d0e1f2a3b",
  client_secret: "shpss_0123456789abcdef0123456789abcdef",
  settings: {
    product_key: "53101600",
    payment_forms: { paypal: "31" },
  },
}, { idempotencyKey: "pedido-A-1042" });
```

## Con el SDK de Python

```python
from fiscalisto import Fiscalisto

# La llave viene de FISCALISTO_API_KEY.
fiscalisto = Fiscalisto()

store_connection = fiscalisto.store_connections.create({
    "platform": "shopify",
    "shop": "mi-tienda.myshopify.com",
    "client_id": "8c1f0e7a2b3d4e5f6a7b8c9d0e1f2a3b",
    "client_secret": "shpss_0123456789abcdef0123456789abcdef",
    "settings": {
        "product_key": "53101600",
        "payment_forms": {"paypal": "31"},
    },
}, idempotency_key="pedido-A-1042")
```

## Con el SDK de PHP

```php
<?php

use Fiscalisto\Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
$fiscalisto = new Fiscalisto();

$storeConnection = $fiscalisto->storeConnections->create([
    'platform' => 'shopify',
    'shop' => 'mi-tienda.myshopify.com',
    'client_id' => '8c1f0e7a2b3d4e5f6a7b8c9d0e1f2a3b',
    'client_secret' => 'shpss_0123456789abcdef0123456789abcdef',
    'settings' => [
        'product_key' => '53101600',
        'payment_forms' => ['paypal' => '31'],
    ],
], ['idempotency_key' => 'pedido-A-1042']);
```

## Con el SDK de .NET

```csharp
using Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var storeConnection = await fiscalisto.StoreConnections.CreateAsync(new CreateStoreConnectionParams
{
    Platform = "shopify",
    Shop = "mi-tienda.myshopify.com",
    ClientId = "8c1f0e7a2b3d4e5f6a7b8c9d0e1f2a3b",
    ClientSecret = "shpss_0123456789abcdef0123456789abcdef",
    Settings = new()
    {
        ProductKey = "53101600",
        PaymentForms = new() { ["paypal"] = "31" },
    },
}, new RequestOptions { IdempotencyKey = "pedido-A-1042" });
```

## Con el SDK de Go

```go
package main

import (
	"context"
	"fmt"
	"log"

	fiscalisto "fiscalisto.com/go"
)

func main() {
	// La llave viene de FISCALISTO_API_KEY.
	client, err := fiscalisto.NewClient("")
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	storeConnection, err := client.StoreConnections.Create(ctx, &fiscalisto.CreateStoreConnectionParams{
		Platform:     "shopify",
		Shop:         fiscalisto.String("mi-tienda.myshopify.com"),
		ClientID:     fiscalisto.String("8c1f0e7a2b3d4e5f6a7b8c9d0e1f2a3b"),
		ClientSecret: fiscalisto.String("shpss_0123456789abcdef0123456789abcdef"),
		Settings: &fiscalisto.CreateStoreConnectionParamsSettings{
			ProductKey:   fiscalisto.String("53101600"),
			PaymentForms: map[string]string{"paypal": "31"},
		},
	}, fiscalisto.WithIdempotencyKey("pedido-A-1042"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(storeConnection.ID)
}
```

## Con el SDK de Java

```java
import com.fiscalisto.FiscalistoClient;
import com.fiscalisto.RequestOptions;
import com.fiscalisto.model.CreateStoreConnectionParams;
import com.fiscalisto.model.CreateStoreConnectionParamsSettings;
import java.util.Map;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var storeConnection = fiscalisto.storeConnections().create(new CreateStoreConnectionParams()
        .setPlatform("shopify")
        .setShop("mi-tienda.myshopify.com")
        .setClientId("8c1f0e7a2b3d4e5f6a7b8c9d0e1f2a3b")
        .setClientSecret("shpss_0123456789abcdef0123456789abcdef")
        .setSettings(new CreateStoreConnectionParamsSettings()
                .setProductKey("53101600")
                .setPaymentForms(Map.of("paypal", "31"))), RequestOptions.idempotencyKey("pedido-A-1042"));
System.out.println(storeConnection.getId());
```

## Respuesta 201

Correcto.

Un objeto `StoreConnection`:

| Campo | Tipo | Siempre viene | Descripción |
| --- | --- | --- | --- |
| `id` | string | sí | Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). |
| `livemode` | boolean | sí | true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. |
| `object` | `"store_connection"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `issuer` | string | sí | El emisor dueño de la tienda. |
| `platform` | `shopify`, `mercadolibre` | sí | shopify o mercadolibre. |
| `shop` | string o null | sí | El dominio de la tienda de Shopify, o el id del vendedor en Mercado Libre (al autorizar). |
| `status` | `pending`, `active`, `disconnected` | sí | pending (Mercado Libre espera que el vendedor autorice en authorize_url), active o disconnected. |
| `authorize_url` | string o null | sí | Si está pending: la página de Mercado Libre donde el vendedor autoriza (vale un día; cada consulta da una nueva). Si no, null. |
| `settings` | objeto | sí | Cómo se vuelve ticket cada pedido. |
| `settings.product_key` | string o null | sí | c_ClaveProdServ de lo que vende, o null. |
| `settings.unit_key` | string o null | sí | c_ClaveUnidad, o null (la de la clave del producto). |
| `settings.iva` | `0`, `0.16`, `0.08`, `exento` | sí | Tasa de IVA incluida en los precios. |
| `settings.description` | string o null | sí | El concepto fijo de cada ticket, o null (el pedido y sus artículos). |
| `settings.folio_prefix` | string | sí | Lo que va antes del número del pedido en el folio. |
| `settings.payment_form` | string o null | sí | c_FormaPago cuando la del pedido no está en payment_forms, o null. |
| `settings.payment_forms` | objeto | sí | c_FormaPago por pasarela o tipo de pago. |
| `settings.auto_invoice` | boolean o null | sí | Mercado Libre: si se timbra al momento con los datos fiscales del comprador; null en Shopify. |
| `orders_count` | integer | sí | Cuántos pedidos se han vuelto tickets. (de -9007199254740991 a 9007199254740991) |
| `last_order_at` | string (date-time) o null | sí | Cuándo llegó el último, o null. |
| `last_error` | objeto o null | sí | El último problema (un pedido en dólares, un ticket que ya se facturó cuando se canceló el pedido…), o null. |
| `last_error.message` | string | sí | Qué pasó. |
| `last_error.at` | string (date-time) o null | sí | Cuándo. |
| `created_at` | string (date-time) o null | sí | Cuándo se conectó. |

```json
{
  "id": "stc_OufpKqnrvx9p3Kd8sLm2XyT5uBcW8sKdLx",
  "object": "store_connection",
  "livemode": false,
  "issuer": "iss_OufpKqnrvx9p",
  "platform": "shopify",
  "shop": "mi-tienda.myshopify.com",
  "status": "active",
  "authorize_url": null,
  "settings": {
    "product_key": "53101600",
    "unit_key": null,
    "iva": "0.16",
    "description": null,
    "folio_prefix": "SHOP-",
    "payment_form": null,
    "payment_forms": {
      "paypal": "31"
    },
    "auto_invoice": null
  },
  "orders_count": 128,
  "last_order_at": "2026-10-25T10:12:44-06:00",
  "last_error": null,
  "created_at": "2026-10-01T09:00:00-06:00"
}
```

## Errores

Puede responder 400, 401, 403, 404, 429, 500 con el cuerpo de error de siempre; cada código está en https://fiscalisto.com/docs/api/errores.md.