Exemplos de uso da API

Criando uma venda

Criar uma venda envolve mais peças do que criar um produto: além dos atributos da venda em si, é preciso resolver a tributação de cada item (CFOP, CST, base de cálculo, alíquotas) e definir as parcelas. Felizmente a API expõe queries auxiliares que entregam tudo pronto.

O fluxo recomendado é:

getNewInvoice para obter os defaults da venda (emittedat, invoicelaneid, etc.) — veja Usando templates de novos registros na API.
findPremisesAndCalculateTaxesForInvoiceProducts para calcular a tributação dos produtos.
Definir as parcelas — usando paymentplan_id (auto-gerado) ou invoice_bills_attributes (manual).
Chamar createInvoice com tudo junto.

Os exemplos seguem a convenção de nomear as operações com o nome da sua empresa e a chamada utilizada — troque padariaDoJoao pelo nome da sua.

Passo 1 — Template da venda

curl -X POST https://app.facil123.com.br/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -d '{
    "query": "query padariaDoJoao_getNewInvoice { getNewInvoice { emitted_at invoicelane_id document_type departure_or_entry destination } }"
  }'

Resposta típica:

{
  "data": {
    "getNewInvoice": {
      "emitted_at": "2026-04-29T23:45:25.572-03:00",
      "invoicelane_id": 9533,
      "document_type": null,
      "departure_or_entry": null,
      "destination": null
    }
  }
}

Guarde os valores que vieram preenchidos — em especial invoicelane_id e emitted_at, que são obrigatórios na criação.

Passo 2 — Calcular a tributação dos produtos

A query findPremisesAndCalculateTaxesForInvoiceProducts recebe a lista de produtos no formato de InvoiceProductAttributesInput (mínimo: product_id, quantity, unit_price) e devolve o mesmo objeto com todos os campos de tributação preenchidos — CFOP, CST, alíquotas, valores de ICMS/PIS/COFINS/IPI etc.

Selecione na query exatamente os campos que existem no input — assim o resultado já vem pronto para virar invoice_products_attributes na mutation:

curl -X POST https://app.facil123.com.br/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -d '{
    "query": "query padariaDoJoao_calculaTributos($products: [InvoiceProductAttributesInput!]!) { findPremisesAndCalculateTaxesForInvoiceProducts(invoice_products: $products, operationkind_id: 3, recipient_id: 1106) { product_id quantity unit_price cfop_id classtrib_id icmscst_id ipicst_id piscofinscst_id regime status icms_basis icms_tax icms_value icms_taxed icms_basis_reduction_method icms_basis_reduction_value icms_fcp_value icms_use_ipi_on_basis icmssimples_basis icmssimples_tax icmssimples_value icmssimples_taxed icmsst_basis icmsst_basis_reduction_method icmsst_basis_reduction_value icmsst_destination_tax icmsst_fcp_tax icmsst_fcp_value icmsst_mva icmsst_strategy icmsst_taxed icmsst_value ipi_basis ipi_tax ipi_value pis_basis pis_tax pis_value cofins_basis cofins_tax cofins_value difal_basis difal_strategy difal_taxed difal_value fcp_tax federal_taxload federal_taxload_value state_taxload state_taxload_value taxload_key taxloadsource_id calculate_taxload } }",
    "variables": {
      "products": [
        { "product_id": 704884, "quantity": "1", "unit_price": "1.10" }
      ]
    }
  }'

Existem várias outras colunas de tributação (DIFAL completo, IBS/CBS, ICMS monofásico, ICMS-ST retido). Inclua na query as que se aplicam ao seu cenário — a fonte da verdade é o input type InvoiceProductAttributesInput. O ideal é selecionar todos os campos do input que possam ser populados, para evitar perder valores calculados.

A resposta traz, por exemplo:

{
  "product_id": 704884,
  "quantity": "1.0",
  "unit_price": "1.1",
  "cfop_id": "314",
  "icmscst_id": 2,
  "ipicst_id": 15,
  "piscofinscst_id": 10,
  "regime": "simple",
  "status": "suggested_by_system",
  "icms_basis": "1.1",
  "icms_tax": "4.0",
  "icms_value": "0.04",
  "...": "..."
}

Passo 3 — Definir as parcelas

Você tem duas opções:

Auto-geração via plano — passe paymentplan_id na mutation e o sistema cria as parcelas conforme a configuração do plano.

Manual — passe invoice_bills_attributes com cada parcela explicitamente:

{
  "invoice_bills_attributes": [
    { "expire_at": "2026-05-15T00:00:00-03:00", "value": "0.65", "paymenttype_id": 1 },
    { "expire_at": "2026-06-15T00:00:00-03:00", "value": "0.62", "paymenttype_id": 1 }
  ]
}

A soma das parcelas deve bater com o total da venda.

Passo 4 — Criar a venda

Com tudo em mãos, monte a mutation. O array invoice_products_attributes é exatamente o retorno do passo 2 (sem nenhuma transformação):

curl -X POST https://app.facil123.com.br/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -d '{
    "query": "mutation padariaDoJoao_criaVenda($attributes: InvoiceInput!) { createInvoice(attributes: $attributes) { id total emitted_at } }",
    "variables": {
      "attributes": {
        "operationkind_id": 3,
        "recipient_id": 1106,
        "invoicelane_id": 9533,
        "departure_or_entry": "departure",
        "destination": "normal",
        "document_type": "nfe",
        "emitted_at": "2026-04-29T22:00:00-03:00",
        "paymentplan_id": "1",
        "invoice_products_attributes": [
          {
            "product_id": 704884,
            "quantity": "1.0",
            "unit_price": "1.1",
            "cfop_id": "314",
            "icmscst_id": 2,
            "ipicst_id": 15,
            "piscofinscst_id": 10,
            "regime": "simple",
            "status": "suggested_by_system",
            "icms_basis": "1.1",
            "icms_tax": "4.0",
            "icms_value": "0.04"
          }
        ]
      }
    }
  }'

Resposta:

{
  "data": {
    "createInvoice": {
      "id": 6999884,
      "total": "1.27",
      "emitted_at": "2026-04-29T22:00:00.000-03:00"
    }
  }
}