Inserir Pedido de Venda

Visão Geral

Endpoint para criar pedidos de venda com suporte completo para:

Geração automática de cobranças
Emissão de notas fiscais (NF-e, NFC-e, NFS-e, NFS-e Nacional)
Controle de impostos retidos
Integração com plataformas de pagamento (Asaas, Cora, C6 Bank)

POST /api/v1/insert_sales_order

Autenticação

Parâmetro	Tipo	Obrigatório	Descrição
`access_token`	string	✓	Token de autenticação do usuário
`unit_token`	string	✓	Token da unidade onde o pedido será criado

Estrutura da Requisição

A requisição é organizada em grupos lógicos para facilitar a manutenção e compreensão:

{
  "access_token": "string",
  "unit_token": "string",
  "pv": { },
  "faturamento": { },
  "charge": { },
  "nf": { }
}

Grupo: `pv` (Pedido de Venda)

Informações básicas do pedido de venda e notificações.

Parâmetro	Tipo	Obrigatório	Default	Descrição
`id_token_contact`	string	✓	-	Token do cliente
`id_token_stock_item`	string	Condicional*	-	Token do produto/serviço principal
`products`	array	Condicional**	`null`	Lista de produtos para NF-e/NFC-e
`description`	string	✓	-	Descrição do pedido (utilizado na nota fiscal)
`value`	number	✓	-	Valor bruto do pedido
`quantity`	number	✗	`1`	Quantidade do item principal
`observation_sales`	string	✗	`null`	Observações internas do pedido
`notify_email_charge`	string	✗	`null`	E-mail para notificações sobre cobrança
`notify_email_nf`	string	✗	`null`	E-mail para notificações sobre nota fiscal
`notify_email_alert`	string	✗	`null`	E-mail para alertas gerais

* Obrigatório para serviços (NFS-e)
** Obrigatório para produtos (NF-e/NFC-e)

Estrutura do array products:

"products": [
  {
    "token": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "quantity": 1
  }
]

Campos alternativos aceitos:

product_id_tokens + product_qtys (formato legado com arrays separados)

Grupo: `faturamento`

Informações de categorização, previsão de pagamento e automações.

Parâmetro	Tipo	Obrigatório	Default	Descrição
`id_token_category`	string	✓	-	Token da categoria financeira
`estimated_payment_date`	string	✓	-	Data estimada de pagamento (formato: `YYYY-MM-DD`)
`id_token_bank_account`	string	✗	`null`	Token da conta bancária de recebimento
`id_token_project`	string	✗	`null`	Token do projeto vinculado
`recurrence`	boolean	✗	`false`	Criar pedido recorrente (mensalmente)
`in_automation`	boolean	✗	`false`	Criar entrada financeira automaticamente ao gerar cobrança
`conciliation`	boolean	✗	`false`	Habilitar conciliação bancária automática

Grupo: `charge` (Cobrança)

Configurações de pagamento e cobrança.

Parâmetro	Tipo	Obrigatório	Default	Descrição
`payment_type`	string	✓	-	Token do tipo de pagamento
`provider_bank`	string	✗	`null`	Provedor de cobrança: `asaas`, `cora`, `c6`
`installment_credit`	number	✗	`1`	Número de parcelas de crédito
`installments`	number	✗	`1`	Número de parcelas (sinônimo de installment)
`charge_pix_key`	string	✗	`null`	Chave PIX para cobrança
`notify_days_charge`	number	✗	`0`	Dias antes do vencimento para notificar
`bankAccountPayment`	string	Condicional***	`null`	Token da conta bancária para transferência
`estimated_payment_date`	string	✗	`null`	Data estimada de pagamento (alternativo)

*** Obrigatório quando payment_type for tipo Transferência

Configuração de Provedores

Você pode configurar o provedor de duas formas:

Forma 1 - Usando provider_bank:

"charge": {
  "provider_bank": "asaas"
}

Forma 2 - Usando flags individuais:

"charge": {
  "generate_with_asaas": true,
  "generate_c6": false,
  "generate_cora": false
}

Valores aceitos para `provider_bank`:

asaas - Integração com Asaas
cora - Integração com Cora
c6 - Integração com C6 Bank
null - Sem integração automática

Campos alternativos aceitos:

pix_key (sinônimo de charge_pix_key)
id_token_bank_account_payment (sinônimo de bankAccountPayment)

Grupo: `nf` (Nota Fiscal)

Informações fiscais, tributárias e de serviço do pedido.

Configurações Gerais

Parâmetro	Tipo	Obrigatório	Default	Descrição
`nf_kind`	string	✗	`null`	Tipo de nota: `nfse`, `nfsen`, `nfe`, `nfce`
`generateNFWebhook`	boolean	✗	`false`	Emitir NF automaticamente via webhook de pagamento
`tipo_documento`	string	✗	`null`	`0`=Entrada, `1`=Saída
`finalidade_emissao`	string	✗	`null`	`1`=Normal, `2`=Complementar, `3`=Ajuste, `4`=Devolução
`presenca_comprador`	string	✗	`null`	`0`=Não se aplica, `1`=Presencial, `2`=Internet, `3`=Teleatendimento, `4`=Entrega em domicílio, `9`=Outros
`consumidor_final`	string	✗	`null`	`0`=Não, `1`=Sim

Serviço

Parâmetro	Tipo	Obrigatório	Default	Descrição
`service_assoc_id_token`	string	✗	`null`	ID de associação do serviço
`service_id_token`	string	Condicional****	`null`	Token do serviço cadastrado (CNAEs e configurações)
`service_cod`	string	✗	`null`	Código do serviço
`service_location`	string	✗	`null`	Local da prestação do serviço

**** Obrigatório quando nf_kind for nfse ou nfsen

Campos alternativos aceitos:

service_assoc_id_token (sinônimo de service_assoc_id)
service_id_token (sinônimo de service_id)
service_code (sinônimo de service_cod)

Impostos e Valores

Parâmetro	Tipo	Obrigatório	Default	Descrição
`tax_service_gross_amount`	number	✗	`0.00`	Valor bruto do serviço
`tax_service_deduction_amount`	number	✗	`0.00`	Valor de dedução da base de cálculo
`tax_service_uncond_discount_amount`	number	✗	`0.00`	Desconto incondicional
`tax_service_cond_discount_amount`	number	✗	`0.00`	Desconto condicional
`tax_service_base_amount`	number	✗	`0.00`	Base de cálculo do ISS
`tax_iss_rate_percent`	number	✗	`0.00`	Alíquota do ISS (%)
`tax_iss_amount`	number	✗	`0.00`	Valor do ISS
`net_receivable_amount`	number	✗	`0.00`	Valor líquido a receber

Retenções Federais

Parâmetro	Tipo	Obrigatório	Default	Descrição
`ret_pis_rate_percent`	number	✗	`0.00`	Alíquota de retenção do PIS (%)
`ret_pis_amount`	number	✗	`0.00`	Valor retido de PIS
`ret_cofins_rate_percent`	number	✗	`0.00`	Alíquota de retenção do COFINS (%)
`ret_cofins_amount`	number	✗	`0.00`	Valor retido de COFINS
`ret_csll_rate_percent`	number	✗	`0.00`	Alíquota de retenção da CSLL (%)
`ret_csll_amount`	number	✗	`0.00`	Valor retido de CSLL
`ret_ir_rate_percent`	number	✗	`0.00`	Alíquota de retenção do IR (%)
`ret_ir_amount`	number	✗	`0.00`	Valor retido de IR
`ret_inss_rate_percent`	number	✗	`0.00`	Alíquota de retenção do INSS (%)
`ret_inss_amount`	number	✗	`0.00`	Valor retido de INSS
`ret_other_rate_percent`	number	✗	`0.00`	Alíquota de outras retenções (%)
`ret_other_amount`	number	✗	`0.00`	Valor de outras retenções
`ret_total_amount`	number	✗	`0.00`	Valor total das retenções

Frete e Transporte

Parâmetro	Tipo	Obrigatório	Default	Descrição
`freight_mode`	string	✗	`9`	`0`=Emitente, `1`=Destinatário, `2`=Terceiros, `9`=Sem frete
`freight_total`	number	✗	`0.00`	Valor total do frete
`local_destino`	string	✗	`1`	`1`=Operação interna, `2`=Interestadual, `3`=Exterior

Estrutura Aninhada (Alternativa)

Os campos de impostos e retenções também podem ser enviados em sub-objetos:

"nf": {
  "nf_kind": "nfse",
  "impostos": {
    "tax_service_gross_amount": 3500.00,
    "tax_iss_rate_percent": 5.00,
    "tax_iss_amount": 175.00
  },
  "retencoes": {
    "ret_pis_rate_percent": 0.65,
    "ret_pis_amount": 22.75,
    "ret_cofins_rate_percent": 3.00,
    "ret_cofins_amount": 105.00
  }
}

Exemplos de Requisição

Exemplo 1: Serviço com NFS-e + Asaas

curl -X POST 'https://portal.fipli.pro/api/v1/insert_sales_order' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "unit_token": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
    
    "pv": {
      "id_token_contact": "5c5545bb-4c1e-4612-bba5-06319320c73e",
      "id_token_stock_item": "e4b7d5ff-3367-4ed5-a714-0f50a72a6dd0",
      "description": "Serviço de consultoria estratégica",
      "value": 3500.00,
      "observation_sales": "Cliente preferencial",
      "notify_email_charge": "cliente@exemplo.com",
      "notify_email_nf": "financeiro@exemplo.com"
    },
    
    "faturamento": {
      "id_token_category": "a302d0a8-be82-4f68-ad51-1e2005f4ffdf",
      "estimated_payment_date": "2026-02-15",
      "in_automation": true,
      "conciliation": true
    },
    
    "charge": {
      "payment_type": "15516bea-4523-4a57-aad1-a1b5a4fc57fa",
      "provider_bank": "asaas",
      "installment_credit": 1
    },
    
    "nf": {
      "nf_kind": "nfse",
      "generateNFWebhook": true,
      "service_id": "gggggggg-hhhh-iiii-jjjj-kkkkkkkkkkkk",
      "tax_service_gross_amount": 3500.00,
      "tax_service_base_amount": 3500.00,
      "tax_iss_rate_percent": 5.00,
      "tax_iss_amount": 175.00,
      "ret_pis_rate_percent": 0.65,
      "ret_pis_amount": 22.75,
      "ret_cofins_rate_percent": 3.00,
      "ret_cofins_amount": 105.00,
      "ret_total_amount": 127.75,
      "net_receivable_amount": 3372.25
    }
  }'

Exemplo 2: Produtos com NF-e + Cora

curl -X POST 'https://portal.fipli.pro/api/v1/insert_sales_order' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "unit_token": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
    
    "pv": {
      "id_token_contact": "5c5545bb-4c1e-4612-bba5-06319320c73e",
      "products": [
        {
          "token": "hhhhhhhh-iiii-jjjj-kkkk-llllllllllll",
          "quantity": 2
        },
        {
          "token": "iiiiiiii-jjjj-kkkk-llll-mmmmmmmmmmmm",
          "quantity": 5
        }
      ],
      "description": "Venda de notebooks e mouses",
      "value": 1500.00,
      "notify_email_charge": "cliente@exemplo.com",
      "notify_email_nf": "cliente@exemplo.com"
    },
    
    "faturamento": {
      "id_token_category": "a302d0a8-be82-4f68-ad51-1e2005f4ffdf",
      "estimated_payment_date": "2026-02-10"
    },
    
    "charge": {
      "payment_type": "22222222-3333-4444-5555-666666666666",
      "provider_bank": "cora",
      "charge_pix_key": "contato@empresa.com.br"
    },
    
    "nf": {
      "nf_kind": "nfe",
      "freight_mode": "0",
      "freight_total": 50.00,
      "local_destino": "1"
    }
  }'

Exemplo 3: Serviço Recorrente com Parcelamento (C6 Bank)

curl -X POST 'https://portal.fipli.pro/api/v1/insert_sales_order' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "unit_token": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
    
    "pv": {
      "id_token_contact": "5c5545bb-4c1e-4612-bba5-06319320c73e",
      "id_token_stock_item": "e4b7d5ff-3367-4ed5-a714-0f50a72a6dd0",
      "description": "Mensalidade de serviço de suporte técnico",
      "value": 599.00,
      "notify_email_charge": "cliente@exemplo.com",
      "notify_email_alert": "alertas@exemplo.com"
    },
    
    "faturamento": {
      "id_token_category": "a302d0a8-be82-4f68-ad51-1e2005f4ffdf",
      "id_token_project": "33333333-4444-5555-6666-777777777777",
      "estimated_payment_date": "2026-02-05",
      "recurrence": true,
      "in_automation": true,
      "conciliation": true
    },
    
    "charge": {
      "payment_type": "15516bea-4523-4a57-aad1-a1b5a4fc57fa",
      "provider_bank": "c6",
      "installment_credit": 3,
      "notify_days_charge": 5
    },
    
    "nf": {
      "nf_kind": "nfse",
      "service_id": "gggggggg-hhhh-iiii-jjjj-kkkkkkkkkkkk",
      "tax_service_gross_amount": 599.00,
      "tax_service_base_amount": 599.00,
      "tax_iss_rate_percent": 5.00,
      "tax_iss_amount": 29.95
    }
  }'

Exemplo 4: Pedido Simples (Sem Cobrança Automática)

curl -X POST 'https://portal.fipli.pro/api/v1/insert_sales_order' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "unit_token": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
    
    "pv": {
      "id_token_contact": "5c5545bb-4c1e-4612-bba5-06319320c73e",
      "id_token_stock_item": "e4b7d5ff-3367-4ed5-a714-0f50a72a6dd0",
      "description": "Pedido de venda - exemplo",
      "value": 10.99,
      "observation_sales": "Observação do pedido"
    },
    
    "faturamento": {
      "id_token_category": "a302d0a8-be82-4f68-ad51-1e2005f4ffdf",
      "estimated_payment_date": "2026-02-10"
    },
    
    "charge": {
      "payment_type": "15516bea-4523-4a57-aad1-a1b5a4fc57fa"
    },
    
    "nf": {
      "nf_kind": "nfse",
      "service_id": "gggggggg-hhhh-iiii-jjjj-kkkkkkkkkkkk"
    }
  }'

Respostas

Sucesso (200 OK)

{
  "success": true,
  "message": "Sales order inserted successfully",
  "data": {
    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "cod_orders": "PV-2026-0001"
  }
}

Erros

Status	Mensagem	Descrição
`400`	`Missing required fields`	Campos obrigatórios não foram enviados
`403`	`Invalid data`	Token de autenticação inválido
`422`	`Invalid parameter format`	Formato de parâmetro incorreto
`500`	`Erro ao inserir pedido`	Erro interno no servidor

Exemplo de erro:

{
  "success": false,
  "error": "Missing required fields",
  "details": {
    "missing_fields": ["pv.value", "faturamento.estimated_payment_date"],
    "group": "pv"
  }
}

Notas Importantes

Configuração de Provedores de Pagamento

O campo provider_bank oferece uma forma simplificada de configurar o provedor:

// Forma recomendada
"charge": {
  "provider_bank": "asaas"
}

// Equivalente a:
"charge": {
  "generate_with_asaas": true,
  "generate_c6": false,
  "generate_cora": false
}

Cálculo de Impostos

Os valores de retenção devem ser calculados conforme a legislação vigente. O campo net_receivable_amount deve considerar todas as retenções aplicadas:

net_receivable_amount = value - ret_total_amount

Emissão Automática de NF

Para habilitar a emissão automática via webhook:

Configure nf.generateNFWebhook: true
Certifique-se de que todos os dados fiscais estejam completos
A nota será emitida automaticamente após confirmação do pagamento

Pedidos Recorrentes

Quando faturamento.recurrence: true:

O sistema cria automaticamente novos pedidos no 1º dia de cada mês
Os valores e configurações são mantidos
As datas de vencimento são ajustadas automaticamente

Produtos vs Serviços

Serviços (NFS-e/NFS-e Nacional): Use pv.id_token_stock_item
Produtos (NF-e/NFC-e): Use array pv.products com tokens e quantidades

Integrações de Pagamento

Os provedores disponíveis são:

asaas: Integração com Asaas (boleto, PIX, cartão)
cora: Integração com Cora (PIX, boleto)
c6: Integração com C6 Bank (boleto, PIX)
null: Sem integração automática (cobrança manual)

Tipos de Pagamento

O campo charge.payment_type deve conter o token de um tipo de pagamento cadastrado no sistema. Exemplos comuns:

Boleto bancário
PIX
Transferência bancária
Cartão de crédito
Dinheiro

Validações Importantes

Se provider_bank for definido, é recomendado ter faturamento.id_token_bank_account configurado
Para PIX, o campo charge_pix_key é obrigatório
Para transferência, o campo bankAccountPayment é obrigatório
O número de parcelas (installment_credit) deve ser >= 1
Campos de retenção e impostos devem ter valores numéricos válidos

Retrocompatibilidade

A API mantém compatibilidade com formatos legados:

Campos podem ser enviados diretamente no body (fora dos grupos)
Arrays de produtos podem usar product_id_tokens + product_qtys
Campos têm múltiplos sinônimos aceitos (ex: id_token_contact ou id_token_contact)

Visão Geral​

Autenticação​

Estrutura da Requisição​

Grupo: pv (Pedido de Venda)​

Grupo: faturamento​

Grupo: charge (Cobrança)​

Configuração de Provedores​

Valores aceitos para provider_bank:​

Grupo: nf (Nota Fiscal)​

Configurações Gerais​

Serviço​

Impostos e Valores​

Retenções Federais​

Frete e Transporte​

Estrutura Aninhada (Alternativa)​

Exemplos de Requisição​

Exemplo 1: Serviço com NFS-e + Asaas​

Exemplo 2: Produtos com NF-e + Cora​

Exemplo 3: Serviço Recorrente com Parcelamento (C6 Bank)​

Exemplo 4: Pedido Simples (Sem Cobrança Automática)​

Respostas​

Sucesso (200 OK)​

Erros​

Notas Importantes​

Configuração de Provedores de Pagamento​

Cálculo de Impostos​

Emissão Automática de NF​

Pedidos Recorrentes​

Produtos vs Serviços​

Integrações de Pagamento​

Tipos de Pagamento​

Validações Importantes​

Retrocompatibilidade​

Visão Geral

Autenticação

Estrutura da Requisição

Grupo: `pv` (Pedido de Venda)

Grupo: `faturamento`

Grupo: `charge` (Cobrança)

Configuração de Provedores

Valores aceitos para `provider_bank`:

Grupo: `nf` (Nota Fiscal)

Configurações Gerais

Serviço

Impostos e Valores

Retenções Federais

Frete e Transporte

Estrutura Aninhada (Alternativa)

Exemplos de Requisição

Exemplo 1: Serviço com NFS-e + Asaas

Exemplo 2: Produtos com NF-e + Cora

Exemplo 3: Serviço Recorrente com Parcelamento (C6 Bank)

Exemplo 4: Pedido Simples (Sem Cobrança Automática)

Respostas

Sucesso (200 OK)

Erros

Notas Importantes

Configuração de Provedores de Pagamento

Cálculo de Impostos

Emissão Automática de NF

Pedidos Recorrentes

Produtos vs Serviços

Integrações de Pagamento

Tipos de Pagamento

Validações Importantes

Retrocompatibilidade