GET /api/v1/sdk/organizations/:orgId/products

Lista o catálogo de produtos de uma sub-organização filha, com filtros e paginação, usando o token da organização pai.

Use este endpoint quando a organização pai (marketplace) precisa inventariar, sincronizar ou exibir os produtos de uma sub-organização sem possuir o token de acesso da filha. Casos típicos: painel do marketplace, conciliação com ERP, ou verificação de catálogo antes de criar checkout links.

A resposta segue o mesmo formato da listagem geral de produtos por organização (items + pagination), porém sempre restrita à orgId da filha. Apenas a organização que é pai direto da filha na relação organization_relationships pode chamar este recurso.

Autenticação

Requer Organization Access Token (OAT) da organização pai via header Authorization: Bearer. Tokens da própria sub-organização não substituem o pai para este endpoint.

Parâmetros de Path

orgId · string · required

Identificador único da sub-organização filha cujos produtos serão listados.

Parâmetros de Query

query · string

Termo de busca: filtra produtos cujo nome contém o texto (correspondência parcial, case-insensitive), equivalente ao parâmetro query de GET /v1/products.

is_archived · boolean

Quando true, retorna apenas produtos arquivados. Quando false, apenas não arquivados. Quando omitido, nenhum filtro por arquivamento é aplicado (retorna ativos e arquivados).

limit · integer

Quantidade máxima de itens por página. Padrão: 100 (diferente do GET /v1/products, pensado para integrações de marketplace que precisam de páginas maiores).

offset · integer

Deslocamento inicial (começando em 0). Padrão: 0.

page · integer

Número da página (base 1). Quando informado, o deslocamento é calculado como (page - 1) * limit, no mesmo espírito do GET /v1/products. Se page e offset forem enviados juntos, page prevalece para o cálculo do offset.

id · string

Restringe a um ou mais produtos por UUID. Para vários IDs, use vírgula entre os valores (ex.: id=uuid1,uuid2). Útil para reconciliar um conjunto conhecido de produtos após um job em lote.

Resposta

items · array

Lista de produtos da sub-organização, cada um com preços ativos, metadados e campos alinhados ao objeto retornado por GET /v1/products e por productsService.list.

pagination · object

Show pagination

total_count · integer

Total de produtos que correspondem aos filtros (antes da paginação).

max_page · integer

Número máximo de páginas para o limit utilizado.

Erros comuns

HTTP	Situação
403	Token não é OAT, ou a organização autenticada não é pai da orgId.
500	Falha interna ou banco; mensagem em error.

Relação com outros endpoints

• Para criar um produto na filha, use Criar produto para sub-organização.
• Para atualizar um produto existente em nome da filha, use Atualizar produto da sub-organização.
• Para alterar produtos usando apenas o token da própria organização dona do produto, use a API geral Listar produtos e Atualizar produto.

Exemplo

cURL

curl -X GET "https://api.chargefy.io/api/v1/sdk/organizations/org_01j9abc333/products?limit=50&query=plano" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN"

Resposta de exemplo

{
  "items": [
    {
      "id": "prod_01j9xyz999",
      "name": "Plano Mensal",
      "description": "Assinatura mensal",
      "is_archived": false,
      "organization_id": "org_01j9abc333",
      "recurring_interval": "month",
      "prices": [],
      "metadata": {},
      "created_at": "2024-11-01T10:30:00Z"
    }
  ],
  "pagination": {
    "total_count": 1,
    "max_page": 1
  }
}