Documentação API de Pedidos

Endpoint

Para utilização da API de consulta de pedidos será necessário fazer uma requisição GET para a seguinte url:

GET <https://api.newtail.com.br/api/order/integration>

Autenticação

Seja mais sobre a autenticação em Documentação API Autenticação

Filtros

Todos os filtros devem ser enviados como Query String.

Filtro	Tipo	Formato	Descrição
order_id	String		Numero do pedido externo
start_date	Date	YYYY-MM-DD
end_date	Date	YYYY-MM-DD
channel_id	String	- whatsapp

magento_ecommerce
lojafisica
MercadoLivre
whatsapp_bot
purchase
rappi
vtex | Canal do gerador de demanda (atendimento) | | store_id | String | | Indica o identificador remoto da loja | | name | String | | Nome do cliente final | | social_id | String | somente números | Indica o CPF ou CNPJ do cliente final | | main_phone | String | somente números | Indica o telefone do cliente final | | status | String | - order_placed
confirmed_order
waiting_picking
pre_picking
in_picking
finished_picking
waiting_invoice
invoice_issued
waiting_delivery
waiting_payment
delivery_accepted
in_delivery
finished
order_cancelled (depreciado)
order_canceled
order_delivered | Indica o status do pedido | | payment_status | String | - waiting_payment
payment_authorized
payment_approved
payment_refused
payment_refunded | Indica o status de pagamento atual | | payment_method | String | - online
in_person | Indica a forma de pagamento | | schedule_date | String | YYYY-MM-DD | Indica a data agendada de entrega (Depreciado) | | schedule_time | String | HH:MM - HH:MM | Indica a hora agendada de entrega (Depreciado) | | delivery_type | String | - shipping_from_store
pick_up_in_store | Indica o tipo de entrega | | page | Inteiro | | Indica a página atual

default=false |

ATENÇÃO:

<aside> 💡 Para filtrar somente os pedidos que precisam ser integrados com o seu sistema de PDV, deve-se filtrar os pedidos com status=finished_picking. Isso faz com que somente os pedidos aguardando nota fiscal, que já foram finalizados a separação, sejam retornados na consulta.

</aside>

<aside> ⚠️ O limite de dados retornados para um pooling é de 10 mil itens na paginação. Sempre que possível, faça o filtro por um período e pela loja, para facilitar a recuperação de todos os dados.

</aside>

Atributos

Atributo	Tipo	Descrição
total	Integer	Indica a quantidade total de pedidos presentes no filtro atual
orders	List<Pedido>	Lista de Pedidos

Atributos do Pedido

Atributo	Tipo	Descrição
id	String	Identificador único interno no pedido
account_id	String	Identificador único interno do Supermercado
location_id	String	Identificador único interno da loja em que o pedido foi feito
operator_id	String	Identificador único interno do operador que fez a separação do pedido
channel_id	String	indica qual em qual o canal o pedido foi feito
customer_id	String	Identificador único interno do Cliente Final
shipping_cost	Float	Valor cobrado para a entrega no pedido
total_discount	Float	Valor total de desconto no pedido
total_price	Float	Valor total do pedido (incluindo total_discount, shipping_cost e sub_total)
description	String	É o corpo da mensagem do pedido feito pelo cliente no Whatsapp
loyalty_program	Boolean	Indica se o cliente deseja participar do programa de fidelidade
is_recurrent	Boolean	Indica se o pedido é recorrente, ou seja, se o cliente deseja que o pedido seja entregue periodicamente.
document_on_receipt	String	indica qual o CPF do cliente que deve estar na nota fical
gift_message	String	Mensagem para presente
items	Array<Object>	Lista de todos os itens
items.#.id	String	Identificador único do item na Newtail
items.#.order_id	String	Identificador único do pedido na Newtail
items.#.original_name	String	Nome do item inicial antes da separação.
O original_name pode ser o mesmo que o name quando o mesmo item comprado for o mesmo separado.
items.#.name	String	Nome do Item separado.
ex.: Água Mineral Com Gás Select 510ml
items.#.detail	String	Observação sobre a separação do item
items.#.status	String	Indica o status de separação do item. Para ver os possíveis status veja Status do Item nesta mesma página
items.#.unit_measurement	String	Indica a unidade de medida do Item.

kg: itens vendidos por Kilo
un: itens vendidos por unidade | | items.#.quantity | Float | Quantidade de itens separados | | items.#.original_price | Float | Valor do unitário do item no momento da compra | | items.#.special_price | Float | Valor do item “por” | | items.#.original_unit_price | Float | Valor do unitário do item no momento da compra | | items.#.discount | Float | Valor total de desconto | | items.#.total_value | Float | Valor total do item após a separação (já possui o valor do desconto) | | items.#.original_quantity | Float | Quantidade de itens no momento da compra | | items.#.original_total_value | Float | Valor total do item no momento da compra (já possui o valor do desconto) | | items.#.original_discount | Float | Valor do desconto no momento da compra | | items.#.product_id | String | Sku do produto | | items.#.product_id_substitute | String | Sku do produto que substituiu o produto inicial.

Esse SKU deve ser usado prioritariamente ao product_id quando estiver presente |

O retorno da requisição terá código HTTP 204 para caso que obtiveram sucesso na atualização. Em caso de erro será enviado um HTTP 5XX, com o possível problema.

Abaixo exemplo de requisição bem sucedida:

{
  "total": 1,
  "orders": [
    {
      "id": "e3cd8350-a862-11eb-b1a4-d7c34cb5fa05",
      "account_id": "7a28e5a0-65a2-11eb-b70f-07f0e148ce7f",
      "location_id": "a65db040-7de6-11eb-ab55-4d2b573fc158",
      "operator_id": null,
      "channel_id": "whatsapp",
      "order_id": "68",
      "customer_id": "fae52600-72e9-11eb-b2ab-9778161ba500",
      "salesperson": null,
      "tax_included": null,
      "shipping_cost": null,
      "total_discount": null,
      "total_tax": null,
      "total_price": 0,
      "description": "100g de batata inglesa\\n2 bandejas de iogurte\\n1 saco de pão fatiado",
      "loyalty_program": false,
      "document_on_receipt": false,
      "gift_message": null,
      "currency": "BRL",
      "closed_at": null,
      "cancelled_at": null,
      "start_picking_at": null,
      "end_picking_at": null,
      "allow_item_substitution": false,
      "include_bag": false,
      "createdAt": "2021-04-28T20:47:04.000Z",
      "updatedAt": "2021-04-28T20:47:04.000Z",
      "deletedAt": null,
      "createdAt_timestamp": 1619913600,
      "store_id": null,
      "is_recurrent": true,
      "webhook_url": "<https://api.newtail.com.br/webhook/orders/7a28e5a0-65a2-11eb-b70f-07f0e148ce7f/e3cd8350-a862-11eb-b1a4-d7c34cb5fa05>",
      "customer": {
        "id": "fae52600-72e9-11eb-b2ab-9778161ba500",
        "name": "Emerson Mendes",
        "social_id": "05207623125",
        "type": "individual",
        "account_id": "7a28e5a0-65a2-11eb-b70f-07f0e148ce7f",
        "main_email": "[email protected]",
        "main_phone": "6792180865",
        "application_source": "newtail_purchase_form",
        "channel_source": "online"
      },
      "items": [
        {
            "id": "bfe27da0-b95e-11ee-a10a-1560324aab07",
            "order_id": "e3cd8350-a862-11eb-b1a4-d7c34cb5fa05",
            "original_name": "Leite Em Pó Ninho Integral 750g",
            "name": "Leite Em Pó Ninho Integral 750g",
            "detail": null,
            "status": "confirmed",
            "unit_measurement": "un",
            "quantity": 1.5,
            "original_price": 0.0,
            "special_price": 0.0,
            "original_unit_price": 0.0,
            "discount": 0.0,
            "total_value": 0.0,
            "original_quantity": 1.0,
            "original_discount": 0.0,
            "original_total_value": 0.0,
            "product_id": "806811",
            "product_id_substitute": null
        }
      ],
      "payments": {
        "id": "e3d1f020-a862-11eb-9acb-7d6185a92fc9",
        "order_id": "e3cd8350-a862-11eb-b1a4-d7c34cb5fa05",
        "value": 0,
        "transaction_date": "2021-04-28",
        "status": "waiting_payment",
        "parcels": null,  
        "method": "online",
        "description": null,
        "card_issuer": null,
        "autorization_id": null,
        "payment_id": null,
        "nsu": null,
        "card_number": null,
        "createdAt": "2021-04-28T20:47:04.000Z",
        "updatedAt": "2021-04-28T20:47:04.000Z",
        "deletedAt": null
      },
      "status": {
        "id": "e3d1a200-a862-11eb-9be2-d3bf56c21ed1",
        "order_id": "e3cd8350-a862-11eb-b1a4-d7c34cb5fa05",
        "type": "waiting_picking",
        "label": "Aguardando Separação",
        "code": "Aguardando Separação",
        "createdAt": "2021-04-28T20:47:04.000Z",
        "updatedAt": "2021-04-28T20:47:04.000Z",
        "deletedAt": null
      },
      "shipments": {
        "schedule_date": "2021-05-01",
        "slot": "09:00 - 13:00",
        "type": "pick_up_in_store",
				"items": "container1,container2,...,containerN",
      }
    }
  ]
}