API de Parceiros da Zoppy

O Connect lê e escreve os dados da loja na Zoppy só pela API de Parceiros. A documentação dos recursos, dos campos e das respostas está em partners.zoppy.com.br; a IA de construção a lê antes de escrever um conector que fala com a Zoppy.

Host lógico

O código e o manifesto usam sempre https://partners.zoppy.com.br, em qualquer ambiente. O gateway troca esse host pelo endereço da API de Parceiros do ambiente em que o conector roda (staging ou produção). Nunca escreva outro host da Zoppy num conector.

Acesso

O conector não declara nem lê o acesso à Zoppy. O gateway injeta o acesso da loja só nas chamadas para partners.zoppy.com.br. ZOPPY_TOKEN é um nome reservado e não pode estar em secrets.

Rotas obrigatórias e nunca DELETE

• partners.zoppy.com.br em hosts exige as rotas que o conector usa em routes, com os métodos de cada uma.
• DELETE nunca é aceito na Zoppy, nem no manifesto nem no gateway (connect.route_not_allowed).
• Toda escrita na Zoppy usa ctx.http.write e exige externalWrites: true. A primeira escrita real espera uma pessoa da loja confirmar.

{
  "hosts": ["partners.zoppy.com.br"],
  "routes": [
    { "host": "partners.zoppy.com.br", "methods": ["GET"], "path": "/customers" },
    { "host": "partners.zoppy.com.br", "methods": ["GET", "POST", "PUT"], "path": "/customers/**" }
  ]
}

Regras de cada recurso

São as regras atuais da API de Parceiros, que a IA segue:

• Sempre buscar antes de escrever: o registro já existe? então atualize em vez de criar.
• Uma escrita por chamada: não há escrita em lote.
• Pedido recusa um externalId repetido com 422: trate como “já importado”, não como erro.
• Cliente é deduplicado pelo telefone.
• Produto é deduplicado pelo nome.
• Loja faz upsert pelo externalId.
• Leitura incremental: cursor por updatedAt mais o id, com pageSize 50.
• Recusa de um registro (4xx) vai para ctx.quarantine; falha geral (5xx, fora do ar) é erro da execução.

Acesso revogado

Um 401 da API de Parceiros quer dizer que o acesso da loja foi desativado: a execução falha, todos os conectores da loja pausam com o motivo zoppy_token_revoked e os administradores são avisados. Veja A Zoppy no Connect.