API atual/Referência completa/Transportadoras

Gerenciar transportadoras

Cadastra, altera, liga e desliga ou apaga uma transportadora, incluindo o modelo de link de rastreamento.

Quatro operações de manutenção do cadastro. Nenhuma delas dispara e-mail ou evento; as mudanças valem imediatamente para os próximos envios.

Cadastrar

POST/api/v1/admin/carriersAdmin

Cria uma transportadora

Exige um token de administrador.

Corpo da requisição

namestringobrigatório

Nome mostrado ao cliente.

codestringobrigatório

Código único, estável (ex.: jadlog). Letras minúsculas e _ evitam surpresas.

tracking_url_templatestring

URL com {tracking} no lugar do código de rastreio.

logo_urlstring

Caminho ou URL do logotipo.

is_activebooleanpadrão: true

Se está ativa.

positionintegerpadrão: 0

Ordem de exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/carriers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs Express",
    "code": "docs_express",
    "tracking_url_template": "https://example.com/track/{tracking}",
    "position": 9
  }'

Resposta

201Transportadora criada

json

{
  "id": "dcd5a2cd-b17c-48a8-b2c2-0f0bba908da1",
  "name": "Docs Express",
  "code": "docs_express",
  "tracking_url_template": "https://example.com/track/{tracking}",
  "logo_url": "",
  "is_active": true,
  "position": 9,
  "created_at": "2026-03-25T04:08:44.039041Z",
  "updated_at": "2026-06-26T01:32:21.600412Z"
}

Alterar

Alteração parcial: só os campos enviados mudam. Um corpo vazio devolve a transportadora sem alterar nada.

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

Altera uma transportadora

Exige um token de administrador.

Parâmetros de caminho

iduuidobrigatório

Id da transportadora.

Corpo da requisição

namestring

Nome.

codestring

Código. Mudar o código não atualiza os métodos de envio que usam o antigo.

tracking_url_templatestring

Modelo do link.

logo_urlstring

Logotipo.

is_activeboolean

Ativa ou não.

positioninteger

Ordem.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/carriers/$CARRIER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_url_template": "https://example.com/rastreio/{tracking}"
  }'

Resposta

200Transportadora alterada

json

{
  "id": "dcd17e6e-f428-4c84-bdb9-14800393ed51",
  "name": "Correios SEDEX",
  "code": "correios_sedex",
  "tracking_url_template": "https://example.com/rastreio/{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"
}

Ligar ou desligar

Inverte is_active e devolve a transportadora. Sem corpo.

PATCH/api/v1/admin/carriers/{id}/toggleAdmin

Liga ou desliga uma transportadora

Exige um token de administrador.

Parâmetros de caminho

iduuidobrigatório

Id da transportadora.

Exemplo de requisição

bash

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

Resposta

200Estado invertido

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": false,
  "position": 2,
  "created_at": "2026-03-25T04:08:44.039041Z",
  "updated_at": "2026-06-26T01:32:21.600412Z"
}

Apagar

Remove o cadastro. É recusado com 409 se algum método de envio ainda tem esta transportadora no campo carrier.

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

Apaga uma transportadora

Exige um token de administrador.

Parâmetros de caminho

iduuidobrigatório

Id da transportadora.

Exemplo de requisição

bash

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

Resposta

200Transportadora apagada

json

{
  "message": "carrier deleted"
}

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
400	Corpo que não é JSON; `name` ou `code` vazio na criação	`{"error":"name is required"}` / `{"error":"code is required"}`
404	Só no `toggle`: o id não existe	`{"error":"carrier not found","detail":"..."}`
409	Apagar uma transportadora usada por algum método de envio	`{"error":"carrier in use","detail":"reassign or delete dependent shipping methods first"}`
500	`code` repetido, ou alterar/apagar um id que não existe	`{"error":"failed to create carrier","detail":"já existe um registro com esse valor (campo \"code\")..."}`

Veja também

API atual/Referência completa/Transportadoras

Gerenciar transportadoras

Cadastra, altera, liga e desliga ou apaga uma transportadora, incluindo o modelo de link de rastreamento.

Quatro operações de manutenção do cadastro. Nenhuma delas dispara e-mail ou evento; as mudanças valem imediatamente para os próximos envios.

Cadastrar

POST/api/v1/admin/carriersAdmin

Cria uma transportadora

Exige um token de administrador.

Corpo da requisição

namestringobrigatório

Nome mostrado ao cliente.

codestringobrigatório

Código único, estável (ex.: jadlog). Letras minúsculas e _ evitam surpresas.

tracking_url_templatestring

URL com {tracking} no lugar do código de rastreio.

logo_urlstring

Caminho ou URL do logotipo.

is_activebooleanpadrão: true

Se está ativa.

positionintegerpadrão: 0

Ordem de exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/carriers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs Express",
    "code": "docs_express",
    "tracking_url_template": "https://example.com/track/{tracking}",
    "position": 9
  }'

Resposta

201Transportadora criada

json

{
  "id": "dcd5a2cd-b17c-48a8-b2c2-0f0bba908da1",
  "name": "Docs Express",
  "code": "docs_express",
  "tracking_url_template": "https://example.com/track/{tracking}",
  "logo_url": "",
  "is_active": true,
  "position": 9,
  "created_at": "2026-03-25T04:08:44.039041Z",
  "updated_at": "2026-06-26T01:32:21.600412Z"
}

Alterar

Alteração parcial: só os campos enviados mudam. Um corpo vazio devolve a transportadora sem alterar nada.

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

Altera uma transportadora

Exige um token de administrador.

Parâmetros de caminho

iduuidobrigatório

Id da transportadora.

Corpo da requisição

namestring

Nome.

codestring

Código. Mudar o código não atualiza os métodos de envio que usam o antigo.

tracking_url_templatestring

Modelo do link.

logo_urlstring

Logotipo.

is_activeboolean

Ativa ou não.

positioninteger

Ordem.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/carriers/$CARRIER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_url_template": "https://example.com/rastreio/{tracking}"
  }'

Resposta

200Transportadora alterada

json

{
  "id": "dcd17e6e-f428-4c84-bdb9-14800393ed51",
  "name": "Correios SEDEX",
  "code": "correios_sedex",
  "tracking_url_template": "https://example.com/rastreio/{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"
}

Ligar ou desligar

Inverte is_active e devolve a transportadora. Sem corpo.

PATCH/api/v1/admin/carriers/{id}/toggleAdmin

Liga ou desliga uma transportadora

Exige um token de administrador.

Parâmetros de caminho

iduuidobrigatório

Id da transportadora.

Exemplo de requisição

bash

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

Resposta

200Estado invertido

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": false,
  "position": 2,
  "created_at": "2026-03-25T04:08:44.039041Z",
  "updated_at": "2026-06-26T01:32:21.600412Z"
}

Apagar

Remove o cadastro. É recusado com 409 se algum método de envio ainda tem esta transportadora no campo carrier.

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

Apaga uma transportadora

Exige um token de administrador.

Parâmetros de caminho

iduuidobrigatório

Id da transportadora.

Exemplo de requisição

bash

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

Resposta

200Transportadora apagada

json

{
  "message": "carrier deleted"
}

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
400	Corpo que não é JSON; `name` ou `code` vazio na criação	`{"error":"name is required"}` / `{"error":"code is required"}`
404	Só no `toggle`: o id não existe	`{"error":"carrier not found","detail":"..."}`
409	Apagar uma transportadora usada por algum método de envio	`{"error":"carrier in use","detail":"reassign or delete dependent shipping methods first"}`
500	`code` repetido, ou alterar/apagar um id que não existe	`{"error":"failed to create carrier","detail":"já existe um registro com esse valor (campo \"code\")..."}`