Connectar una botiga

Connecta una botiga de comerç electrònic a la teva empresa.

integration_id identifica la connexió amb el proveïdor de què depèn la botiga, i external_store_id és l'identificador que el proveïdor assigna a la botiga.
És únic per proveïdor dins de la teva empresa: una segona botiga amb el mateix proveïdor i identificador es rebutja amb store_already_connected.
La facturació automàtica està desactivada fins que l'activis; connectar una botiga no comença a emetre factures.
Si envies remote_base_url, es comprova amb la política de destinacions de sortida de la teva empresa i es rebutja amb store_url_not_allowed si no està permesa.

Clau opaca generada pel client (fins a 255 caràcters; es recomana UUID v7) que fa segurs els reintents: la primera resposta es cacheja i es reprodueix a les repeticions sense tornar a executar la mutació. Reutilitzar una clau amb un cos diferent retorna 409 idempotency_key_reused. Consulta la guia d'Idempotency.

Longitud1 <= length <= 255

Factuarea-Version?string

Fixa la versió de l'API (YYYY-MM-DD, versionat per data estil Stripe) per a aquesta petició; omet-lo per usar la versió fixada de la clau, o l'última si no n'hi ha cap. Versió no suportada → 400 unsupported_api_version; mal formada → 400 parameter_invalid_format. La versió efectiva es reflecteix a la capçalera de resposta Factuarea-Version. Consulta la guia de Versioning.

Formatdate

X-Active-Profile?string

Opera en nom d'una empresa filla (API key mestra de gestoria): passa el seu id públic (UUID v7) i la petició s'executa contra les dades d'aquella filla sense canviar l'scope, el tier ni l'environment de la clau (omet-lo per usar la pròpia empresa de la clau). UUID no vàlid → 400 parameter_invalid_uuid; id desconegut o no propi → 404 profile_not_found. Consulta la guia d'Acting on behalf.

Formatuuid

Cos de la petició

application/json

Definicions de TypeScript

Usa el tipus request body a TypeScript.

integration_id*string

Identificador (UUID v7) de la connexió amb el proveïdor que sustenta la botiga.

Formatuuid

provider*string

Proveïdor de comerç electrònic de la botiga: woocommerce, shopify o prestashop.

Valor a"woocommerce" | "shopify" | "prestashop"

external_store_id*string

Identificador que el proveïdor assigna a la botiga; únic per proveïdor dins de la teva empresa.

Longitudlength <= 191

name*string

Nom visible de la botiga, editable en qualsevol moment.

Longitudlength <= 191

series_id?|

Sèrie (UUID v7, tipus factura) amb què numera la botiga; omet-la per seguir la sèrie predeterminada de la teva empresa.

Formatuuid

simplified_threshold?|

Total de la comanda, en euros, fins al qual la botiga emet una factura simplificada. Màxim 3000.00.

Rang0 <= value <= 3000

require_tax_id?|

Indica si s'exigeix el NIF del comprador per facturar la comanda.

prices_include_tax?|

Indica si els preus de la botiga ja inclouen impostos.

autoinvoicing_enabled?|

Indica si les comandes pagades es facturen automàticament. Desactivat fins que ho activis.

autosend_enabled?|

Indica si la factura s'envia automàticament per email al comprador. Desactivat fins que ho activis.

remote_base_url?|

Adreça base de la botiga remota, comprovada amb la política de destinacions de sortida de la teva empresa.

Formaturi

Longitudlength <= 2048

environment?|

Entorn declarat per la botiga: live genera factures reals; test descarta els esdeveniments amb un motiu tipificat.

Valor a"live" | "test" | null

authorize_remote_host?|

Autoritza el host de remote_base_url com a destinació de sortida en la mateixa crida.

Cos de la resposta

`application/json`

Exemple de petició

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/stores", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-stores-create"} },  body: JSON.stringify({  "integration_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",  "provider": "woocommerce",  "external_store_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",  "name": "Tienda principal"}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Exemple de resposta

{
  "data": {
    "id": "0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090",
    "object": "store",
    "integration_id": "0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f71",
    "provider": "woocommerce",
    "external_store_id": "wc-tienda-es",
    "name": "Tienda ES",
    "simplified_threshold": 400,
    "require_tax_id": false,
    "prices_include_tax": true,
    "autoinvoicing_enabled": false,
    "autosend_enabled": false,
    "remote_base_url": "https://tienda.example.com",
    "environment": "test",
    "status": "active",
    "connected_at": "2026-08-29T09:00:00+00:00"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Falta header Authorization o X-API-Key.",
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_5227e92bac68846062d5cb7790"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'stores:write'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_9ec194f7b7c4eca54b4b873f56"
  }
}

{
  "error": {
    "type": "conflict_error",
    "code": "resource_conflict",
    "message": "La operación chocó con el estado actual del recurso y no aplica ningún código de conflicto más específico.",
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_conflict",
    "request_id": "req_22ee1029847bc887736efd6958"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "El campo integration_id es obligatorio.",
    "param": "integration_id",
    "errors": [
      {
        "param": "integration_id",
        "code": "parameter_missing",
        "message": "El campo integration_id es obligatorio."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_07b10ce71ac4fcb8bd89d6100f"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de requests permitido. Reintenta más tarde.",
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_fb3f595ae0c04c1f5c89301ac4"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.",
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_a9cdf8fa53e72982cb1b3bfb70"
  }
}

Connectar una botiga

Authorization

Headers

Cos de la petició

Cos de la resposta

201application/json

401application/json

403application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`