Status

A API de status gerencia os status de pedido da sua loja: consultar, criar, atualizar e excluir status personalizados.

A API de status permite gerenciar os status de pedido da sua loja. Um status de pedido é uma etapa do ciclo de vida do pedido (por exemplo Aberto ou Concluído), identificada por uma única letra, com uma descrição e os textos do e-mail enviado quando um pedido recebe aquele status. Você pode consultar, criar, atualizar e excluir status de pedido personalizados, para acompanhar o fluxo de trabalho do seu negócio.

Todas as chamadas usam as credenciais HTTP Basic de um administrador ($EMAIL:$API_KEY) e o endereço da sua loja ($BASE_URL).

Como funciona

Os status padrão cobrem a vida normal de um pedido. Você cria status extras com letras que os padrões não usam, e depois os pedidos podem ser movidos para eles.

Aberto→Processado→Concluído

Status de pedido padrão

Código	Descrição
`O`	Aberto, Open (status inicial quando um pedido é criado)
`P`	Processado, Processed (o pedido foi processado)
`C`	Concluído, Complete (o pedido foi concluído)
`F`	Falhou, Failed (o processamento do pedido falhou)
`D`	Recusado, Declined (o pedido foi recusado)
`B`	Em espera por estoque, Backordered (itens do pedido estão em espera por estoque)
`I`	Cancelado, Cancelled (o pedido foi cancelado)

Conceitos principais

Listar status

O GET /api/statuses/ retorna uma lista de todos os status de pedido da sua loja. O endpoint aceita paginação.

Parâmetro	Tipo	Obrigatório	Descrição
`page`	integer	Não	Número da página (padrão: 1)
`items_per_page`	integer	Não	Quantidade de itens por página (padrão: 10)
`type`	string	Não	Filtra pelo tipo de status (por exemplo, "O" para status de pedido)

A resposta de exemplo:

json

{
  "statuses": [
    {
      "status_id": "1",
      "status": "O",
      "description": "Open",
      "email_subj": "Your order has been placed",
      "email_header": "Thank you for your order!",
      "type": "O",
      "is_default": "Y"
    },
    {
      "status_id": "2",
      "status": "P",
      "description": "Processed",
      "email_subj": "Your order has been processed",
      "email_header": "We're processing your order",
      "type": "O",
      "is_default": "N"
    },
    {
      "status_id": "3",
      "status": "C",
      "description": "Complete",
      "email_subj": "Your order has been completed",
      "email_header": "Your order is complete",
      "type": "O",
      "is_default": "N"
    }
  ],
  "params": {
    "page": 1,
    "items_per_page": 10,
    "total_items": 3
  }
}

Consultar um status

O GET /api/statuses/{status_id}/ retorna os detalhes de um status específico, pelo id. A resposta acrescenta o corpo do e-mail e os textos em cada idioma (params_by_lang).

json

{
  "status_id": "1",
  "status": "O",
  "description": "Open",
  "email_subj": "Your order has been placed",
  "email_header": "Thank you for your order!",
  "email_body": "Dear [customer],\n\nThank you for placing an order in our store. We will notify you when your order ships.",
  "type": "O",
  "is_default": "Y",
  "params_by_lang": {
    "en": {
      "description": "Open",
      "email_subj": "Your order has been placed",
      "email_header": "Thank you for your order!",
      "email_body": "Dear [customer],\n\nThank you for placing an order in our store. We will notify you when your order ships."
    },
    "es": {
      "description": "Abierto",
      "email_subj": "Su pedido ha sido realizado",
      "email_header": "¡Gracias por su pedido!",
      "email_body": "Estimado [customer],\n\nGracias por realizar un pedido en nuestra tienda. Le notificaremos cuando su pedido sea enviado."
    }
  }
}

Criar um status

O POST /api/statuses/ cria um status de pedido personalizado novo. O corpo da requisição tem estes parâmetros.

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	Sim	Código do status (uma letra)
`description`	string	Sim	Descrição do status
`email_subj`	string	Não	Assunto do e-mail
`email_header`	string	Não	Texto do cabeçalho do e-mail
`email_body`	string	Não	Texto do corpo do e-mail
`type`	string	Sim	Tipo do status (por exemplo, "O" para pedido)
`is_default`	string	Não	"Y" ou "N" (padrão: "N")
`params_by_lang`	object	Não	Parâmetros do status por idioma

Um exemplo de requisição:

json

{
  "status": "S",
  "description": "Shipped",
  "email_subj": "Your order has been shipped",
  "email_header": "Your order is on its way!",
  "email_body": "Dear [customer],\n\nYour order has been shipped and is on its way to you. You can track your shipment using the tracking number below.",
  "type": "O",
  "is_default": "N",
  "params_by_lang": {
    "en": {
      "description": "Shipped",
      "email_subj": "Your order has been shipped",
      "email_header": "Your order is on its way!",
      "email_body": "Dear [customer],\n\nYour order has been shipped and is on its way to you. You can track your shipment using the tracking number below."
    },
    "es": {
      "description": "Enviado",
      "email_subj": "Su pedido ha sido enviado",
      "email_header": "¡Su pedido está en camino!",
      "email_body": "Estimado [customer],\n\nSu pedido ha sido enviado y está en camino. Puede realizar el seguimiento de su envío utilizando el número de seguimiento a continuación."
    }
  }
}

Atualizar e excluir um status

O PUT /api/statuses/{status_id}/ atualiza um status de pedido existente. Um exemplo de requisição:

json

{
  "description": "Order Completed",
  "email_header": "Your order is now complete!",
  "email_body": "Dear [customer],\n\nThank you for shopping with us. Your order has been completed and we hope you're satisfied with your purchase."
}

Ao atualizar um status, você só precisa incluir os campos que quer mudar. Os demais campos mantêm os valores atuais.

O DELETE /api/statuses/{status_id}/ exclui um status de pedido personalizado.

Endpoints

Método	Caminho	Finalidade	Autenticação
GET	`/api/statuses`	Listar os status de pedido, veja Paginação	Administrador
POST	`/api/statuses`	Criar um status de pedido personalizado, veja Endpoints	Administrador
GET	`/api/statuses/{status_id}`	Consultar um status específico, veja Endpoints	Administrador
PUT	`/api/statuses/{status_id}`	Atualizar um status, veja Endpoints	Administrador
DELETE	`/api/statuses/{status_id}`	Excluir um status personalizado, veja Endpoints	Administrador

Erros comuns

Reutilizar a letra de um status padrão num status personalizado. Escolha uma letra que os padrões não usem.
Tentar excluir um status padrão, ou um status que ainda é usado por pedidos. Mova os pedidos para outro status antes.
Enviar o status inteiro num PUT. Só os campos que você quer mudar são necessários.
Esquecer que status, description e type são obrigatórios ao criar um status.
Escrever as variáveis de e-mail em outro formato. As variáveis vão entre colchetes, como [customer].

Próximos passos

Endpoints

Todas as URLs da API de status, com exemplos.

Paginação

Escolha a página e o tamanho da página da listagem.

Campos

A referência dos campos de status.

Pedidos (REST)

Mova pedidos de um status para outro.

API legada/Referência completa

Status

A API de status gerencia os status de pedido da sua loja: consultar, criar, atualizar e excluir status personalizados.

Todas as chamadas usam as credenciais HTTP Basic de um administrador ($EMAIL:$API_KEY) e o endereço da sua loja ($BASE_URL).

Como funciona

Os status padrão cobrem a vida normal de um pedido. Você cria status extras com letras que os padrões não usam, e depois os pedidos podem ser movidos para eles.

Aberto→Processado→Concluído

Status de pedido padrão

Código	Descrição
`O`	Aberto, Open (status inicial quando um pedido é criado)
`P`	Processado, Processed (o pedido foi processado)
`C`	Concluído, Complete (o pedido foi concluído)
`F`	Falhou, Failed (o processamento do pedido falhou)
`D`	Recusado, Declined (o pedido foi recusado)
`B`	Em espera por estoque, Backordered (itens do pedido estão em espera por estoque)
`I`	Cancelado, Cancelled (o pedido foi cancelado)

Conceitos principais

Listar status

O GET /api/statuses/ retorna uma lista de todos os status de pedido da sua loja. O endpoint aceita paginação.

Parâmetro	Tipo	Obrigatório	Descrição
`page`	integer	Não	Número da página (padrão: 1)
`items_per_page`	integer	Não	Quantidade de itens por página (padrão: 10)
`type`	string	Não	Filtra pelo tipo de status (por exemplo, "O" para status de pedido)

A resposta de exemplo:

json

{
  "statuses": [
    {
      "status_id": "1",
      "status": "O",
      "description": "Open",
      "email_subj": "Your order has been placed",
      "email_header": "Thank you for your order!",
      "type": "O",
      "is_default": "Y"
    },
    {
      "status_id": "2",
      "status": "P",
      "description": "Processed",
      "email_subj": "Your order has been processed",
      "email_header": "We're processing your order",
      "type": "O",
      "is_default": "N"
    },
    {
      "status_id": "3",
      "status": "C",
      "description": "Complete",
      "email_subj": "Your order has been completed",
      "email_header": "Your order is complete",
      "type": "O",
      "is_default": "N"
    }
  ],
  "params": {
    "page": 1,
    "items_per_page": 10,
    "total_items": 3
  }
}

Consultar um status

O GET /api/statuses/{status_id}/ retorna os detalhes de um status específico, pelo id. A resposta acrescenta o corpo do e-mail e os textos em cada idioma (params_by_lang).

json

{
  "status_id": "1",
  "status": "O",
  "description": "Open",
  "email_subj": "Your order has been placed",
  "email_header": "Thank you for your order!",
  "email_body": "Dear [customer],\n\nThank you for placing an order in our store. We will notify you when your order ships.",
  "type": "O",
  "is_default": "Y",
  "params_by_lang": {
    "en": {
      "description": "Open",
      "email_subj": "Your order has been placed",
      "email_header": "Thank you for your order!",
      "email_body": "Dear [customer],\n\nThank you for placing an order in our store. We will notify you when your order ships."
    },
    "es": {
      "description": "Abierto",
      "email_subj": "Su pedido ha sido realizado",
      "email_header": "¡Gracias por su pedido!",
      "email_body": "Estimado [customer],\n\nGracias por realizar un pedido en nuestra tienda. Le notificaremos cuando su pedido sea enviado."
    }
  }
}

Criar um status

O POST /api/statuses/ cria um status de pedido personalizado novo. O corpo da requisição tem estes parâmetros.

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	Sim	Código do status (uma letra)
`description`	string	Sim	Descrição do status
`email_subj`	string	Não	Assunto do e-mail
`email_header`	string	Não	Texto do cabeçalho do e-mail
`email_body`	string	Não	Texto do corpo do e-mail
`type`	string	Sim	Tipo do status (por exemplo, "O" para pedido)
`is_default`	string	Não	"Y" ou "N" (padrão: "N")
`params_by_lang`	object	Não	Parâmetros do status por idioma

Um exemplo de requisição:

json

{
  "status": "S",
  "description": "Shipped",
  "email_subj": "Your order has been shipped",
  "email_header": "Your order is on its way!",
  "email_body": "Dear [customer],\n\nYour order has been shipped and is on its way to you. You can track your shipment using the tracking number below.",
  "type": "O",
  "is_default": "N",
  "params_by_lang": {
    "en": {
      "description": "Shipped",
      "email_subj": "Your order has been shipped",
      "email_header": "Your order is on its way!",
      "email_body": "Dear [customer],\n\nYour order has been shipped and is on its way to you. You can track your shipment using the tracking number below."
    },
    "es": {
      "description": "Enviado",
      "email_subj": "Su pedido ha sido enviado",
      "email_header": "¡Su pedido está en camino!",
      "email_body": "Estimado [customer],\n\nSu pedido ha sido enviado y está en camino. Puede realizar el seguimiento de su envío utilizando el número de seguimiento a continuación."
    }
  }
}

Atualizar e excluir um status

O PUT /api/statuses/{status_id}/ atualiza um status de pedido existente. Um exemplo de requisição:

json

{
  "description": "Order Completed",
  "email_header": "Your order is now complete!",
  "email_body": "Dear [customer],\n\nThank you for shopping with us. Your order has been completed and we hope you're satisfied with your purchase."
}

Ao atualizar um status, você só precisa incluir os campos que quer mudar. Os demais campos mantêm os valores atuais.

O DELETE /api/statuses/{status_id}/ exclui um status de pedido personalizado.

Endpoints

Método	Caminho	Finalidade	Autenticação
GET	`/api/statuses`	Listar os status de pedido, veja Paginação	Administrador
POST	`/api/statuses`	Criar um status de pedido personalizado, veja Endpoints	Administrador
GET	`/api/statuses/{status_id}`	Consultar um status específico, veja Endpoints	Administrador
PUT	`/api/statuses/{status_id}`	Atualizar um status, veja Endpoints	Administrador
DELETE	`/api/statuses/{status_id}`	Excluir um status personalizado, veja Endpoints	Administrador

Erros comuns

Reutilizar a letra de um status padrão num status personalizado. Escolha uma letra que os padrões não usem.
Tentar excluir um status padrão, ou um status que ainda é usado por pedidos. Mova os pedidos para outro status antes.
Enviar o status inteiro num PUT. Só os campos que você quer mudar são necessários.
Esquecer que status, description e type são obrigatórios ao criar um status.
Escrever as variáveis de e-mail em outro formato. As variáveis vão entre colchetes, como [customer].

Próximos passos

Endpoints

Todas as URLs da API de status, com exemplos.

Paginação

Escolha a página e o tamanho da página da listagem.

Campos

A referência dos campos de status.

Pedidos (REST)

Mova pedidos de um status para outro.