11. 🛍️ Pedidos de Venda

Consulta de Nota Fiscal do Pedido

get

Endpoint para consulta de nota fiscal vinculada a um pedido

Retorna as informações da Nota Fiscal Eletrônica (NF-e) associada ao pedido, incluindo status atual, chave de acesso e link para o DANFE.

Informações retornadas:

UUID da nota fiscal
Chave de acesso (versão segura)
Status atual da NF-e
URL pública do DANFE para visualização/download

Status possíveis da NF-e:

NAO_TRANSMITIDA: NF-e criada mas não enviada à SEFAZ
EM_TRANSMISSAO: NF-e sendo processada pela SEFAZ
ACEITA: NF-e aceita e válida fiscalmente
REJEITADA: NF-e rejeitada pela SEFAZ
CANCELADA: NF-e cancelada após aceita
DENEGADA: NF-e denegada pela SEFAZ

Uso típico:

Consulta de status de transmissão
Obtenção de link para DANFE
Verificação de dados da NF-e gerada

Autorizações

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de rota

pedido_idstringObrigatório

UUID do pedido

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

Respostas

200

Dados da nota fiscal

application/json

401

Usuário não autenticado

application/json

404

Nota fiscal não encontrada

get

/pedidos/{pedido_id}/nota_fiscal

GET /api/v2/pedidos/{pedido_id}/nota_fiscal HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "nota_fiscal": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "chave_acesso": "35210812345678000190550010000012341234567890",
    "status": "ACEITA",
    "danfe_url": "https://api.maino.com.br/danfe/f47ac10b-58cc-4372-a567-0e02b2c3d479/35210812345678000190550010000012341234567890"
  }
}

Criação de Nota Fiscal de Pedido

post

Endpoint para finalização de pedido com geração automática de NF-e

Este endpoint realiza a finalização de um pedido de venda, executando todas as validações fiscais necessárias e gerando automaticamente a Nota Fiscal Eletrônica (NF-e).

Processo de finalização:

Validação completa do pedido (produtos, quantidades, dados fiscais)
Verificação de status do cliente (ativo, dados completos)
Validação de estoque disponível
Geração automática da NF-e com dados fiscais corretos
Atualização do status do pedido para "finalizado"

Validações realizadas:

Integridade dos dados do pedido
Disponibilidade de estoque
Dados fiscais do cliente
Configurações tributárias
Certificado digital válido

Comportamento transacional:

Operação executada com lock no pedido
Rollback automático em caso de erro
Garantia de consistência dos dados

Uso típico:

Finalização de pedidos aprovados
Geração de NF-e para faturamento
Processamento de vendas em lote

Autorizações

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de rota

pedido_idstringObrigatório

UUID do pedido

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

Respostas

401

Usuário não autenticado

application/json

404

Pedido não encontrado

422

Erro de validação do pedido

application/json

post

/pedidos/{pedido_id}/nota_fiscal

POST /api/v2/pedidos/{pedido_id}/nota_fiscal HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "error": "Chave de API inválida"
}

Cancelamento de Nota Fiscal do Pedido

delete

Endpoint para cancelamento de nota fiscal e reversão do pedido

Este endpoint realiza o cancelamento de uma nota fiscal já gerada, revertendo o pedido para seu estado anterior. A operação é executada com segurança transacional.

Processo de cancelamento:

Verificação se a NF-e pode ser cancelada (regras fiscais)
Cancelamento da NF-e na SEFAZ (se já transmitida)
Reversão do pedido para status anterior
Reposição de estoque (se aplicável)

Condições para cancelamento:

NF-e deve estar em status que permite cancelamento
Prazo fiscal para cancelamento não deve ter expirado
Não deve haver dependências que impeçam o cancelamento

Comportamento transacional:

Operação executada com lock no pedido
Rollback automático em caso de erro
Garantia de consistência dos dados

Uso típico:

Correção de pedidos finalizados incorretamente
Cancelamento por solicitação do cliente
Ajustes em casos de erro no faturamento

Autorizações

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de rota

pedido_idstringObrigatório

UUID do pedido

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

Respostas

204

Nota fiscal cancelada com sucesso

401

Usuário não autenticado

application/json

404

Pedido não encontrado

delete

/pedidos/{pedido_id}/nota_fiscal

DELETE /api/v2/pedidos/{pedido_id}/nota_fiscal HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

Sem conteúdo

Lista pedidos

get

Lista pedidos de venda com filtros básicos.

Autorizações

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de consulta

statusstringOpcional

Filtrar por status do pedido

exportacaobooleanOpcional

Filtrar pedidos de exportação (true) ou mercado interno (false)

pageintegerOpcional

Número da página para paginação

per_pageintegerOpcional

Quantidade de registros por página (máx: 100, padrão: 30)

Respostas

200

Lista de pedidos

application/json

401

Não autorizado

application/json

get

/pedidos

GET /api/v2/pedidos HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "pedidos": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "numero": "PED-2023-001234",
      "status": "CONFIRMADO",
      "exportacao": false,
      "moeda": "BRL",
      "taxa_cambio": 1,
      "cliente": {
        "documento": "12.345.678/0001-90",
        "razao_social": "Cliente Exemplo LTDA",
        "nome_fantasia": "Cliente Exemplo",
        "inscricao_estadual": "123456789",
        "endereco": "Rua Exemplo",
        "numero": "100",
        "complemento": "Sala 1",
        "cep": "01310-100",
        "bairro": "Centro",
        "municipio": "3550308"
      },
      "transportadora": {
        "documento": "98.765.432/0001-10",
        "razao_social": "Transportadora Exemplo LTDA",
        "nome_fantasia": "Trans Exemplo",
        "inscricao_estadual": "987654321",
        "endereco": "Av. Transportes",
        "numero": "500",
        "complemento": null,
        "cep": "04567-890",
        "bairro": "Industrial",
        "municipio": "3550308"
      },
      "representante": {
        "nome": "João Vendedor",
        "email": "[email protected]"
      },
      "itens": [
        {
          "codigo": "PROD001",
          "descricao": "Produto Exemplo",
          "quantidade": 10,
          "status": "OK"
        }
      ],
      "cobranca": {
        "numero_fatura": "FAT-001",
        "dt_inicio_pagamento": "2023-12-01",
        "forma_pagamento": "Boleto",
        "tipo_de_receita": "Venda de Mercadorias",
        "plano_de_conta": "1.1.01 - Receitas de Vendas",
        "parcelas": [
          {
            "numero_titulo": "FAT-001/1",
            "valor": 1000,
            "data_vencimento": "2023-12-15"
          }
        ]
      },
      "transporte": {
        "quantidade_volumes": 2,
        "especie_volumes": "Caixa",
        "numeracao_volumes": "1-2",
        "marca_volumes": "FRAGIL",
        "peso_bruto": 25.5,
        "peso_liquido": 23
      }
    }
  ],
  "pagination": {
    "total": 150,
    "previous_page": null,
    "next_page": "/pedidos?page=2"
  }
}

Cria pedido

post

Cria um novo pedido de venda.

Parâmetros de controle:

transmite: "0" (apenas pedido) ou "1" (pedido + NF-e) - Obrigatório
async: "0" (síncrono) ou "1" (assíncrono) - Opcional
url: Webhook para callback (obrigatório se async=1 ou transmite=1)
gerar_nota_fiscal_sem_transmissao: true/false - Gera NF-e sem transmitir
numero_processo: Número de processo já cadastrado no sistema

Autorizações

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de consulta

transmitestringObrigatório

0=apenas pedido, 1=pedido+NF-e:

0
1

asyncstringOpcional

0=síncrono, 1=assíncrono

urlstringOpcional

URL de callback (obrigatório se async=1 ou transmite=1)

gerar_nota_fiscal_sem_transmissaobooleanOpcional

Gera NF-e sem transmitir

numero_processostringOpcional

Número do processo já cadastrado

origemstringOpcional

Origem da requisição (vtex, maino_ia, etc)

Corpo

numerostringObrigatório

Número do pedido (campo com unicidade)

orcamentobooleanOpcional

true=orçamento, false=pedido (padrão: false)

exportacaobooleanOpcional

true=exportação, false=mercado interno (padrão: false)

revendabooleanOpcional

true se pedido para revenda

consumidor_finalbooleanOpcional

true se cliente é consumidor final

tabela_de_vendastringOpcional

Código da tabela de venda

statusstringOpcional

Status personalizado do pedido

modalidade_freteinteger · enumOpcional

0=CIF, 1=FOB, 2=Terceiros, 3=Próprio Remetente, 4=Próprio Destinatário, 9=Sem Transporte

Valores possíveis:

valor_fretenumber · floatOpcional

valor_outras_despesasnumber · floatOpcional

valor_seguronumber · floatOpcional

informacoes_complementaresstringOpcional

informacoes_ao_fiscostringOpcional

quantidade_volumesnumberOpcional

especie_volumesstringOpcional

numeracao_volumesstringOpcional

marca_volumesstringOpcional

codigo_iso_moedastringOpcional

Código ISO da moeda (ex: BRL, USD)

taxa_cambionumber · floatOpcional

cfopstringOpcional

CFOP da nota fiscal (sobrescreve automático)

natureza_da_operacaostringOpcional

representante_emailstringOpcional

Email do representante/vendedor cadastrado

tagsstring[]Opcional

Tags do pedido

indicador_presencainteger · enumOpcional

Indicador de presença

Valores possíveis:

indicador_intermediadorinteger · enumOpcional

0=sem intermediador, 1=com intermediador

Valores possíveis:

inf_intermed_cnpjstringOpcional

CNPJ do intermediador

inf_intermed_id_cad_int_transtringOpcional

ID do intermediador

observacaostringOpcional

valor_comissaonumber · floatOpcional

datastring · dateOpcional

Data do pedido (padrão: hoje)

data_de_entregastring · dateOpcional

exibe_calculo_antecipacao_icmsbooleanOpcional

calculo_antecipacao_icms_inclui_fretebooleanOpcional

calculo_antecipacao_icms_inclui_ipibooleanOpcional

Respostas

401

Não autorizado

application/json

post

/pedidos

POST /api/v2/pedidos?transmite=text HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 876

{
  "pedido": {
    "numero": "PED-2023-001234",
    "exportacao": false,
    "modalidade_frete": 0,
    "valor_frete": 50,
    "observacao": "Pedido de exemplo",
    "data": "2023-12-01",
    "data_de_entrega": "2023-12-05",
    "cliente": {
      "somente_busca": false,
      "cnpj": "12345678000190",
      "razao_social": "Cliente Exemplo LTDA",
      "nome_fantasia": "Cliente Exemplo",
      "cep": "01310100",
      "uf": "SP",
      "endereco": "Rua Exemplo",
      "numero": "100",
      "complemento": "Sala 1",
      "bairro": "Centro",
      "municipio": "3550308",
      "email": "[email protected]",
      "ddd": "11",
      "telefone": "999999999"
    },
    "transportadora": {
      "somente_busca": true,
      "cnpj": "98765432000110"
    },
    "transporte": {
      "quantidade_volumes": 1,
      "especie_volumes": "Caixa",
      "peso_bruto": 10.5,
      "peso_liquido": 9
    },
    "itens": [
      {
        "codigo": "PROD001",
        "descricao": "Produto Exemplo",
        "quantidade": 2,
        "pu": 100
      }
    ],
    "cobranca": {
      "forma_pagamento": 2,
      "plano_de_conta": "1.1.01",
      "parcelas": [
        {
          "valor": 200,
          "data_vencimento": "2023-12-15"
        }
      ]
    }
  }
}

401

Não autorizado

{
  "error": "text"
}

Exibe pedido

get

Retorna detalhes completos de um pedido

Autorizações

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de rota

idstringObrigatório

UUID do pedido

Respostas

200

Detalhes do pedido

application/json

401

Não autorizado

application/json

404

Pedido não encontrado

get

/pedidos/{id}

GET /api/v2/pedidos/{id} HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "pedido": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "numero": "PED-2023-001234",
    "status": "CONFIRMADO",
    "exportacao": false,
    "moeda": "BRL",
    "taxa_cambio": 1,
    "cliente": {
      "cnpj": "12.345.678/0001-90",
      "razao_social": "Cliente Exemplo LTDA",
      "nome_fantasia": "Cliente Exemplo",
      "inscricao_estadual": "123456789",
      "endereco": "Rua Exemplo",
      "numero": "100",
      "complemento": "Sala 1",
      "cep": "01310100",
      "bairro": "Centro",
      "municipio": "3550308",
      "email": "[email protected]",
      "ddd": "11",
      "telefone": "999999999"
    },
    "transportadora": {
      "cnpj": "98.765.432/0001-10",
      "razao_social": "Transportadora Exemplo LTDA",
      "nome_fantasia": "Trans Exemplo",
      "inscricao_estadual": "987654321",
      "endereco": "Av. Transportes",
      "numero": "500",
      "complemento": null,
      "cep": "04567890",
      "bairro": "Industrial",
      "municipio": "3550308",
      "email": "[email protected]",
      "ddd": "11",
      "telefone": "888888888"
    },
    "representante": {
      "nome": "João Vendedor",
      "email": "[email protected]"
    },
    "itens": [
      {
        "codigo": "PROD001",
        "descricao": "Produto Exemplo",
        "quantidade": 10,
        "status": "OK"
      }
    ],
    "cobranca": {
      "numero_fatura": "FAT-001",
      "dt_inicio_pagamento": "2023-12-01",
      "forma_pagamento": "Boleto",
      "tipo_de_receita": "Venda de Mercadorias",
      "plano_de_conta": "1.1.01 - Receitas de Vendas",
      "parcelas": [
        {
          "numero_titulo": "FAT-001/1",
          "valor": 1000,
          "data_vencimento": "2023-12-15"
        }
      ]
    },
    "transporte": {
      "quantidade_volumes": 2,
      "especie_volumes": "Caixa",
      "numeracao_volumes": "1-2",
      "marca_volumes": "FRAGIL",
      "peso_bruto": 25.5,
      "peso_liquido": 23
    }
  }
}

Atualiza pedido

put

Atualiza um pedido existente. Apenas pedidos em digitação podem ser alterados. Aceita os mesmos parâmetros do POST.

Autorizações

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de rota

idstringObrigatório

UUID do pedido

Corpo

objectOpcional

Mesma estrutura do POST - Cria pedido

Respostas

401

Não autorizado

application/json

404

Pedido não encontrado

put

/pedidos/{id}

PUT /api/v2/pedidos/{id} HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

{
  "error": "text"
}

Excluir pedido

delete

Exclui um pedido (apenas se não faturado)

Autorizações

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de rota

idstringObrigatório

UUID do pedido

Respostas

401

Não autorizado

application/json

404

Pedido não encontrado

delete

/pedidos/{id}

DELETE /api/v2/pedidos/{id} HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "error": "text"
}

Atualiza status do pedido

put

Atualiza apenas o status de um pedido

Autorizações

AuthorizationstringObrigatório

Token JWT de Autenticação Token obtido através do endpoint /authentication. Formato: Bearer {seu_token_jwt} Exemplo: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Validade: Sem expiração

Parâmetros de rota

idstringObrigatório

UUID do pedido

Parâmetros de consulta

statusstringObrigatório

Descrição do novo status do pedido

Respostas

401

Não autorizado

application/json

put

/pedidos/{id}/update_status

PUT /api/v2/pedidos/{id}/update_status?status=text HTTP/1.1
Host: api.maino.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

401

Não autorizado

{
  "error": "text"
}

hashtagConsulta de Nota Fiscal do Pedido

hashtagCriação de Nota Fiscal de Pedido

hashtagCancelamento de Nota Fiscal do Pedido

hashtagLista pedidos

hashtagCria pedido

hashtagExibe pedido

hashtagAtualiza pedido

hashtagExcluir pedido

hashtagAtualiza status do pedido

Consulta de Nota Fiscal do Pedido

Criação de Nota Fiscal de Pedido

Cancelamento de Nota Fiscal do Pedido

Lista pedidos

Cria pedido

Exibe pedido

Atualiza pedido

Excluir pedido

Atualiza status do pedido