Produtos

Alimente o seu catálogo de serviços e exponha estoques com segurança nos seus frontends.

Visão geral

O objeto Producto contém os elementos da sua lista de preços (SKU, nome, preço base e unidade de medida). A API de produtos do Cord é segura o bastante para que você a consuma não só a partir dos seus servidores internos, mas também diretamente no navegador dos seus clientes.

Criar um produto

Use a sua chave de API secreta (sk_) para alimentar o catálogo em massa. Ideal para integrações noturnas ou webhooks vindos de sistemas de gestão de estoque.

Requisição:

curl -X POST "https://cordhq.app/api/v1/productos" \
     -H "Authorization: Bearer sk_live_tU..." \
     -H "Content-Type: application/json" \
     -d '{
       "sku": "LIC-PRO-24",
       "nombre": "Professional Annual License",
       "unidad": "license",
       "precio": 12000,
       "activo": true
     }'

Resposta bem-sucedida:

{
  "data": {
    "id": "7e3c9a1f-2b4d-4c6e-8f0a-b1d3e5f7a9c2"
  }
}

Campos opcionais de imposto e faturamento

Campo	O que é	Validação
`tax_rate`	O imposto que o produto sugere ao ser adicionado a um orçamento ou a uma fatura, como fração (`0.08` = 8%). Sem ele, o item usa a sua alíquota padrão.	Deve ser uma alíquota do seu catálogo de impostos (ou `0`); se não, responde `400`.
`clave_sat`	Código SAT de produto ou serviço (c_ClaveProdServ) para o CFDI no México.	8 dígitos (`81111500`); se não, `400`.
`clave_unidad_sat`	Código SAT de unidade (c_ClaveUnidad). Sem ele, é deduzido de `unidad` ao timbrar (`hora` → `HUR`).	De 1 a 3 letras ou números (`E48`), armazenada em maiúsculas; se não, `400`.

Na listagem, eles vêm como taxRate, claveSat e claveUnidadSat (null se não foram atribuídos).

Listar produtos e segurança dos dados

A API de listagem (GET /api/v1/productos) tem um mecanismo de mascaramento dinâmico (Dynamic Masking) baseado no nível de confiança da chave de API com que você se autentica.

Se você usar uma chave secreta (sk_): O Cord presume que você é um sistema interno confiável e devolve o objeto completo, incluindo os custos ocultos e as margens de lucro (costo).

Se você usar uma chave publicável (pk_): As chaves publicáveis ficam expostas no navegador (por exemplo, para exibir uma lista de preços em um site público em React). O Cord assume o risco e remove automaticamente o campo costo de todos os resultados em memória antes de serializar o JSON. Assim, as suas margens nunca vazam para o frontend público.

curl -X GET "https://cordhq.app/api/v1/productos?limit=50" \
     -H "Authorization: Bearer pk_live_yX..."

Com sk_live_..., o mesmo produto inclui costo:

{ "data": [ { "id": "7e3c9a1f-2b4d-4c6e-8f0a-b1d3e5f7a9c2", "sku": "LIC-PRO-24", "nombre": "Professional Annual License", "unidad": "license", "precio": 12000, "costo": 4000, "activo": true, "taxRate": null, "claveSat": "43231500", "claveUnidadSat": null } ] }

Com pk_live_..., costo simplesmente não aparece no objeto (não vem como null nem como 0 — a chave não existe):

{ "data": [ { "id": "7e3c9a1f-2b4d-4c6e-8f0a-b1d3e5f7a9c2", "sku": "LIC-PRO-24", "nombre": "Professional Annual License", "unidad": "license", "precio": 12000, "activo": true, "taxRate": null, "claveSat": "43231500", "claveUnidadSat": null } ] }

Observação: uma Publishable Key só pode ser usada em quatro rotas: GET /api/v1/productos, POST /api/v1/cotizaciones, GET /api/v1/elements/config e POST /api/v1/elements/ai-draft. Qualquer outra rota (criar produtos, ler clientes, cobrança) responde 403 insufficient_scope. Além disso, ela exige um header Origin ou Referer que corresponda aos domínios permitidos da sua organização, configurados em Configurações › Gerador de orçamentos incorporável. Uma pk_live_ sem domínios configurados responde 403 origin_allowlist_required; uma pk_test_ funciona a partir de qualquer origem.