Przejdź do treści
Biblioteka skilli
Programowanie · Integracja z narzędziem

br-ecommerce-integrations

/br-ecommerce-integrations

Opisuje, jak rozszerzyć Order Hub o brazylijski e-commerce: Mercado Livre, ERP Bling i potwierdzenia płatności Pix przez webhooki.

Repozytorium
order-hub ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
4
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Opisuje, jak rozszerzyć Order Hub o brazylijski e-commerce: Mercado Livre, ERP Bling i potwierdzenia płatności Pix przez webhooki.

Oryginalny opis (EN)

Reference for extending Order Hub beyond Shopify to the Brazilian e-commerce ecosystem — Mercado Livre (OAuth + notifications), Bling ERP (API v3), and Pix payment confirmation via webhooks (Mercado Pago, Pagar.me). Use when planning or building a new sales channel, ERP sync or payment integration.

Jak działa

  1. Architecture rule: one ingestion pipeline per channel, one domain model
  2. Mercado Livre
  3. Bling (ERP, API v3)
  4. Pix confirmation (Mercado Pago / Pagar.me)
  5. Checklist for any new integration
Sekcje z nagłówków SKILL.md, w oryginale · 53 linii, 425 słów
Podgląd SKILL.md
---
name: br-ecommerce-integrations
description: Reference for extending Order Hub beyond Shopify to the Brazilian e-commerce ecosystem — Mercado Livre (OAuth + notifications), Bling ERP (API v3), and Pix payment confirmation via webhooks (Mercado Pago, Pagar.me). Use when planning or building a new sales channel, ERP sync or payment integration.
---

# Brazilian e-commerce integrations (design notes)

These notes describe integration _patterns_. API details change: always confirm endpoints, scopes
and payloads in the official docs before coding (see links), and record decisions in `docs/adr/`.

## Architecture rule: one ingestion pipeline per channel, one domain model

Each channel gets: an auth module (OAuth tokens stored encrypted, refreshed proactively), a
webhook/notification receiver, a mapper `channel payload → Order/Customer`, and the same
guarantees as `lib/shopify/webhooks.ts`: signature/authenticity check, idempotency log,
single transaction, stale-update guard. Add a `channel` column (`shopify | mercado_livre | ...`)
and make `shopifyId` → `(channel, externalId)` unique — via expand/contract (skill `prisma-migration`).

## Mercado Livre

- Auth: OAuth 2.0 authorization code; access tokens are short-lived (hours) and refresh tokens
  rotate on use — persist the new refresh token every time.
- Notifications: ML POSTs a small JSON (`resource`, `topic`, `user_id`, ...) to the app callback
  URL, e.g. topic `orders_v2`. The notification carries no order data: you **GET the resource**
  with the seller's token. Respond 200 quickly; ML retries otherwise.
- Authenticity: there is no HMAC like Shopify's — validate by fetching the resource from the API
  (the source of truth) and by checking `user_id` belongs to a connected seller.
- Docs: https://developers.mercadolivre.com.br/

## Bling (ERP, API v3)

- OAuth 2.0 (authorization code), REST JSON, rate limited — queue writes and back off on 429.
- Typical flows: push paid orders to Bling (invoice/NF-e, stock), pull stock levels back.
- Idempotency on our side: store the Bling id returned for each order; never create twice.
- Docs: https://developer.bling.com.br/

## Pix confirmation (Mercado Pago / Pagar.me)

- Flow: create a charge → show QR code / copia-e-cola → customer pays in their bank app →
  PSP confirms asynchronously by **webhook** → mark order paid. Never trust the client redirect.
- Mercado Pago: webhook notification with the payment id; verify the `x-signature` header (HMAC
  with the webhook secret) and then GET the payment to read `status` (`approved`).
- Pagar.me: webhook events such as `order.paid` / `charge.paid`; verify the signature header and
  re-fetch the charge when in doubt.
- Charges expire: handle `expired`/`canceled`, and reconcile periodically (cron) in case a webhook
  was lost.
- Docs: https://www.mercadopago.com.br/developers · https://docs.pagar.me/

## Checklist for any new integration

- [ ] Secrets in env vars, documented in `.env.example` and `lib/env.ts`
- [ ] Signature or fetch-back verification
- [ ] Idempotency (event log + upserts) and out-of-order handling
- [ ] Integration tests with recorded fixtures
- [ ] LGPD: store only fields we use; handle deletion requests
- [ ] ADR explaining the choice

Wersje

W bazie nie ma innych skilli o nazwie br-ecommerce-integrations.

Migawka bazy z 13.11.2026 · wersja paczki 82214c0eaca0 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100mp-commerce-checkout
    Podłącza przypięty adapter Mercado Pago Checkout Pro do backendów agentów handlowych w Pythonie 3.11+, z hostowanym przekazaniem płatności zbudowanym z zaufanego katalogu.
  • 100int-bling
    Integruje ERP Bling przez API v3: produkty, zamówienia sprzedaży, kontakty, faktury NF-e i stany magazynowe.
  • 100mp-webhooks
    Konfiguruje i waliduje webhooki Mercado Pago z narzędziami MCP save_webhook i notifications_history oraz wzorcem walidacji podpisu HMAC-SHA256.
  • 95review-analysis
    Analizuje recenzje produktów z Shopee i Mercado Livre po portugalsku, klasyfikując negatywy, mocne strony i poprawki opisu.
  • 95headless-ecommerce
    Projektuje bezgłowe sklepy internetowe na Shopify Hydrogen i Storefront API: pobieranie danych, cache dla każdego typu danych, koszyk i wdrożenie.
  • 100celcoin-webhooks
    Odbiera i uwierzytelnia webhooki Celcoin, brazylijskiego BaaS, z obsługą przelewów Pix, TED i kont.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.