# MadeiraMadeira

> MadeiraMadeira (MadeiraMadeira Comercio Eletronico S/A, Curitiba, Parana, Brazil) is one of Brazil's
> largest online retailers and marketplaces for home goods - furniture, decor, appliances, building
> materials, bathroom and kitchen fixtures. Its developer surface is the seller-facing Marketplace
> MadeiraMadeira API, a REST API over HTTPS used by third-party sellers and by the ERP/hub platforms
> that integrate on their behalf.

This file was GENERATED by API Evangelist from the provider's own published documentation and from
artifacts in this repository. MadeiraMadeira does not publish an llms.txt of its own; /llms.txt
returns a soft-404 on every MadeiraMadeira host (probed 2026-08-25).

## What the API does

The Marketplace API covers the full seller integration lifecycle:

- Products: submit and update the catalog, read the MadeiraMadeira category tree, and follow products
  through an approval pipeline (pending, awaiting approval, in publication, rejected, divergent,
  published).
- Price, stock and status: individually or in bulk.
- Shipping (frete): upload rate tables, assign a table per SKU, or have MadeiraMadeira call the
  seller's own quoting endpoint.
- Orders: read orders by id, status or date range, and advance them through received, invoiced
  (NF-e issued), shipped and delivered.
- Financial: read ledger entries - sales, commissions, withdrawals, chargebacks.
- Messaging (Mensageria): buyer-seller conversations, attachments and tracking updates.
- Callbacks: register webhook URLs for order and product events.

## Base URLs

- Production: https://marketplace.madeiramadeira.com.br
- Sandbox: https://marketplace-sandbox.madeiramadeira.com.br

All operations sit under the /v1 path prefix.

## Authentication

Send a seller-bound token in a custom header on every request:

    Content-Type: application/json
    TOKENMM: <token>

The token is issued in the Portal Marketplace under Administracao > Integracao, and requires an
approved seller registration with signed Terms and Conditions. It is unscoped and has no documented
expiry or rotation policy. The Mensageria (messaging) surface is the exception: it exchanges the
token for a bearer JWT via POST /v1/mensageria/auth/generate-token (expires_in 3600), revocable via
POST /v1/mensageria/auth/revoke-token.

There is no OAuth, no OpenID Connect, and no /.well-known/ metadata of any kind.

## Things that will break a naive client

- Pagination is encoded as PATH SEGMENTS, not query parameters. The URL is literally
  /v1/produto/limit=100&offset=0 - there is no "?". The Mensageria surface is the one exception and
  uses conventional query parameters, so the API carries two incompatible conventions at once.
- No idempotency. No Idempotency-Key header on any write. Do not blind-retry a timed-out PUT.
- Order status transitions are one-way. There is no un-invoice, un-ship or un-deliver, and CANCELADO
  is never accepted inbound - it is only ever pushed out to the seller. A wrong transition can only
  be corrected by contacting MadeiraMadeira.
- Errors carry no machine-readable code. The envelope is {"meta":{"count":0},"errors":{"detail":"..."}}
  with a Portuguese prose string. The HTTP status is the only machine-discriminable signal.
- HTTP 404 is overloaded: on the shipping surface it means "we do not serve that region", not "not found".
- Identifiers are returned as JSON strings, monetary values appear as both numbers and strings in the
  same object, and dates appear in three formats (YYYY-MM-DD HH:MM:SS, YYYY-MM-DD and DD/MM/YYYY) with
  no timezone stated.

## Documentation

- API reference (Postman): https://documenter.getpostman.com/view/3341659/RztmqU19
- Machine-readable collection: https://documenter.gw.postman.com/api/collections/3341659/RztmqU19
- Seller landing page: https://www.madeiramadeira.com.br/marketplace
- Help centre: https://madeiramadeira.zendesk.com/hc/pt-br
- Seller blog: https://parceiros.madeiramadeira.com.br/
- GitHub organisation: https://github.com/madeiramadeirabr
- Terms: https://www.madeiramadeira.com.br/termos
- Privacy: https://www.madeiramadeira.com.br/termos-e-privacidade

## What MadeiraMadeira does NOT publish

Recorded honestly so an agent does not go looking:

- No OpenAPI document. The Postman collection is the contract; the OpenAPI in this repository is a
  faithful derivation of it by API Evangelist, not a provider artifact.
- No GraphQL endpoint, no MCP server, no A2A agent card, no llms.txt, no /.well-known/ documents.
- No AsyncAPI. Webhooks exist and are documented, but only in prose.
- No status page, no dated changelog, no SLA for its own API.
- No first-party client SDK in any package registry. The only Marketplace API client on Packagist is
  third-party (magazord-plataforma/madeira-madeira-marketplace) and has never cut a tagged release.
- No published rate-limit numbers or headers, and no 429 in the error table.
- No published commission rate, plan or price list. Access to the API is a consequence of being an
  approved seller; the model is commission on sales with no initial cost and no monthly fee.

## Webhook events

Registered by the seller via POST /v1/callback and delivered by MadeiraMadeira over HTTPS. No
signature, shared secret or replay protection is documented.

- PEDIDO_NOVO - order placed, payment not yet authorised
- PEDIDO_APROVADO - payment authorised
- PEDIDO_CANCELADO - order cancelled
- PRODUTO_APROVADO - submitted product approved and published
- FRETE - synchronous shipping-quote request; the seller must respond within 1500 ms at 85%
  availability, returning 404 when it does not serve the region

## Repository artifacts

- openapi/madeiramadeira-marketplace-openapi.yml - OpenAPI 3.1.0, 67 operations, derived
- postman/madeiramadeira-marketplace-postman-collection.json - the provider's collection, verbatim
- authentication/madeiramadeira-authentication.yml
- conventions/madeiramadeira-conventions.yml - pagination, idempotency, reversibility
- errors/madeiramadeira-problem-types.yml
- asyncapi/madeiramadeira-marketplace-webhooks.yml
- data-model/madeiramadeira-data-model.yml
- lifecycle/madeiramadeira-lifecycle.yml
- rate-limits/madeiramadeira-rate-limits.yml
- sandbox/madeiramadeira-sandbox.yml
- plans/madeiramadeira-plans-pricing.yml
- conformance/madeiramadeira-conformance.yml
- packages/madeiramadeira-packages.yml
- security/madeiramadeira-domain-security.yml
- well-known/madeiramadeira-well-known.yml
- skills/_index.yml