REST API: rastreio em pedidos

O plugin registra um campo customizado, shipping_tracking_code, no recurso orders da REST API do WooCommerce. Você pode ler e gravar códigos de rastreio sem entrar no admin — útil pra integrar a loja com o sistema de etiquetas (ex: Melhor Envio, Bling, ERP próprio).

A autenticação, os escopos e o endpoint base são os do próprio WooCommerce. Veja a documentação oficial da WooCommerce REST API pra detalhes de keys e permissões.

Endpoint

GET  /wp-json/wc/v3/orders/{id}
PUT  /wp-json/wc/v3/orders/{id}

O campo shipping_tracking_code é exposto pra leitura (GET) e escrita (PUT). Tem o mesmo comportamento que adicionar pelo admin: dispara e-mail pro cliente, adiciona nota interna, e pode atualizar o status do pedido conforme status do pedido.

GET — listar todos os códigos do pedido

GET /wp-json/wc/v3/orders/123?_fields=id,shipping_tracking_code

Resposta:

{
  "id": 123,
  "shipping_tracking_code": [
    {
      "company_id": "0",
      "name": "Sedex",
      "tracking_code": "BR123456789BR"
    },
    {
      "company_id": "1",
      "name": "Jadlog",
      "tracking_code": "JL987654321BR"
    }
  ]
}

Se o pedido não tem rastreio, o array vem vazio.

Campo	Descrição
`company_id`	Slug interno da transportadora — o índice do array de transportadoras cadastradas em cadastrar transportadoras.
`name`	Nome da transportadora exibido pro cliente. Se a transportadora foi removida, vira `Transportadora`.
`tracking_code`	O código em si.

PUT — adicionar um código

PUT /wp-json/wc/v3/orders/123
Content-Type: application/json

{
  "shipping_tracking_code": {
    "company_id": "0",
    "tracking_code": "BR123456789BR"
  }
}

Campo	Obrigatório?	Descrição
`company_id`	sim	Slug interno da transportadora. Deve corresponder a uma cadastrada em cadastrar transportadoras.
`tracking_code`	sim	O código de rastreio a adicionar.

A resposta volta com o pedido completo (formato padrão do WooCommerce). O campo shipping_tracking_code na resposta já reflete o código recém-adicionado.

Cada PUT adiciona um código — não substitui

A REST API só permite adicionar. Não tem operação de "remover" via API. Pra remover, use o admin (X no metabox Código de rastreio) ou o helper PHP wc_any_shipping_notify_update_tracking_code() com $remove = true. Veja funções helper.

Como descobrir o `company_id`

O company_id é o índice numérico da transportadora dentro do array de transportadoras cadastradas (a primeira é "0", a segunda é "1", e assim por diante).

Se você não sabe os índices, faça um GET em qualquer pedido que já tenha rastreio (a resposta traz o company_id correspondente). Ou liste as transportadoras pelo helper PHP wc_any_shipping_notify_get_shipping_companies(), documentado em funções helper.

Ordem importa

Reordenar transportadoras na tela de configuração muda os índices. Se você tem integração externa que envia company_id numérico, padronize a lista antes de ligar a integração.

Erros e respostas

401 Unauthorized — credenciais ausentes ou inválidas.
404 Not Found — pedido {id} não existe.
PUT sem company_id ou tracking_code — o plugin ignora silenciosamente. A resposta volta 200 com o pedido sem alterações no shipping_tracking_code. Sempre confira na resposta se o código realmente foi adicionado.
company_id que não existe — o código é salvo mesmo assim, mas o name retornado fica como Transportadora e o link aparece pro cliente apontando pra página da conta.

Próximo passo

Se você está integrando, dê uma olhada também em hooks: actions e filtros — em particular o action wcasn_tracking_added, que dispara depois de qualquer adição (admin ou API), e é o ponto certo pra disparar webhooks ou logs externos.