Usando templates de novos registros na API

A API expõe um conjunto de queries no padrão getNewXXX que devolvem um objeto não persistido já preenchido com os valores default daquele tipo de registro. A ideia é que você use esse retorno como base para construir o input da mutation correspondente — em vez de descobrir manualmente todos os campos obrigatórios e seus defaults.

Exemplos disponíveis: getNewProduct, getNewPerson, getNewInvoice, getNewAccount, getNewActivity, getNewCategory, getNewContact, getNewLicensee, entre outras.

Algumas dessas queries aceitam o argumento based_on_id: passando o ID de um registro existente, o objeto retornado vem clonado a partir dele — útil para duplicar produtos, pessoas, vendas etc.

Por que usar?

• Você não precisa adivinhar quais campos são obrigatórios. Os valores default vêm do servidor, refletindo as regras do licenciado.
• Campos sequenciais (como code em Product) já vêm com o próximo valor disponível, evitando colisões.
• Defaults dependentes de configuração (regime tributário, moeda, séries de NF-e etc.) vêm corretos para o licenciado autenticado, sem o cliente precisar consultar essas configurações antes.
• Reduz divergência entre frontend e API: o frontend nativo do Fácil123 usa exatamente essas queries para popular o formulário de criação.

Exemplo — criando um produto

Primeiro busque o template:

curl -X POST https://app.facil123.com.br/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -d '{
    "query": "{ getNewProduct { name code unit_id kind price price_method origin volumes gross_weight net_weight scale_enabled archived } }"
  }'

Resposta típica:

{
  "data": {
    "getNewProduct": {
      "name": null,
      "code": "9764",
      "unit_id": null,
      "kind": "materia_prima",
      "price": "0.0",
      "price_method": "manual",
      "origin": 0,
      "volumes": "0.0",
      "gross_weight": "0.0",
      "net_weight": "0.0",
      "scale_enabled": false,
      "archived": false
    }
  }
}

Repare que:

• code já vem com o próximo valor sequencial ("9764") — você pode mantê-lo ou sobrescrever.
• kind, price_method, origin e os pesos vêm com defaults sensatos.
• Campos como name e unit_id ficam null porque dependem de você.

Agora basta sobrescrever os campos necessários e enviar para createProduct:

curl -X POST https://app.facil123.com.br/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -d '{
    "query": "mutation($attributes: ProductInput!) { createProduct(attributes: $attributes) { id name code } }",
    "variables": {
      "attributes": {
        "name": "Camiseta",
        "code": "9764",
        "unit_id": "1",
        "kind": "mercadoria_para_revenda",
        "price": "49.90",
        "price_method": "manual",
        "origin": 0,
        "volumes": "0.0",
        "gross_weight": "0.0",
        "net_weight": "0.0",
        "scale_enabled": false,
        "archived": false
      }
    }
  }'

Clonando um registro existente

Para usar um produto existente como base, passe based_on_id:

{
  getNewProduct(based_on_id: "2468752") {
    name
    code
    unit_id
    kind
    price
  }
}

O retorno traz os campos copiados do produto 2468752, com code já alterado para o próximo sequencial disponível. O mesmo argumento existe em getNewPerson, getNewInvoice e em várias outras queries — consulte o schema para descobrir quais (veja Explorando a API por introspecção).

Cuidados ao mandar para a mutation

Lembre-se que o tipo de leitura (Product) tem mais campos do que o tipo de input (ProductInput). O retorno de getNewProduct traz apenas os campos que você pediu na query, então o ideal é selecionar exatamente os atributos que existem em ProductInput — assim o objeto já fica pronto para virar variables.attributes na mutation, sem filtragem extra.

Se você selecionar campos que não existem no input (como associações resolvidas — unit { name } em vez de unit_id), a mutation vai falhar com erro de validação do GraphQL.