VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Brasil: preço por UF e destinos

Regras de destino

Libera ou bloqueia a entrega de produtos, sellers e categorias por UF, cidade ou faixa de CEP.

Use quando um produto não pode ser entregue em certas regiões (regulamentação, logística, contrato com o fornecedor). Se o destino do pedido cai em uma regra deny, o pedido é recusado na criação, com o reason da regra. A verificação roda para cada produto do pedido; se a consulta falha por erro interno, o pedido segue (a verificação falha aberta).

Listar regras

GET/api/v1/admin/brazil/destination-permissionsAdmin

Lista regras de destino

Parâmetros de consulta

entity_typestring
productvendorcategoryglobal
Filtra por alvo.
entity_idinteger
Filtra por número do alvo.
state_codestring
Filtra por UF.
rule_typestring
allow ou deny.
statusstring
A/active ou D/disabled.
pageintegerpadrão: 1
Página (padrão 1).
per_pageintegerpadrão: 20
Itens por página, de 1 a 100; fora disso vale 20.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/brazil/destination-permissions?entity_type=product&page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regras
json
{
  "permissions": [
    {
      "id": 4,
      "rule_type": "deny",
      "entity_type": "product",
      "entity_id": 9825,
      "state_code": "RJ",
      "city_id": 0,
      "cep_range_from": "",
      "cep_range_to": "",
      "reason": "Produto proibido no RJ",
      "status": "A",
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Campos da resposta

totalinteger
Total que casa com o filtro.
pageinteger
Página pedida. Vem 0 se você não enviou page.
per_pageinteger
Tamanho pedido. Vem 0 se você não enviou per_page.
permissionsarray
Regras, ordenadas por alvo, número e UF.
idinteger
Id numérico da regra.
rule_typestring
allowdeny
allow ou deny.
entity_typestring
productvendorcategoryglobal
A quem a regra se aplica.
entity_idinteger
display_id do produto ou seller, ou legacy_id da categoria; 0 para global.
state_codestring
UF; vazio = todas.
city_idinteger
Id numérico da cidade; 0 = todas.
cep_range_fromstring
CEP inicial, 8 dígitos; vazio = sem limite.
cep_range_tostring
CEP final, 8 dígitos.
reasonstring
Texto mostrado ao cliente quando bloqueia.
statusstring
AD
A ou D.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_brazil nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}

Criar uma regra

POST/api/v1/admin/brazil/destination-permissionsAdmin

Cria regra de destino

Corpo da requisição

rule_typestringobrigatório
allowdeny
allow ou deny.
entity_typestringobrigatório
productvendorcategoryglobal
Alvo da regra.
entity_idinteger
Número do alvo (positivo); 0 obrigatório para global.
state_codestring
UF opcional.
city_idinteger
Cidade opcional.
cep_range_fromstring
CEP inicial; pontos e hífen são removidos.
cep_range_tostring
CEP final; não pode ser menor que o inicial.
reasonstring
Motivo exibido ao cliente.
statusstring
active/A ou disabled/D. Vazio = ativa.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/brazil/destination-permissions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "deny",
    "entity_type": "product",
    "entity_id": 9825,
    "state_code": "RJ",
    "reason": "Produto proibido no RJ"
  }'

Resposta

201Regra criada
json
{
  "id": 4,
  "rule_type": "deny",
  "entity_type": "product",
  "entity_id": 9825,
  "state_code": "RJ",
  "city_id": 0,
  "cep_range_from": "",
  "cep_range_to": "",
  "reason": "Produto proibido no RJ",
  "status": "A",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger
Id numérico da regra.
rule_typestring
allowdeny
allow ou deny.
entity_typestring
productvendorcategoryglobal
A quem a regra se aplica.
entity_idinteger
display_id do produto ou seller, ou legacy_id da categoria; 0 para global.
state_codestring
UF; vazio = todas.
city_idinteger
Id numérico da cidade; 0 = todas.
cep_range_fromstring
CEP inicial, 8 dígitos; vazio = sem limite.
cep_range_tostring
CEP final, 8 dígitos.
reasonstring
Texto mostrado ao cliente quando bloqueia.
statusstring
AD
A ou D.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
400rule_type/entity_type inválidos, entity_id incoerente, UF inexistente ou CEP malformado.{"error":"entity_id must be positive for non-global rules"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_brazil nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}
entity_id é número, não UUID

Use o display_id do produto ou do seller (campo numérico nas respostas de produto) e o legacy_id da categoria. Um id errado cria uma regra que nunca casa com nada.

Verificar um destino

Responde se a entrega é permitida para o destino, usando as mesmas regras do checkout. Não cria nada.

POST/api/v1/admin/brazil/destination-permissions/checkAdmin

Verifica um destino

Corpo da requisição

product_idinteger
display_id do produto.
vendor_idinteger
display_id do seller.
category_idinteger
legacy_id da categoria.
state_codestring
UF do destino.
city_idinteger
Cidade do destino.
cepstring
CEP do destino.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/brazil/destination-permissions/check" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 9825,
    "state_code": "RJ"
  }'

Resposta

200Resultado
json
{
  "allowed": false,
  "reason": "Produto proibido no RJ",
  "matching_rule_id": 4
}

Campos da resposta

allowedboolean
true se pode entregar.
reasonstring
Motivo da regra que decidiu; vazio se nenhuma casou.
matching_rule_idinteger
Regra que decidiu; 0 se nenhuma.

Erros

StatusQuandoCorpo de exemplo
400Nenhum de state_code, city_id ou cep foi enviado.{"error":"a destination (state_code, city_id, or cep) is required"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_brazil nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}

Alterar uma regra

Atualização parcial: só os campos enviados mudam. As validações de coerência do cadastro (por exemplo global com entity_id 0) não são refeitas aqui.

PUT/api/v1/admin/brazil/destination-permissions/{id}Admin

Altera regra de destino

Parâmetros de caminho

idintegerobrigatório
Id numérico da regra.

Corpo da requisição

rule_typestring
allowdeny
allow ou deny.
entity_typestring
productvendorcategoryglobal
Alvo da regra.
entity_idinteger
Número do alvo (positivo); 0 obrigatório para global.
state_codestring
UF opcional.
city_idinteger
Cidade opcional.
cep_range_fromstring
CEP inicial; pontos e hífen são removidos.
cep_range_tostring
CEP final; não pode ser menor que o inicial.
reasonstring
Motivo exibido ao cliente.
statusstring
active/A ou disabled/D. Vazio = ativa.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/brazil/destination-permissions/4" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "disabled"
  }'

Resposta

200Regra alterada
json
{
  "id": 4,
  "rule_type": "deny",
  "entity_type": "product",
  "entity_id": 9825,
  "state_code": "RJ",
  "city_id": 0,
  "cep_range_from": "",
  "cep_range_to": "",
  "reason": "Produto proibido no RJ",
  "status": "D",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger
Id numérico da regra.
rule_typestring
allowdeny
allow ou deny.
entity_typestring
productvendorcategoryglobal
A quem a regra se aplica.
entity_idinteger
display_id do produto ou seller, ou legacy_id da categoria; 0 para global.
state_codestring
UF; vazio = todas.
city_idinteger
Id numérico da cidade; 0 = todas.
cep_range_fromstring
CEP inicial, 8 dígitos; vazio = sem limite.
cep_range_tostring
CEP final, 8 dígitos.
reasonstring
Texto mostrado ao cliente quando bloqueia.
statusstring
AD
A ou D.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
400Id inválido, enum inválido ou status diferente de ativa/desativada.{"error":"status must be 'A' (active) or 'D' (disabled)"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_brazil nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}
404Regra inexistente.{"error":"destination permission 4 not found"}

Remover uma regra

DELETE/api/v1/admin/brazil/destination-permissions/{id}Admin

Remove regra de destino

Parâmetros de caminho

idintegerobrigatório
Id numérico da regra.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/brazil/destination-permissions/4" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removida
json
{
  "status": "deleted"
}

Erros

StatusQuandoCorpo de exemplo
400Id inválido.{"error":"invalid permission ID"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_brazil nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}
404Regra inexistente.{"error":"destination permission 4 not found"}

Veja também

  • Brasil
Anterior
Preço por UF em lote e simulação
Próxima
Consultas: CNPJ, CNAE e UFs
Nesta página
  • Listar regras
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar uma regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Verificar um destino
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar uma regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Remover uma regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também