# Lista de pedidos de venda Retorna lista de pedidos de Venda. Endpoint: GET /api/v3/sale-orders Version: 3.0.0 Security: OAuth2 ## Header parameters: - `CPlug-Company-Id` (number, required) Id da Empresa (Company). Você pode localizar os IDs das empresas no _endpoint_ de listagem de empresas. Example: 12 ## Query parameters: - `search_term` (string) Filtro pelo Nome do cliente ou ID do pedido de venda. Example: "123" - `sale_orders_id` (string) Filtra pelos IDs dos pedidos de venda. Pode passar mais de um ID numérico separado por virgula. Example: "1,2,3" - `item_name` (string) Filtro pelo Nome do produto. Example: "Banana" - `item_id` (integer) Filtro pelo ID do produto. Example: 123 - `source_type` (string) Canal de venda. - erp - pdv - store - totem Enum: "erp", "pdv", "store", "totem" - `unique_id` (string) Filtro pelo ID único da venda. Example: "cf2e0a5e-aa58-4181-9c9b" - `seller_id` (integer) Filtro pelo ID do vendedor. Example: 123 - `user_id` (integer) Filtro pelo ID do usuário. Example: 123 - `customer_name` (string) Filtro pelo Nome do cliente. Example: "CPlug" - `customer_document` (string) Número do documento do cliente. Pode ser CPF ou CNPJ. Example: "43496196000" - `customer_id` (integer) Filtro pelo ID do cliente. Example: 123 - `start_date_time` (string) Filtra por dados que foram registrados a partir de uma data. (Formato: YYYY-MM-DDThh:mm:ss+hh:mm). - `end_date_time` (string) Filtra por dados que foram registrados até uma data. (Formato: YYYY-MM-DDThh:mm:ss+hh:mm). - `status` (string) Status do pedido de venda - canceled pedido de venda cancelada. - closed pedido de venda fechada. - in_preparation pedido em preparação. - in_route pedido em entrega. - open pedido de venda aberta. - reserved pedido de venda reservada. - takeout pedido para retirar. - waiting pedido de venda em espera. Enum: "canceled", "closed", "in_preparation", "in_route", "open", "reserved", "takeout", "waiting" - `delivery_type` (string) Tipo de entrega do pedido: - delivery entrega. - withdrawal retirada. Enum: "delivery", "withdrawal" - `with_items` (boolean) Indica se devolve a lista de itens da venda. - `with_payments` (boolean) Indica se devolve a lista de pagamentos da venda. - `with_seller` (boolean) Indica se devolve quem fez a venda. - `sort_by` (string) Campo para ordenação. Exemplo: - created_at Data de criação do pedido de venda. Enum: "created_at" - `sorting_type` (string) Tipo de ordenação. Exemplo: - asc Ascendente - desc Descendente Enum: "asc", "desc" - `total_from` (number) Filtra por total do pedido de venda maior ou igual que o valor informado. Example: 100 - `total_to` (number) Filtra por total do pedido de venda menor ou igual que o valor informado. Example: 100 - `page` (number) Indica a página da paginação. - `per_page` (number) Indica a quantidade de itens por página. - `updated_from` (string) Filtra por dados que foram atualizadas a partir de uma data. (Formato: YYYY-MM-DDThh:mm:ss+hh:mm). - `deleted` (string) Filtro para indicar se deve retornar dados apagados ou não. Enum: "not_include", "include", "only" ## Response 200 fields (application/json): - `data` (object) - `data.sale_orders` (array) Representa a lista de pedidos de venda - `data.sale_orders.id` (integer) Identificador numérico único do pedido de venda. Example: 123 - `data.sale_orders.number` (integer) Número do pedido de venda. Example: 123 - `data.sale_orders.unique_id` (string) Identificador único do pedido de venda. Example: "cf2e0a5e-aa58-4181-9c9b-47702bd2be99" - `data.sale_orders.customer` (object) Dados do cliente - `data.sale_orders.customer.id` (integer) Identificador único do Cliente. Example: 123 - `data.sale_orders.customer.name` (string) Nome do cliente pessoa física ou Razão social. Example: "Nome do Cliente" - `data.sale_orders.customer.type` (string) Tipo do cliente. - individual (Pessoa física) - company (Pessoa jurídica) Enum: "individual", "company" - `data.sale_orders.customer.order_count` (integer) Quantidade de pedidos do cliente. Example: 10 - `data.sale_orders.customer.last_order_id` (integer) ID do último pedido do cliente. Example: 123 - `data.sale_orders.customer.birthday` (string) Data de nascimento do cliente Pessoa física. Formato "YYYY-MM-DD" Example: "1990-12-25" - `data.sale_orders.customer.companies` (array) Lista de empresas que permite visualizar. - `data.sale_orders.customer.companies.id` (integer) Identificador único da empresa Example: 1234 - `data.sale_orders.customer.companies.name` (string) Nome fantasia da empresa. Example: "CPlug" - `data.sale_orders.customer.companies.company_name` (string,null) Razão social da empresa. Example: "CPlug Tecnologia da Informação" - `data.sale_orders.customer.company_name` (string) Razão social da pessoa jurídica. Example: "MyCompany" - `data.sale_orders.customer.notes` (string) Observações do cliente. Example: "Minhas obervações do cliente" - `data.sale_orders.customer.documents` (array) Lista de documentos do cliente. - `data.sale_orders.customer.documents.type` (string, required) Indica o tipo do documento. - cpf: CPF Pessoa física - rg: RG Pessoa física - cnpj: CNPJ Pessoa jurídica - ie: Inscrição Estadual Pessoa jurídica - im: Inscrição Municipal Pessoa jurídica Enum: "cpf", "rg", "cnpj", "ie", "im" - `data.sale_orders.customer.documents.identify` (string, required) Identificação do documento. Example: "11144477735" - `data.sale_orders.customer.category` (object) Representa uma categoria de Cliente. - `data.sale_orders.customer.category.id` (integer) Identificador único da categoria de cliente. Example: 123 - `data.sale_orders.customer.category.name` (string) Nome da categoria. Example: "Ouro" - `data.sale_orders.customer.category.is_wholesale` (boolean) Indica que todos os clientes vinculados à essa categoria irão pagar o valor de atacado dos produtos. - `data.sale_orders.customer.category.discount_in_percent` (number) Desconto em percentual para a categoria. Todos os clientes vinculados à essa categoria receberão o desconto informado automáticamente. Example: 2.5 - `data.sale_orders.customer.category.deleted` (boolean) Indica se está apagado ou não. - `data.sale_orders.customer.category.created_at` (string) Data da última criação. Example: "2020-01-01T09:00:00-03:00" - `data.sale_orders.customer.category.updated_at` (string) Data da última atualização. Example: "2020-01-01T09:00:00-03:00" - `data.sale_orders.customer.created_at` (string) Data da criação do cliente. Example: "2020-01-01T09:00:00-03:00" - `data.sale_orders.customer.updated_at` (string) Data da atualização do cliente. Example: "2020-01-01T09:00:00-03:00" - `data.sale_orders.address` (object) Endereço da venda - `data.sale_orders.address.id` (number) id do endereço. Example: 220 - `data.sale_orders.address.nickname` (string) Apelido do endereço. Example: "Casa" - `data.sale_orders.address.type` (string, required) Tipo do endereço. - default endereço principal. - shipping endereço de entrega. - charge endereço de cobrança. - other outro tipo de endereço. Enum: "default", "shipping", "charge", "other" - `data.sale_orders.address.street` (string, required) Nome do logradouro (Rua, Avenida, praça, etc). Example: "Avenida Paulista" - `data.sale_orders.address.number` (string) Número do logradouro. Example: "42 A" - `data.sale_orders.address.city_id` (number) ID da cidade. Obrigatório quando o campo ibge_code não for passado. Example: 1234 - `data.sale_orders.address.ibge_code` (string) Código do município segundo IBGE. Exemplo: O código do município segundo IBGE é 3550308 Obrigatório quando o campo city_id não for passado. Example: "3550308" - `data.sale_orders.address.state` (string) Sigla do estado do endereço. Example: "SP" - `data.sale_orders.address.city` (string) Nome da cidade. Example: "São Paulo" - `data.sale_orders.address.neighborhood` (string) Nome do Bairro. Example: "Bela Vista" - `data.sale_orders.address.complement` (string) Complemento do endereço. Example: "Apto 2550" - `data.sale_orders.address.zip_code` (string) CEP do endereço. Example: "01311000" - `data.sale_orders.observation` (string) Obervação da venda Example: "Sem copo" - `data.sale_orders.status` (any) Status do pedido de venda. - canceled pedido de venda cancelada. - closed pedido de venda fechada. - in_preparation pedido em preparação. - in_route pedido em entrega. - open pedido de venda aberta. - reserved pedido de venda reservada. - takeout pedido para retirar. - waiting pedido de venda em espera. Enum: "canceled", "closed", "in_preparation", "in_route", "open", "reserved", "takeout", "waiting" - `data.sale_orders.items` (array) Lista de produtos deste pedido de venda. - `data.sale_orders.items.item_id` (integer) Id único do produto Example: 123 - `data.sale_orders.items.id` (integer) Id único do produto na relação Example: 123 - `data.sale_orders.items.grid_id` (integer) Id único do grid que este item faz parte. O grid_id é o ID do Product Grid. Example: 456 - `data.sale_orders.items.amount` (number) quantidade Example: 5 - `data.sale_orders.items.image` (string) imagem do produto Example: "mobile/totem/58723627fcebc230ab0d53ddf5f16e34/100/product_1_c1.jpeg" - `data.sale_orders.items.name` (string) Nome do produto Example: "Banana" - `data.sale_orders.items.unitary_value` (object) Valor unitário do item. É a soma do valor base deste item com a soma dos adicionais e com a soma do total dos atributos. Fórmula: unitary_value = valor base do item + sum(attributes.total_value) + sum(additionals.total_value) - `data.sale_orders.items.unitary_value.amount` (number, required) Valor expresso como um número decimal das principais unidades monetárias Example: 99.95 - `data.sale_orders.items.unitary_value.currency` (string, required) Código de moeda de 3 letras conforme definido pela ISO-4217 Example: "BRL" - `data.sale_orders.items.total_value` (object) Valor total do item. É a multiplicação da quantidade pelo valor unitário deste item. Fórmula: total_value = amount * unitary_value - `data.sale_orders.items.discount` (object) Desconto do produto - `data.sale_orders.items.stock_id` (integer) Id único do estoque Example: 1234 - `data.sale_orders.items.attributes` (array) Lista de atributos deste produto nesta venda. - `data.sale_orders.items.attributes.id` (integer) Id único do atributo do produto na relação Example: 123 - `data.sale_orders.items.attributes.attribute_id` (integer) Id único do atributo do produto Example: 123 - `data.sale_orders.items.attributes.min_choices` (integer) Quantidade mínima de opções que devem ser selecionadas Example: 1 - `data.sale_orders.items.attributes.max_choices` (integer) Quantidade máxima de opções que podem ser selecionadas Example: 2 - `data.sale_orders.items.attributes.name` (string) Nome do atributo Example: "Atributo" - `data.sale_orders.items.attributes.charge_from_quantity` (integer) Indica a partir de qual opção irá começar a cobrar. Ex: 3, indica se a partir da terceira opção que irá fazer parte do cálculo do total do atributo. Portanto, a primeira e a segunda opção será de graça, ou seja, essas duas opções deverão estar com o desconto igual ao valor total da opção. Example: 2 - `data.sale_orders.items.attributes.total_value` (object) Valor total deste atributo. É a soma dos valores das opções. Fórmula: total_value = sum((option.amount * option.unitary_value) - option.discount) - `data.sale_orders.items.attributes.price_calculation_type` (any) Tipo de cálculo no total do atributo. Ex: average, quer dizer a o valor total do atributo será a média dos valores das opções - Highest maior valor das opções - Average média dos valores das opções - Cumulative soma dos valores das opções Enum: "Highest", "Average", "Cumulative" - `data.sale_orders.items.attributes.options` (array) Lista de opções de um atributo. - `data.sale_orders.items.attributes.options.id` (integer) Id único da opção na relação Example: 123 - `data.sale_orders.items.attributes.options.option_id` (integer) Id único da opção Example: 123 - `data.sale_orders.items.attributes.options.code` (string) Código personalizado da opção Example: "code-123" - `data.sale_orders.items.attributes.options.name` (string) Nome da opção Example: "Opção 1" - `data.sale_orders.items.attributes.options.image` (string,null) URL da imagem da opção Example: "https://images.connectplug.com.br/4f01c1252eea.jpg" - `data.sale_orders.items.attributes.options.unitary_value` (object) Valor unitário da opção - `data.sale_orders.items.attributes.options.discount` (object) Desconto na opção - `data.sale_orders.items.attributes.options.notes` (string) Observação da opção Example: "Sem cebola" - `data.sale_orders.items.components` (array) Lista de componente que fazem parte deste combo, caso este item for um combo. - `data.sale_orders.items.components.combo_item_id` (integer) Id único do produto combo na relação, caso este item pertence a um combo Example: 3 - `data.sale_orders.items.components.additionals` (array) Lista de adicionais deste produto nesta venda. - `data.sale_orders.items.components.additionals.additional_id` (integer) ID do adicional Example: 123 - `data.sale_orders.items.components.additionals.amount` (integer) quantidade deste adicional Example: 1 - `data.sale_orders.items.components.additionals.unitary_value` (object) Valor unitário deste adicional - `data.sale_orders.items.components.additionals.total_value` (object) Valor total deste adicional - `data.sale_orders.items.components.additionals.image` (string) imagem do adicional Example: "mobile/totem/58723627fcebc230ab0d53ddf5f16e34/100/product_1_c1_add1.jpeg" - `data.sale_orders.items.components.additionals.name` (string) Nome do adicional Example: "Adicional do produto" - `data.sale_orders.items.price_list_product_id` (integer) Id único da lista de produto do produto. Você pode localizar os IDs da lista de preço do produto no _endpoint_ de [listagem de produtos de uma lista de preço](#tag/PriceLists/operation/get-price-list-products). Example: 456 - `data.sale_orders.items.combo_id` (integer) Id único do combo que este item faz parte. Você pode localizar os IDs dos combos no _endpoint_ de [listagem de produtos](#tag/Products/operation/get-products) com o filtro types=combo. Example: 456 - `data.sale_orders.payments` (array) Lista de pagamentos. - `data.sale_orders.payments.id` (integer) Id da único do método de pagamento na relação Example: 1 - `data.sale_orders.payments.payment_method` (object) Método de pagamento utilizado na venda - `data.sale_orders.payments.payment_method.id` (integer) Id único do método de pagamento Example: 123 - `data.sale_orders.payments.payment_method.name` (string) Nome do método de pagamento Example: "Cartão de crédito" - `data.sale_orders.payments.payment_method.allow_installment` (boolean) Indica se o método de pagamento permite parcelamento. Example: true - `data.sale_orders.payments.bank_account_id` (integer) Id da conta bancária Example: 1 - `data.sale_orders.payments.total_value` (object) valor total deste pagamento - `data.sale_orders.payments.exchange_value` (object) valor do troco, quando o tipo de pagamento for dinheiro - `data.sale_orders.payments.installments` (array) Lista de parcelas deste método de pagamento - `data.sale_orders.payments.installments.id` (integer) Id da único da parcela do método de pagamento na relação Example: 1 - `data.sale_orders.payments.installments.value` (object) valor desta parcela - `data.sale_orders.payments.installments.due_date` (string) Data de vencimento da parcela Example: "2020-01-01T09:00:00-03:00" - `data.sale_orders.payments.installments.observation` (string) observação desta parcela Example: "primeira parcela" - `data.sale_orders.payments.card_brand` (object) Bandeira do cartão de crédito - `data.sale_orders.payments.card_brand.id` (integer) Identificador único da bandeira. Example: 123 - `data.sale_orders.payments.card_brand.name` (string) Nome da bandeira. Example: "Master" - `data.sale_orders.payments.card_brand.icon` (string) ícone da bandeira. Example: "mastercard.png" - `data.sale_orders.payments.card_brand.nfe_code` (string) Código da NFe da bandeira. Example: "02" - `data.sale_orders.payments.card_contract_id` (integer) Id do contrato do cartão Example: 1 - `data.sale_orders.payments.card_receipt` (object) Dados do recibo do cartão - `data.sale_orders.payments.card_receipt.authorization` (string) Número da autorização do cartão. Normalmente é o número que aparece ao lado da palavra AUT, AUTORIZACAO, A Example: "999996" - `data.sale_orders.payments.card_receipt.nsu` (string) Número sequencial único. Normalmente é o número que aparece ao lado da palavra DOC, CV, NSU. Example: "009999997" - `data.sale_orders.payments.card_receipt.receipt` (string) Dados do recebio. Example: "SITEF\n00001\nBIN\nVIA - ESTABELECIMENTO\nCPLUG COMERCIO DE SOFTWARE LTDA\nAvenida da CPlug\nCuritibaTT000181\nEC:000000033999999 TERM:TFI038B9\n************9999\nAUT=999996 CV=009999997 DOC=999998\n18/03/20 17:27:57 C\nVISA\nCREDITO A VISTA\nVALOR 8.90\nTRANSACAO AUTORIZADA COM SENHA\n\n\nARQC: 35E8DF8A3234C308\nVISA CREDITO\nAID:A0000000031010\n(SiTef)" - `data.sale_orders.seller` (object) Dados do vendedor - `data.sale_orders.seller.id` (integer) Identificador único do vendedor. Example: 123 - `data.sale_orders.seller.name` (string) Nome do vendedor. Example: "Fulano de tal" - `data.sale_orders.seller.email` (string) E-mail do vendedor. Example: "vendedor@email.com" - `data.sale_orders.seller.username` (null,string) Nome de usuário do vendedor. Example: "Vendedor" - `data.sale_orders.seller.created_at` (string) Data da criação da vendedor. Example: "2020-01-01T09:00:00-03:00" - `data.sale_orders.seller.updated_at` (string) Data da atualização da vendedor. Example: "2020-01-01T09:00:00-03:00" - `data.sale_orders.seller.deleted_at` (string) Data que foi apagado o vendedor. Example: "2020-01-01T09:00:00-03:00" - `data.sale_orders.carrier` (object) Dados do frete e do transportador - `data.sale_orders.carrier.shipping_fee` (object) valor do frete - `data.sale_orders.carrier.carrier_id` (integer) Id do transportador Example: 1 - `data.sale_orders.total` (object) Resumo monetário da venda - `data.sale_orders.total.value` (object) Valor total da venda já considerando o desconto e o frete e o valor de outras despesas - `data.sale_orders.total.discount` (object) Valor de desconto na venda. Deixar em nulo quando um desconto no item for aplicado - `data.sale_orders.total.total_value_ipi` (object) Valor total de IPI - `data.sale_orders.total.other_expenses_value` (object) Valor total de outras despesas - `data.sale_orders.source_type` (string) Canal de venda: - erp - pdv - store - totem Enum: "erp", "pdv", "store", "totem" - `data.sale_orders.registration_date` (string) Data do registro da venda. Example: "2020-01-01T09:00:00-03:00" - `data.sale_orders.delivery_type` (any) Tipo de entrega do pedido: - delivery entrega - withdrawal retirada Enum: "delivery", "withdrawal" - `data.sale_orders.sale_id` (integer) Identificador numérico único de venda. Example: 789 - `data.sale_orders.delivery_area` (object) Representa uma área de entrega. - `data.sale_orders.delivery_area.id` (integer) Identificador único da área de entrega. Example: 1 - `data.sale_orders.delivery_area.name` (string) Nome da área de entrega. Example: "Centro" - `data.sale_orders.delivery_area.type` (string) Tipo da área de entrega. - circle: Área de entrega circular (radio de entrega). - polygon: Área de entrega customizada. Enum: "circle", "polygon" - `data.sale_orders.delivery_area.center_point` (object) Localização do centro da área de entrega. Esse compo é obrigatório para áreas de entrega com tipo circle. Esse compo não será considerado para áreas de entrega com tipo polygon. - `data.sale_orders.delivery_area.center_point.lat` (number, required) Latitude de um ponto geográfico. Example: -23.5505199 - `data.sale_orders.delivery_area.center_point.lng` (number, required) Longitude de um ponto geográfico. Example: -46.6333093 - `data.sale_orders.delivery_area.radius` (integer) Raio da área de entrega em quilômetros (km). Esse compo é obrigatório para áreas de entrega com tipo circle. Esse compo não será considerado para áreas de entrega com tipo polygon. Example: 10 - `data.sale_orders.delivery_area.polygon` (array) Polígono da área de entrega. Esse compo é obrigatório para áreas de entrega com tipo polygon. Esse compo não será considerado para áreas de entrega com tipo circle. - `data.sale_orders.delivery_area.price` (object) Valor da taxa de entrega. - `data.sale_orders.delivery_area.min_waiting_time` (integer) Tempo em minutos estimado mínimo de espera para a entrega. Example: 30 - `data.sale_orders.delivery_area.max_waiting_time` (integer) Tempo em minutos estimado máximo de espera para a entrega. Example: 60 - `data.sale_orders.created_at` (string) Data da criação da venda. Example: "2020-01-01T09:00:00-03:00" - `data.sale_orders.updated_at` (string) Data da atualização da venda. Example: "2020-01-01T09:00:00-03:00" - `meta` (object) Representa as informações de Metadado da paginação da listagem. - `meta.current_page` (integer, required) Página atual na paginação. Example: 1 - `meta.last_page` (integer, required) Quantidade total de páginas. Example: 10 - `meta.per_page` (integer, required) Quantidade de resultados por página. Example: 20 - `meta.total` (integer, required) Quantidade total de itens. Example: 200 ## Response 400 fields (application/json): - `code` (string, required) Código de erro. Example: "missing_headers" - `message` (string) Descrição do erro. Example: "error message" - `meta` (array) Dados adicionais sobre o erro. ## Response 422 fields (application/json): - `code` (string, required) Código de erro. Example: "uneditable_entity" - `message` (string) Descrição do erro. Example: "description error" - `meta` (array) Dados adicionais sobre o erro. - `meta.field` (string, required) Nome do campo no qual existe um erro de validação. Example: "name" - `meta.validations` (array) - `meta.validations.type` (string, required) Tipo da validação aplicada. Example: "Required" - `meta.validations.value` (array) Tipo de valor aplicável (esse campo pode ser vazio). ## Response 401 fields ## Response 404 fields