# Contratos de API e integração de merchandising | MerchandAise

- slug: developers-api-integrations
- locale: pt
- localeResolved: pt
- canonical: https://www.merchandaise.com/pt/developers/api-integrations

Explore os contratos MerchandAise para ferramentas de assistentes, incorporações comunitárias, operações de fornecedores e identidade empresarial, com limites claros de acesso público e protegido.

## Mantenha uma única fonte de verdade
Uma integração deve estender o fluxo da MerchandAise, não bifurcá-lo. As superfícies de site, incorporação, fornecedor, empresa e futuros assistentes devem ler e atualizar o mesmo estado versionado de design, intenção comercial, orçamento, aprovação e encomenda.
Onde a MerchandAise processa a transação do comprador, a Hutter Products GmbH é a vendedora contratante e o Merchant of Record sob a marca MerchandAise. A identidade e os contactos dos fornecedores permanecem privados, exceto quando a divulgação for obrigatória, e a produção continua a exigir a aprovação de prova digital e de uma amostra real.

## Superfícies de API e integração
- **Documentação da API de ferramentas de assistentes:** Explore os endpoints atuais de assistentes e ferramentas para sessões de design e revisão de integração. Esta referência pública não concede autoridade anónima para orçamentar ou efetuar uma encomenda. Human guide: Abrir docs de ferramentas de assistentes (/pt/developers/api-integrations). Machine-readable contract: OpenAPI JSON de ferramentas de assistentes (/api/docs/openapi.json). Access: public. Referência pública para APIs de assistentes e ferramentas. O acesso de produção e as operações que afetam encomendas continuam a exigir a autorização aplicável. Canonical page: /developers/api-integrations. Canonical section: /developers/api-integrations#api-docs.
- **API de incorporação comunitária:** Ligue experiências localizadas de clubes, comunidades ou montras às transferências de design e comércio geridas pela MerchandAise sem reconstruir o fluxo subjacente. Human guide: Rever guia de integração comunitária (/pt/developers/api-integrations#community-integrations). Machine-readable contract: OpenAPI JSON comunitário (/api/v1/community/public/openapi/v1). Access: public. Contrato público versionado para incorporações em montras, descoberta comunitária e transferências sensíveis ao idioma. Canonical page: /developers/api-integrations. Canonical section: /developers/api-integrations#community-integrations.
- **API de fornecedores:** Ligue fornecedores aprovados a operações de integração, catálogo, orçamento e atendimento após a qualificação da relação de fornecedor e do modelo de acesso. Human guide: Rever guia de integração de fornecedores (/pt/developers/api-integrations#supplier-integrations). Machine-readable contract: OpenAPI JSON de fornecedor (/api/v1/supplier/openapi/v1). Access: public. Contrato público para planeamento e geração de clientes. O acesso operacional de fornecedores permanece sujeito a permissões. Canonical page: /developers/api-integrations. Canonical section: /developers/api-integrations#supplier-integrations.
- **API de identidade empresarial:** Planeie fluxos de identidade SSO, provisionamento SCIM e prontos para auditoria para programas de merchandising empresarial aprovados e implementações governadas. Human guide: Rever guia de integração empresarial (/pt/developers/api-integrations#enterprise-integrations). Machine-readable contract: OpenAPI JSON de identidade empresarial (/api/v1/enterprise/identity/openapi/v1). Access: protected. Contrato protegido para espaços de trabalho empresariais aprovados; solicite acesso antes de utilizar este endpoint. Canonical page: /developers/api-integrations. Canonical section: /developers/api-integrations#enterprise-integrations.

## Escolha o contrato antes do código
- **Step 1: Mapeie a jornada do utilizador:** Decida quem entra no fluxo e onde: um comprador numa montra incorporada, um fornecedor aprovado, um utilizador empresarial ou um assistente a operar com autorização explícita.
- **Step 2: Confirme o limite de acesso:** Utilize contratos públicos para avaliação e geração de clientes, depois confirme as credenciais, âmbitos, ambientes, callbacks e endpoints protegidos antes da implementação.
- **Step 3: Comprove a continuidade de estado:** Teste se os designs, orçamentos, aprovações, erros e transferências de encomendas se mantêm atualizados com a versão ao longo da integração, incluindo tentativas e caminhos de reversão.

## O que cada integração deve preservar
- **Um estado versionado:** O design, a intenção comercial, o orçamento garantido pelo fornecedor, a aprovação e o estado da encomenda permanecem conectados. Alterações desatualizadas devem acionar um novo orçamento visível ou um estado de revisão.
- **Privacidade comercial e de fornecedores:** A MerchandAise continua a ser a comerciante e responsável pelo apoio perante o comprador. As identidades, contactos e dados internos dos fornecedores não são expostos através de integrações públicas.
- **Aprovação antes da produção:** Uma vista 3D nativa do produto e uma prova digital apoiam a decisão, mas não substituem a amostra real de produção exigida antes da produção em massa.

## Antes do tráfego de produção
Um ficheiro OpenAPI publicado é uma superfície de planeamento, não uma promessa de acesso anónimo à produção. Analisamos ambientes, credenciais, tratamento de falhas e titularidade operacional antes do lançamento.
- **Acesso e ambientes:** Confirme a versão do contrato, o espaço de trabalho aprovado, os âmbitos de autenticação, o sandbox, as credenciais de produção e os destinos de callback.
- **Falha e recuperação:** Defina tentativas, idempotência, tempos limite, erros visíveis para o cliente, observabilidade, responsabilidade de suporte e reversão antes do lançamento.
- **Evidência de ponta a ponta:** Verifique a jornada pretendida no ambiente de staging, desde a entrada e mutação de estado até ao orçamento, aprovação, transferência e comportamento de recuperação.

## FAQ
- **Com que superfície de integração devo começar?:** Comece pela pessoa e pela transição de estado. Utilize incorporações comunitárias para jornadas de clubes ou comunidades orientadas para o comprador, operações de fornecedores para fluxos aprovados do lado da oferta, identidade empresarial para SSO e SCIM, e ferramentas de assistentes apenas para fluxos orientados por AI explicitamente autorizados.
- **Um contrato público significa acesso público à produção?:** Não. Um contrato OpenAPI público apoia a descoberta, a revisão de arquitetura e a geração de clientes. As credenciais de produção, operações de escrita, fluxos de fornecedores, identidade empresarial e execução de assistentes ainda podem exigir um espaço de trabalho aprovado e autorização com âmbito definido.
- **Pode uma integração expor fornecedores ou contornar aprovações?:** Não. A identidade e os contactos dos fornecedores permanecem privados, exceto quando a divulgação for obrigatória, a MerchandAise detém a relação com o comprador e as ações que afetam encomendas devem preservar os controlos configurados de aprovação e de amostra real.

## Traga-nos o fluxo de trabalho, não uma arquitetura acabada.
Diga-nos quem vai utilizar a integração, que estado precisa de ler ou alterar e onde a experiência vai decorrer. Mapearemos o contrato, o modelo de acesso e o caminho de implementação mais seguro consigo.
- **Planear integração:** /pt/contact?intent=api-integration-review
- **Explorar agentes AI e MCP:** /pt/developers/ai-agents-mcp