Pular para conteúdo

Ambientes

A Gubee opera com um único domínio de produção. Não há subdomínio separado de sandbox; comportamento sandbox é habilitado por feature (atualmente apenas a criação manual de pedidos).

Produção

Recurso URL
API base https://api.gubee.com.br
Swagger UI https://api.gubee.com.br/api/swagger-ui/index.html
OpenAPI JSON (todos) https://api.gubee.com.br/api/openapi.json
OpenAPI BFF https://api.gubee.com.br/api/openapi-bff.json
OpenAPI Integração https://api.gubee.com.br/api/openapi-integration.json
Actuator health https://api.gubee.com.br/actuator/health
Actuator info https://api.gubee.com.br/actuator/info

O path base da API é /. Endpoints de integração ficam sob /integration/* e endpoints do front web sob /bffweb/*.

Portas internas

O BFF escuta na porta 8080 em produção. Essa porta não é exposta externamente; todo acesso público passa pelo API Gateway na borda, que termina TLS e encaminha para o BFF. Internamente a Gubee usa portas diferentes para outros perfis (ex.: desenvolvimento), mas isso não afeta parceiros.

TLS e HTTP

  • TLS 1.2+ é obrigatório. Requisições em TLS 1.0/1.1 são rejeitadas na borda.
  • HTTP/2 é suportado e recomendado — multiplexa várias chamadas na mesma conexão TCP.
  • HTTP plano retorna redirect 301 para HTTPS; nunca envie payloads em clear-text.
  • HSTS é enviado pelo gateway com max-age de pelo menos 1 ano.

CORS

O BFF tem CORS configurado de forma permissiva para permitir integrações front-end:

gubee:
  cors:
    allowed-origins: '*'
    allowed-methods: GET, PUT, POST, DELETE, OPTIONS, PATCH
    allowed-headers: '*'
    allow-credentials: true
    max-age: 1800

Para integrações server-to-server (ERP, hub), o CORS é irrelevante — ele só aplica em navegadores. Prefira chamadas diretas com Authorization: Bearer.

Swagger UI

Acesse:

https://api.gubee.com.br/api/swagger-ui/index.html

O Swagger UI exibe três specs no dropdown superior direito:

  • All: todas as rotas (openapi.json).
  • BFF: rotas /bffweb/* (openapi-bff.json).
  • Integrações: rotas /integration/* (openapi-integration.json) — a documentação canônica para parceiros ERP/hub.

A maior parte das rotas é permitAll no filtro de segurança, mas chamadas reais a endpoints /integration/* só funcionam com JWT válido (ver Autenticação). O painel Swagger aceita o botão "Authorize" com o JWT no formato Bearer <token>.

Endpoints /management/* exigem ROLE_ADMIN e não devem ser usados por integrações externas.

Sandbox

Não há domínio sandbox.gubee.com.br. Operações sandbox-only são controladas por flag no serviço downstream e rodam contra o mesmo cluster de produção, mas não disparam efeitos colaterais reais (ex.: não notificar o marketplace).

Criação de pedido em sandbox

A única operação explicitamente sandbox hoje é a criação manual de pedido:

POST /integration/orders/create

Esta rota é declarada como sandbox-only no OrderIntegrationApiResource. Em uma conta configurada para produção normal, a chamada retorna erro. Use-a apenas em contas de teste homologadas para validar o payload de pedido.

Operações como PUT /integration/orders/invoiced/{orderId}, PUT /integration/orders/paid/{orderId} e PUT /integration/orders/cancel/{orderId} não são sandbox: elas afetam o pedido real.

Para validar o ciclo completo de pedidos sem impactar marketplaces, crie uma conta de teste isolada e mantenha-a sem canais publicados ativos.

Rate limits e concorrência

O BFF não impõe limit rígido por token, mas recomenda-se respeitar as diretrizes abaixo para evitar degradação:

Tipo de carga Concorrência recomendada Observação
Escrita em lote (produtos/preço/estoque) 5–10 conexões simultâneas Cada call pode gerar eventos na plataforma de streaming; sature e o lag aumenta.
Leitura de filas de pedidos (/integration/orders/queue/*) 1–2 pollers por seller Use poll com backoff (15–60s) e sempre confirme via DELETE.
Resolução de SKU (/integration/skus/by-sku) Livre Resposta cacheada por 5min no BFF (cache.sku-id.ttl: 5m, 50k entradas).
Search de produtos (/integration/products/list/search) 2–3 simultâneas É uma chamada paginada que pode varrer milhões de itens.

Boas práticas de cliente

  • Connection pool: use HTTP keep-alive e pool de conexões (ex.: 50–100 conexões por host). O BFF está configurado com pool de 200 conexões totais e 200 por rota (rest-template-pool.configurations.default).
  • Timeouts: recomendado 10s para leituras rápidas, 30s para search/ads e 180s para operações longas (import, reprocessamento). O BFF já usa esses três perfis internamente.
  • Retry com jitter: em caso de 5xx ou timeout, faça retry exponencial com jitter (ex.: 1s, 2s, 4s). Evite retry em 4xx.
  • Idempotência: writes de preço/estoque retornam 202 Accepted e são idempotentes no nível de evento — refazer o mesmo PUT não duplica o preço, apenas atualiza o lastModifiedDt.
  • Não faça busy-polling em /integration/orders/queue/created: cada chamada sem DELETE subsequente retorna o mesmo lote.

Actuator e observabilidade

Os únicos endpoints do Actuator expostos são health e info:

GET /actuator/health    -> {"status": "UP"}
GET /actuator/info      -> metadados do componente (nome, versão)

Liveness e readiness probes do Kubernetes usam /actuator/health/liveness e /actuator/health/readiness (probes habilitados). Esses endpoints são permitAll na configuração de segurança — não exigem JWT.

O BFF exporta telemetria via OpenTelemetry usando as variáveis OTEL_* definidas no ConfigMap do Kubernetes. Não há endpoint público para traces/metrics; a observabilidade é consultada internamente via Grafana. Para detalhes de troubleshooting em produção, consulte o time de SRE.

Requisitos de rede

Egress do seu ambiente para a Gubee

Libere no firewall de saída do seu ERP/hub:

  • api.gubee.com.br:443 (HTTPS)
  • IP: resolva via DNS — o tráfego é balanceado via Tencent Cloud CLB.

Não há necessidade de liberar portas não-padrão. Tudo passa por HTTPS/443.

Webhooks (Gubee → seu ambiente)

Se você configurar webhooks (recomendado para eventos de pedido e preço), o serviço Gubee precisa enxergar seu endpoint público. Se o seu ERP estiver em rede privada, exponha um proxy reverso ou API Gateway interno e cadastre essa URL no painel Gubee.

A Gubee não envia webhooks assinados com HMAC por padrão; a autenticação do webhook é por token compartilhado no header (configurável no cadastro do webhook).

IP whitelist (marketplaces externos)

Alguns marketplaces (Shein, Mercado Livre, B2W, Magalu, Amazon, Shopee, etc.) exigem que as chamadas venham de um IP whitelistado. Para bater diretamente nessas APIs externas a partir do seu ambiente, é preciso usar o egress proxy da Gubee (IP fixo 43.159.133.168). Consulte o time de suporte para liberar acesso ao proxy.

Versionamento de API

A API é versionada implicitamente por path. Mudanças breaking seguem o padrão:

  • Major: nova rota (ex.: /v2, /v3) é adicionada; a antiga é mantida por pelo menos 6 meses com header Deprecation: true.
  • Minor/Patch: adição de campos opcionais em request/response, novos endpoints — sem breaking change.

O header Content-Type canônico é application/json. Muitas rotas usam também application/hal+json (HATEOAS) para incluir links de navegação.

Suporte

  • Dúvidas técnicas: abra um chamado no painel Gubee ou use o canal de suporte do seu onboarding.
  • Bugs: inclua X-Request-Id (retornado pelo BFF) e o timestamp UTC.
  • Status do serviço: monitore /actuator/health do seu ambiente; o SLA é comunicado no contrato.

Próximos passos