Botigues de comerç electrònic
Connecta botigues, configura la facturació de comandes i diagnostica comandes i devolucions mitjançant REST i MCP.
Autoritza primer la connexió del proveïdor a Factuarea. integration_id identifica aquesta connexió existent; external_store_id és l’identificador opac de la botiga al proveïdor. La botiga pertany a l’empresa autenticada per la teva API key.
Operacions i scopes
| Operació | Scope necessari | Eina MCP |
|---|---|---|
GET /v1/stores | stores:read | list_stores |
POST /v1/stores | stores:write | connect_store |
GET /v1/stores/{store} | stores:read | get_store |
PUT /v1/stores/{store} | stores:write | update_store |
DELETE /v1/stores/{store} | stores:write | disconnect_store |
POST /v1/woocommerce/stores/{store}/connection-test | woocommerce_store:write | test_woocommerce_store_connection |
POST /v1/shopify/stores/{store}/connection-test | shopify_store:write | test_shopify_store_connection |
Aquestes eines només admeten API key. Les operacions REST que declaren Idempotency-Key la requereixen; reutilitza la mateixa clau quan reintentis la mateixa intenció. A MCP, passa idempotency_key quan ho exigeixi l’eina. El llistat accepta limit d’1 a 100 (25 per defecte), starting_after i ending_before; no combinis tots dos cursors.
curl -X POST https://api.factuarea.com/v1/stores \
-H "Authorization: Bearer $FACTUAREA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: connect-tienda-es-2026-09" \
--data '{
"integration_id": "0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f71",
"provider": "woocommerce",
"external_store_id": "wc-tienda-es",
"name": "Tienda ES",
"remote_base_url": "https://tienda.example.com",
"environment": "test",
"autoinvoicing_enabled": false,
"autosend_enabled": false
}'Revisa la configuració abans d’activar
Les botigues noves fan servir per defecte environment: test, autoinvoicing_enabled: false i autosend_enabled: false. prices_include_tax val true, require_tax_id val false i simplified_threshold és 400 EUR. L’API admet un llindar de fins a 3000; tria el corresponent a la teva activitat. Canviar una botiga a live no canvia l’entorn d’una credencial fact_test_.
Les comandes pagades poden produir factures; les devolucions poden produir rectificatives vinculades a l’original. Es continuen comprovant la identificació, els impostos, l’estat de la comanda i el llindar configurat. Les comandes en altres divises necessiten conversió a EUR i un tipus de canvi disponible. Els casos fiscals o d’identitat no admesos apareixen com a motius de descart tipats, sense fabricar cap factura.
Diagnostica el resultat
Les proves de connexió poden retornar HTTP 200 amb credential_accepted: false. Consulta reachable, failure_code, api_version i checked_at. Una botiga inexistent retorna 404; l’èxit de la petició HTTP no demostra per si sol que funcionin les credencials remotes.
Fes servir la safata d’integracions per a les comandes descartades i reprocessa només quan is_replayable sigui true, després de corregir-ne la causa. Subscriu-te a order.invoiced i order.refunded per rebre els snapshots a data.object; fes servir correlation_id per relacionar esdeveniments. channel i source_store_id conserven l’origen de la factura. Les notificacions configurades de Slack/Teams són una destinació separada dels teus webhooks públics. Desconnectar una botiga atura la connexió; no n’esborra les factures ni els esdeveniments històrics.