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
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 |

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
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 |

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>

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
document_on_receipt	String	indica qual o CPF do cliente que deve estar na nota fical
gift_message	String	Mensagem para 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,
      "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": "emerson.mendes@newtail.com.br",
        "main_phone": "6792180865",
        "application_source": "newtail_purchase_form",
        "channel_source": "online"
      },
      "items": [
        {
          "id": "e3d1c910-a862-11eb-bd46-01238ff209f9",
          "order_id": "e3cd8350-a862-11eb-b1a4-d7c34cb5fa05",
          "name": "Pedido Total",
          "detail": null,
          "gift_wrap": null,
          "original_price": 0,
          "special_price": 0,
          "cost_price": 0,
          "shipping_cost": 0,
          "quantity": 0,
          "product_id": "wpp-001",
          "product_id_substitute": null,
          "image_url": null,
          "status": null,
          "createdAt": "2021-04-28T20:47:04.000Z",
          "updatedAt": "2021-04-28T20:47:04.000Z",
          "deletedAt": 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",
      }
    }
  ]
}

Observação quando ocorrer itens com substituição

Quando ocorrer substituição, deve ser utilizado o campo product_id_substitute em detrimento ao product_id para as ofertas.

Status do Item

deleted: esse item foi removido durante a separação e não deve ser incluído no Cupom Fiscal
confirmed: esse item foi separado com sucesso e deve ser incluído no Cupom Fiscal e deve utilizar o campo product_id para identificar a oferta
substitution: esse item foi substituído por outro item e deve ser incluído no Cupom Fiscal e deve utilizar o campo product_id_substitute para identificar a oferta

Exemplos de Pedidos:

shipping_from_store.json

Atualização do pedido do pedido

Para atualizar o status de um pedido pela API é bastante simples, bastando fazer uma Requisição HTTP com o status desejado.

PUT <https://api.newtail.com.br/webhook/orders/:account_id/:id> ou :order_id

account_id: é o identificador único da conta
id: é o identificador único do pedido (que é recebido no campo id) - newtail
order_id: é um identificador sequencial gerado durante a criação do pedido na newtail

Parâmetros

Os próximos campos são utilizados quando a separação é feita em sistema externo a Newtail.

Exemplo de nota fiscal emitida.

<aside> ⚠️ Captura do Pagamento O pagamento não será capturado até que o status do pedido chegue ao status de nota fiscal emitida (invoice_issued).

</aside>

{
    "status": "invoice_issued", // indica o status atual do pedido
    "integration_id": "100000001" // indica o id interno,
  "invoice_id": "1234" // chave da nota 44 caracteres - Opcional
}

Exemplo de finalização de separação

{
    "status": "finished_picking",
    "integration_id": "100000001",
  "shipping_cost": 1.0, // opcional - enviar somente se necessário
  "sub_total": 999.99, // opcional - enviar somente se necessário
  "items": [
    {
      "product_id": "1", // sku do produto
      "product_id_substitute": "2", // sku do novo produto
      "price": 23.50, // preço por unidade/kg
      "quantity": 1.3, // quantidade separada
      "discount": 1.5, // valor do desconto
      "sub_total": 30.55 // opcional - price * discount
    },
    {
      "product_id": "3", // sku do produto
      "price": 23.50, // preço por unidade/kg
      "quantity": 1.3, 
      "discount": 1.5,
    },
  ]
}

Retorno

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.

Exemplo de Requisição

curl --location --request PUT '<https://api.newtail.com.br/webhook/orders/XXXXXX-XXXX-XXXX-XXXX-1918d5f0ff29/XXXXXX-XXXX-XXXX-XXXX-1769d727c329>' \\
--header 'x-app-id: xxx' \\
--header 'x-api-key: yyy' \\
--header 'Content-Type: application/json' \\
--data-raw '{
    "status": "order_delivered"
}'

Status

Status dos Pedidos

Indica os status que o pedido pode passar por toda a sua vida útil.

Status de Atualização

Indica os possíveis status que o Supermercado por enviar após a conclusão da separação. São esses status que indicam se a entrega deve seguir como está no seu status final

Status do Pagamento

Indica os status do pagamento

Método de Pagamento

Indica as formas de pagamento que o cliente poderá optar

Tipo do Método de Pagamento

Indica qual o tipo de pagamento que o cliente escolheu.

Status do Item

Indica os status que os produtos podem ter após a separação.