Credenciais dos Correios

Lê e grava o contrato dos Correios do seller (cartão de postagem, CEP de origem e prazo de preparo) e testa a conexão.

Cada seller usa o seu contrato com os Correios. Aqui ficam o cartão de postagem, o login e a senha da API dos Correios, o CEP de onde os pacotes saem e o prazo de preparo. Sem esse cadastro, o seller não tem opções Correios no checkout. A senha é gravada, mas nunca é devolvida: a leitura mostra ********.

Ler as credenciais

Se o seller nunca salvou nada, configured vem false e os demais campos vêm vazios: não é erro.

GET/api/v1/vendor/shipping/correios/configSeller

Lê as credenciais Correios do seller

Exemplo de requisição: ler

bash

curl "$BASE_URL/api/v1/vendor/shipping/correios/config" \
  -H "Authorization: Bearer $TOKEN"

Resposta: ler

200Configuração

json

{
  "configured": true,
  "cep_origem": "01310100",
  "mode": "rest",
  "resolved_mode": "rest",
  "cartao_postagem": "0067599079",
  "api_login": "lojaexemplo",
  "api_password": "********",
  "api_base_url": "",
  "processing_days": 2,
  "is_active": true
}

Campos da resposta

configuredboolean

Se o seller já salvou credenciais.

cep_origemstring

CEP de origem, 8 dígitos. Vazio = usa o do depósito ou do cadastro do seller.

modestring

rest ou vazio (equivale a rest).

resolved_modestring

Modo efetivo: rest.

cartao_postagemstring

Número do cartão de postagem do contrato.

api_loginstring

api_passwordstring

Sempre mascarada (********) quando há senha.

api_base_urlstring

Endereço da API. Vazio = o padrão da loja.

processing_daysinteger

Dias úteis de preparo antes da postagem, somados ao prazo.

is_activeboolean

Se a integração do seller está ligada. Desligada, o seller some do checkout para Correios.

Erros: ler

Status	Quando	Corpo de exemplo
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (vendor_settings ou um privilégio de leitura de configurações).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao ler.	`{"error":"failed to read Correios config"}`

Gravar as credenciais

A gravação é parcial: só os campos enviados mudam. Para trocar o CEP sem digitar a senha de novo, omita api_password ou reenvie ********: a senha guardada é mantida. Na primeira gravação, envie a senha de verdade.

PUT/api/v1/vendor/shipping/correios/configSeller

Grava as credenciais Correios do seller

Corpo da requisição

cep_origemstring

CEP de origem, 8 dígitos (hífen aceito). "" limpa.

modestring

rest

Vazio ou rest. soap é recusado para sellers.

cartao_postagemstring

Cartão de postagem do contrato.

api_loginstring

api_passwordstring

Senha da API. Omitida ou ******** = mantém a guardada.

api_base_urlstring

Só https, host dentro de correios.com.br, porta padrão, sem credenciais na URL. Vazio = padrão.

processing_daysinteger

Dias de preparo, de 0 a 100.

is_activeboolean

Liga ou desliga a integração do seller. Na primeira gravação o padrão é true.

Exemplo de requisição: gravar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/shipping/correios/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cep_origem": "01310-100",
    "cartao_postagem": "0067599079",
    "api_login": "lojaexemplo",
    "api_password": "senha-da-api",
    "processing_days": 2,
    "is_active": true
  }'

Resposta: gravar

200Gravado

json

{
  "success": true,
  "message": "CORREIOS_VENDOR_CONFIG_SAVED"
}

Campos da resposta

successboolean

Sempre true.

messagestring

Código fixo CORREIOS_VENDOR_CONFIG_SAVED.

Erros: gravar

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	`cep_origem` fora de 8 dígitos (ou `00000000`/`99999999`).	`{"error":"cep_origem must have 8 digits"}`
400	`mode` diferente de vazio ou `rest`.	`{"error":"mode must be empty or 'rest'"}`
400	`processing_days` fora de 0 a 100.	`{"error":"processing_days must be between 0 and 100"}`
400	`api_base_url` fora da regra de segurança (o `detail` explica).	`{"error":"invalid api_base_url","detail":"..."}`
400	`api_password` mascarada, mas não há senha guardada para manter.	`{"error":"no stored password to preserve","detail":"type the API password"}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (vendor_settings).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao gravar.	`{"error":"failed to save Correios config"}`

Testar a conexão

Autentica nos Correios com as credenciais gravadas do seller (grave antes de testar) e diz se funcionam. A resposta é sempre 200: o veredito está no corpo. Cada teste consome uma emissão de token do seu cartão, então evite chamar em laço.

POST/api/v1/vendor/shipping/correios/testSeller

Testa a conexão com os Correios

Exemplo de requisição: testar

bash

curl -X POST "$BASE_URL/api/v1/vendor/shipping/correios/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta: testar

200Conexão ok

json

{
  "ok": true,
  "success": true,
  "mode": "rest",
  "message": "CORREIOS_TEST_OK"
}

Campos da resposta

ok, successboolean

true quando os Correios aceitaram as credenciais.

modestring

Modo usado no teste.

messagestring

CORREIOS_TEST_OK ou CORREIOS_TEST_FAILED.

errorstring

Só na falha: o motivo.

200Conexão com falha

json

{
  "ok": false,
  "success": false,
  "mode": "rest",
  "error": "correios: vendor 5f1c... has no Correios contract of its own on this store",
  "message": "CORREIOS_TEST_FAILED"
}

Erros: testar

Status	Quando	Corpo de exemplo
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (vendor_settings).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`

Veja também

API atual/Referência completa/Correios

Credenciais dos Correios

Lê e grava o contrato dos Correios do seller (cartão de postagem, CEP de origem e prazo de preparo) e testa a conexão.

Ler as credenciais

Se o seller nunca salvou nada, configured vem false e os demais campos vêm vazios: não é erro.

GET/api/v1/vendor/shipping/correios/configSeller

Lê as credenciais Correios do seller

Exemplo de requisição: ler

bash

curl "$BASE_URL/api/v1/vendor/shipping/correios/config" \
  -H "Authorization: Bearer $TOKEN"

Resposta: ler

200Configuração

json

{
  "configured": true,
  "cep_origem": "01310100",
  "mode": "rest",
  "resolved_mode": "rest",
  "cartao_postagem": "0067599079",
  "api_login": "lojaexemplo",
  "api_password": "********",
  "api_base_url": "",
  "processing_days": 2,
  "is_active": true
}

Campos da resposta

configuredboolean

Se o seller já salvou credenciais.

cep_origemstring

CEP de origem, 8 dígitos. Vazio = usa o do depósito ou do cadastro do seller.

modestring

rest ou vazio (equivale a rest).

resolved_modestring

Modo efetivo: rest.

cartao_postagemstring

Número do cartão de postagem do contrato.

api_loginstring

api_passwordstring

Sempre mascarada (********) quando há senha.

api_base_urlstring

Endereço da API. Vazio = o padrão da loja.

processing_daysinteger

Dias úteis de preparo antes da postagem, somados ao prazo.

is_activeboolean

Se a integração do seller está ligada. Desligada, o seller some do checkout para Correios.

Erros: ler

Status	Quando	Corpo de exemplo
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (vendor_settings ou um privilégio de leitura de configurações).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao ler.	`{"error":"failed to read Correios config"}`

Gravar as credenciais

PUT/api/v1/vendor/shipping/correios/configSeller

Grava as credenciais Correios do seller

Corpo da requisição

cep_origemstring

CEP de origem, 8 dígitos (hífen aceito). "" limpa.

modestring

rest

Vazio ou rest. soap é recusado para sellers.

cartao_postagemstring

Cartão de postagem do contrato.

api_loginstring

api_passwordstring

Senha da API. Omitida ou ******** = mantém a guardada.

api_base_urlstring

Só https, host dentro de correios.com.br, porta padrão, sem credenciais na URL. Vazio = padrão.

processing_daysinteger

Dias de preparo, de 0 a 100.

is_activeboolean

Liga ou desliga a integração do seller. Na primeira gravação o padrão é true.

Exemplo de requisição: gravar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/shipping/correios/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cep_origem": "01310-100",
    "cartao_postagem": "0067599079",
    "api_login": "lojaexemplo",
    "api_password": "senha-da-api",
    "processing_days": 2,
    "is_active": true
  }'

Resposta: gravar

200Gravado

json

{
  "success": true,
  "message": "CORREIOS_VENDOR_CONFIG_SAVED"
}

Campos da resposta

successboolean

Sempre true.

messagestring

Código fixo CORREIOS_VENDOR_CONFIG_SAVED.

Erros: gravar

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	`cep_origem` fora de 8 dígitos (ou `00000000`/`99999999`).	`{"error":"cep_origem must have 8 digits"}`
400	`mode` diferente de vazio ou `rest`.	`{"error":"mode must be empty or 'rest'"}`
400	`processing_days` fora de 0 a 100.	`{"error":"processing_days must be between 0 and 100"}`
400	`api_base_url` fora da regra de segurança (o `detail` explica).	`{"error":"invalid api_base_url","detail":"..."}`
400	`api_password` mascarada, mas não há senha guardada para manter.	`{"error":"no stored password to preserve","detail":"type the API password"}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (vendor_settings).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`
503	Falha ao gravar.	`{"error":"failed to save Correios config"}`

Testar a conexão

POST/api/v1/vendor/shipping/correios/testSeller

Testa a conexão com os Correios

Exemplo de requisição: testar

bash

curl -X POST "$BASE_URL/api/v1/vendor/shipping/correios/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta: testar

200Conexão ok

json

{
  "ok": true,
  "success": true,
  "mode": "rest",
  "message": "CORREIOS_TEST_OK"
}

Campos da resposta

ok, successboolean

true quando os Correios aceitaram as credenciais.

modestring

Modo usado no teste.

messagestring

CORREIOS_TEST_OK ou CORREIOS_TEST_FAILED.

errorstring

Só na falha: o motivo.

200Conexão com falha

json

{
  "ok": false,
  "success": false,
  "mode": "rest",
  "error": "correios: vendor 5f1c... has no Correios contract of its own on this store",
  "message": "CORREIOS_TEST_FAILED"
}

Erros: testar

Status	Quando	Corpo de exemplo
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O módulo `correios-shipping` está desligado na loja.	`{"error":"module_disabled","module":"correios-shipping"}`
403	O usuário não tem conta de seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário não tem o privilégio necessário (vendor_settings).	`{"error":"insufficient vendor privileges","privilege_required_any":["..."]}`