Pedidos

GET /orders

Os pedidos da loja

Escopo read_orders

Na ordem da última mudança, da mais antiga à mais nova, com o id para desempatar: para sincronizar, guarde o updated_at do último que leu e peça updated_at_min na próxima vez. Toda mudança do pedido conta: a situação, o pagamento confirmado, o rastreio, a nota fiscal e a anonimização. Cada pedido traz os dados de quem comprou.

Parâmetros

Resposta

200 Sucesso. (OrderList)

Erros

• 400 A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).
• 401 O token falta, não existe, foi revogado ou venceu (authentication_error).
• 403 O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).
• 429 Chamadas demais: espere o Retry-After (rate_limited).
• 500 Erro do nosso lado (api_error).
• 503 A API está ocupada com outras chamadas: espere o Retry-After (api_error).

GET /orders/count

Quantos pedidos casam com os filtros

Escopo read_orders

Os mesmos filtros da lista.

Parâmetros

Resposta

200 Sucesso. (Count)

Erros

• 400 A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).
• 401 O token falta, não existe, foi revogado ou venceu (authentication_error).
• 403 O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).
• 429 Chamadas demais: espere o Retry-After (rate_limited).
• 500 Erro do nosso lado (api_error).
• 503 A API está ocupada com outras chamadas: espere o Retry-After (api_error).

GET /orders/{id}

Um pedido

Escopo read_orders

O pedido, com os itens, os valores, o frete, a última cobrança, a nota fiscal e os dados de quem comprou.

Parâmetros

Resposta

200 Sucesso. (Order)

Erros

• 401 O token falta, não existe, foi revogado ou venceu (authentication_error).
• 403 O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).
• 404 O recurso não existe nesta loja (not_found).
• 429 Chamadas demais: espere o Retry-After (rate_limited).
• 500 Erro do nosso lado (api_error).
• 503 A API está ocupada com outras chamadas: espere o Retry-After (api_error).

POST /orders/{id}/mark_paid

Marca o pedido como pago

Escopo write_orders

Para o pagamento recebido fora da plataforma (depósito, dinheiro na retirada). Só o pedido que aguarda pagamento; quem comprou recebe o e-mail de pagamento confirmado. O pagamento feito pelo checkout já chega pago, pelo gateway.

Parâmetros

Resposta

200 Sucesso. (Order)

Erros

• 401 O token falta, não existe, foi revogado ou venceu (authentication_error).
• 403 O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).
• 404 O recurso não existe nesta loja (not_found).
• 409 O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).
• 429 Chamadas demais: espere o Retry-After (rate_limited).
• 500 Erro do nosso lado (api_error).
• 503 A API está ocupada com outras chamadas: espere o Retry-After (api_error).

POST /orders/{id}/prepare

Começa a separar o pedido

Escopo write_orders

Só o pedido pago.

Parâmetros

Resposta

200 Sucesso. (Order)

Erros

• 401 O token falta, não existe, foi revogado ou venceu (authentication_error).
• 403 O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).
• 404 O recurso não existe nesta loja (not_found).
• 409 O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).
• 429 Chamadas demais: espere o Retry-After (rate_limited).
• 500 Erro do nosso lado (api_error).
• 503 A API está ocupada com outras chamadas: espere o Retry-After (api_error).

POST /orders/{id}/ship

Marca o pedido como enviado

Escopo write_orders

Só o pedido em separação, com o código de rastreio opcional. Quem comprou recebe o e-mail de pedido enviado, com o rastreio. Na retirada na loja, enviado é o pedido pronto para retirar.

Parâmetros

Resposta

200 Sucesso. (Order)

Erros

• 400 A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).
• 401 O token falta, não existe, foi revogado ou venceu (authentication_error).
• 403 O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).
• 404 O recurso não existe nesta loja (not_found).
• 409 O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).
• 429 Chamadas demais: espere o Retry-After (rate_limited).
• 500 Erro do nosso lado (api_error).
• 503 A API está ocupada com outras chamadas: espere o Retry-After (api_error).

POST /orders/{id}/deliver

Marca o pedido como entregue

Escopo write_orders

Só o pedido enviado. Na retirada na loja, entregue é o pedido retirado.

Parâmetros

Resposta

200 Sucesso. (Order)

Erros

• 401 O token falta, não existe, foi revogado ou venceu (authentication_error).
• 403 O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).
• 404 O recurso não existe nesta loja (not_found).
• 409 O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).
• 429 Chamadas demais: espere o Retry-After (rate_limited).
• 500 Erro do nosso lado (api_error).
• 503 A API está ocupada com outras chamadas: espere o Retry-After (api_error).

POST /orders/{id}/cancel

Cancela o pedido

Escopo write_orders

Os itens voltam ao estoque, e a cobrança em aberto deixa de valer. O pedido já pago tem o dinheiro devolvido a quem comprou, pelo gateway que cobrou: cancelá-lo pede também o escopo refund_orders (sem ele, 403). Se o gateway recusar o estorno, nada muda. O pedido enviado ou entregue não se cancela (409).

Parâmetros

Resposta

200 Sucesso. (Order)

Erros

• 401 O token falta, não existe, foi revogado ou venceu (authentication_error).
• 403 O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).
• 404 O recurso não existe nesta loja (not_found).
• 409 O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).
• 429 Chamadas demais: espere o Retry-After (rate_limited).
• 500 Erro do nosso lado (api_error).
• 503 A API está ocupada com outras chamadas: espere o Retry-After (api_error).

PUT /orders/{id}/invoice

Informa a nota fiscal do pedido

Escopo write_orders

A nota emitida pelo ERP (a plataforma não emite nota): a chave de acesso, e o número, a série e o link, opcionais. O número e a série estão dentro da chave; sem eles, saem dela. Informar de novo troca a nota anterior. A nota aparece no pedido no painel, e a compra da etiqueta do Melhor Envio usa a chave.

Parâmetros

Resposta

200 Sucesso. (Order)

Erros

• 400 A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).
• 401 O token falta, não existe, foi revogado ou venceu (authentication_error).
• 403 O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).
• 404 O recurso não existe nesta loja (not_found).
• 429 Chamadas demais: espere o Retry-After (rate_limited).
• 500 Erro do nosso lado (api_error).
• 503 A API está ocupada com outras chamadas: espere o Retry-After (api_error).

PUT /orders/{id}/line_items/{line_id}/prescription

Informa a receita de um item

Escopo write_orders

A receita oftalmológica recebida por outro canal (o balcão, o ERP da ótica, o telefone), com os nomes em inglês e os rótulos do padrão dos laboratórios (DCS) nas descrições. Conferida pelas mesmas regras do checkout (faixas, passos de 0.25, eixo com o cilíndrico, adição na progressive e na bifocal): o erro diz o campo. Troca a receita que havia; a conferida volta a provided. Só o item que pede receita (prescription não é null); sem isso, 409. A receita que estava pendente gera o evento order.prescription_received. A resposta é o pedido com os valores da receita, como no GET.

Parâmetros

Resposta

200 Sucesso. (Order)

Erros

• 400 A chamada veio com campos inválidos; os campos recusados vão em fields (invalid_request).
• 401 O token falta, não existe, foi revogado ou venceu (authentication_error).
• 403 O token não tem o escopo da rota, ou, com write_content, mandou campos que pedem write_products, listados em fields (permission_error).
• 404 O recurso não existe nesta loja (not_found).
• 409 O estado do recurso não permite a mudança, ou ele mudou desde a leitura (conflict).
• 429 Chamadas demais: espere o Retry-After (rate_limited).
• 500 Erro do nosso lado (api_error).
• 503 A API está ocupada com outras chamadas: espere o Retry-After (api_error).

POST /orders/{id}/line_items/{line_id}/prescription/check

Marca a receita de um item como conferida

Escopo write_orders

A ótica conferiu a receita (a foto contra os valores, a validade, o médico). Só a receita informada (status provided); a pendente dá 409. Gera order.updated. A resposta é o pedido com os valores da receita, como no GET.

Parâmetros

Resposta

200 Sucesso. (Order)