API atual/Referência completa/Transportadoras

Listar e consultar transportadoras

Lista todas as transportadoras da loja, ativas ou não, e lê uma pelo id.

Diferente das listas públicas (que só mostram as ativas), a listagem do administrador traz todas, inclusive as desativadas, para você poder reativá-las. Não é paginada e vem ordenada por position e depois por nome.

Listar

GET/api/v1/admin/carriersAdmin

Lista as transportadoras

Exige um token de administrador.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/carriers" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Transportadoras retornadas

json

{
  "carriers": [
    {
      "id": "dcd17e6e-f428-4c84-bdb9-14800393ed51",
      "name": "Correios SEDEX",
      "code": "correios_sedex",
      "tracking_url_template": "https://rastreamento.correios.com.br/app/index.php?objetos={tracking}",
      "logo_url": "/carriers/correios.svg",
      "is_active": true,
      "position": 2,
      "created_at": "2026-03-25T04:08:44.039041Z",
      "updated_at": "2026-06-26T01:32:21.600412Z"
    },
    {
      "id": "14d5c435-5517-4c9c-8d82-42167f24157f",
      "name": "Jadlog",
      "code": "jadlog",
      "tracking_url_template": "https://www.jadlog.com.br/jadlog/tracking?cte={tracking}",
      "logo_url": "/carriers/jadlog.svg",
      "is_active": false,
      "position": 3,
      "created_at": "2026-03-25T04:08:44.039041Z",
      "updated_at": "2026-06-26T01:32:21.600412Z"
    }
  ],
  "total": 2
}

Campos da resposta

carriersarray

Transportadoras.

totalinteger

Quantidade devolvida.

carriers[].iduuid

Id da transportadora.

carriers[].namestring

Nome mostrado ao cliente.

carriers[].codestring

Código único. É o que um método de envio guarda em carrier e o que a loja usa para achar a transportadora.

carriers[].tracking_url_templatestring

Modelo da URL de rastreamento, com {tracking} no lugar do código de rastreio. Vazio = sem link.

carriers[].logo_urlstring

Caminho ou URL do logotipo.

carriers[].is_activeboolean

Se a transportadora está disponível para uso.

carriers[].positioninteger

Ordem de exibição (menor primeiro).

carriers[].created_atstring

Criação, RFC 3339 em UTC.

carriers[].updated_atstring

Última alteração, RFC 3339 em UTC.

Consultar uma

GET/api/v1/admin/carriers/{id}Admin

Lê uma transportadora

Exige um token de administrador.

Parâmetros de caminho

iduuidobrigatório

Id da transportadora.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/carriers/$CARRIER_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Transportadora encontrada

json

{
  "id": "dcd17e6e-f428-4c84-bdb9-14800393ed51",
  "name": "Correios SEDEX",
  "code": "correios_sedex",
  "tracking_url_template": "https://rastreamento.correios.com.br/app/index.php?objetos={tracking}",
  "logo_url": "/carriers/correios.svg",
  "is_active": true,
  "position": 2,
  "created_at": "2026-03-25T04:08:44.039041Z",
  "updated_at": "2026-06-26T01:32:21.600412Z"
}

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
404	O id não existe ou não é um UUID válido	`{"error":"carrier not found","detail":"carrier not found: 00000000-0000-0000-0000-000000000000"}`
500	Falha interna na listagem	`{"error":"failed to list carriers","detail":"..."}`

Veja também

Listar e consultar transportadoras

Lista todas as transportadoras da loja, ativas ou não, e lê uma pelo id.

Listar

GET/api/v1/admin/carriersAdmin

Lista as transportadoras

Exige um token de administrador.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/carriers" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Transportadoras retornadas

json

{
  "carriers": [
    {
      "id": "dcd17e6e-f428-4c84-bdb9-14800393ed51",
      "name": "Correios SEDEX",
      "code": "correios_sedex",
      "tracking_url_template": "https://rastreamento.correios.com.br/app/index.php?objetos={tracking}",
      "logo_url": "/carriers/correios.svg",
      "is_active": true,
      "position": 2,
      "created_at": "2026-03-25T04:08:44.039041Z",
      "updated_at": "2026-06-26T01:32:21.600412Z"
    },
    {
      "id": "14d5c435-5517-4c9c-8d82-42167f24157f",
      "name": "Jadlog",
      "code": "jadlog",
      "tracking_url_template": "https://www.jadlog.com.br/jadlog/tracking?cte={tracking}",
      "logo_url": "/carriers/jadlog.svg",
      "is_active": false,
      "position": 3,
      "created_at": "2026-03-25T04:08:44.039041Z",
      "updated_at": "2026-06-26T01:32:21.600412Z"
    }
  ],
  "total": 2
}

Campos da resposta

carriersarray

Transportadoras.

totalinteger

Quantidade devolvida.

carriers[].iduuid

Id da transportadora.

carriers[].namestring

Nome mostrado ao cliente.

carriers[].codestring

Código único. É o que um método de envio guarda em carrier e o que a loja usa para achar a transportadora.

carriers[].tracking_url_templatestring

Modelo da URL de rastreamento, com {tracking} no lugar do código de rastreio. Vazio = sem link.

carriers[].logo_urlstring

Caminho ou URL do logotipo.

carriers[].is_activeboolean

Se a transportadora está disponível para uso.

carriers[].positioninteger

Ordem de exibição (menor primeiro).

carriers[].created_atstring

Criação, RFC 3339 em UTC.

carriers[].updated_atstring

Última alteração, RFC 3339 em UTC.

Consultar uma

GET/api/v1/admin/carriers/{id}Admin

Lê uma transportadora

Exige um token de administrador.

Parâmetros de caminho

iduuidobrigatório

Id da transportadora.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/carriers/$CARRIER_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Transportadora encontrada

json

{
  "id": "dcd17e6e-f428-4c84-bdb9-14800393ed51",
  "name": "Correios SEDEX",
  "code": "correios_sedex",
  "tracking_url_template": "https://rastreamento.correios.com.br/app/index.php?objetos={tracking}",
  "logo_url": "/carriers/correios.svg",
  "is_active": true,
  "position": 2,
  "created_at": "2026-03-25T04:08:44.039041Z",
  "updated_at": "2026-06-26T01:32:21.600412Z"
}

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
404	O id não existe ou não é um UUID válido	`{"error":"carrier not found","detail":"carrier not found: 00000000-0000-0000-0000-000000000000"}`
500	Falha interna na listagem	`{"error":"failed to list carriers","detail":"..."}`