Set up and connect
Account, API key, webhooks, the seller and their marketplace account.
This phase happens once per account and once per seller. At the end of it, Acme Store has an active Connection with Mercado Livre.
1. Account and API key
Sign in to the dashboard, give the company name and activate the account. Then create an API key. It shows up once: keep it in your secrets vault.
Every call carries the key in the Authorization: Bearer mk_… header. One key works for the whole account, with every seller. See Authentication and Billing.
2. Webhook endpoint
Register a URL of yours to get the events. You pick the event types or use * for all. The signing secret shows up only at creation. Check the signature on every delivery.
If your URL goes down, marketapi retries for up to 24 hours. You can also redeliver one delivery. See Receiving webhooks.
3. The seller
Create one seller per customer of yours. Use externalId with their id in your system and metadata for anything else you want to keep. The seller has no login on marketapi: you are the one who talks to the API.
4. Connecting the marketplace
The seller authorizes access to their account on a page we host. You only create the session and send the link.
- Two ways to connect. The seller uses our page, which shows every marketplace. Or you put one of the
connectUrlsbehind your own button, and they go straight to the marketplace screen. - Right after connecting, a
connection.syncjob reads the account. Its id arrives inconnection.created, indata.syncJobId. - The token is on us. marketapi renews access on its own. If the seller or the marketplace revokes it,
connection.revokedarrives, and a new link session reconnects the same account. - Your own app (BYOK). You can use your own marketplace app instead of ours. See BYOK.
The step by step with curl is in Connecting a seller.
5. What the Connection tells you
An active Connection answers three questions:
| Question | Where |
|---|---|
| What can I do on this account? | Capabilities |
| Is each resource up to date? | Sync state |
| Is the account's reputation good? | Account health |
Endpoints in this phase
| To | Endpoint |
|---|---|
| Get events | Create endpoint · Event types |
| Register the seller | Create · List · Update |
| Make the connect link | Create link session · Get |
| See the connected accounts | List connections · Get · Disconnect |
| Know what the account allows | Capabilities · Health · Marketplace options |
Webhooks in this phase: seller.created, seller.updated, seller.deleted, connection.created, connection.updated, connection.revoked, link_session.completed and connection.health_changed.