# Primeiros passos com a API G360

A API dos sistemas externos integra aplicações ao ERP G360. O G360 valida as permissões e aplica as regras comerciais da loja. Consulte na API o preço, a disponibilidade e a situação do pedido quando precisar tomar uma decisão de compra.

## Acesso e ambiente de testes

Solicite a liberação da empresa em [contato@movimentosistemas.com.br](mailto:contato@movimentosistemas.com.br). A Movimento Sistemas informa a URL-base, o identificador da loja e o ambiente de testes disponível para a integração. Senhas e chave de sistema são fornecidas por canal separado.

Acrescente `/b2b/v1/lojas/{loja}` à URL-base. O identificador em `{loja}` tem 16 caracteres hexadecimais minúsculos. Neste guia, os caminhos estão abreviados a partir desse prefixo.

- **Operações públicas.** Use `GET /loja` para conferir a configuração exposta pela loja. A liberação é verificada em cada chamada.
- **Comprador.** Abra a sessão em `POST /sessoes` e envie o token em `Authorization: Bearer <token>`. Use `GET /me` para conferir o comprador e a situação de compra. Encerre em `DELETE /sessao`.
- **Operador.** Abra uma sessão própria em `POST /operadores/sessoes` com um usuário do G360. A empresa e as permissões da operação são verificadas pelo servidor. Encerre em `DELETE /operadores/sessao`.
- **Acesso entre servidores.** Use `X-Chave-Sistema` em `POST /acessos/links`. Guarde a chave no servidor da aplicação e faça essa chamada sem o cabeçalho `Origin`.

A sessão expira por inatividade, com padrão de 8 minutos configurável por loja, ou após 12 horas. Com a licença compartilhada ativa, a vaga do operador vence após 180 segundos sem atividade. Um token revogado exige novo login. Em HTTP 401 numa rota protegida, descarte o token inválido e peça nova autenticação. Após `PUT /senha`, substitua o token anterior pelo retornado pela API.

## Primeiro acesso e recuperação de senha

1. Quando o comprador solicitar o acesso, chame `POST /acessos/links` no servidor da aplicação.
2. Em HTTP 201, envie o link ao endereço retornado em `dados.email`. Em homologação, a API devolve o endereço de teste configurado na loja.
3. Mostre a mesma mensagem ao comprador quando a solicitação for aceita ou recusada para o cadastro. Por exemplo, “Se a solicitação puder ser atendida, você receberá as instruções por e-mail.”
4. Coloque o token no fragmento do link, após `#`. A página de destino lê e remove o fragmento e envia `token` e `senha_nova` em `POST /acessos/senha`. Depois do HTTP 204, o comprador pode entrar com a nova senha.

O link tem uso único e vale 30 minutos. Uma nova emissão invalida o link anterior. A troca de senha por link encerra as sessões do comprador.

## Catálogo e pedidos

1. Consulte o catálogo com `GET /produtos` ou `POST /produtos/busca`. Use o `id` numérico para relacionar itens entre catálogo, revisão e pedido. O campo `codigo` contém o código comercial, pesquisável pelo filtro `codigos`. Use `GET /grupos` e `GET /marcas` para filtros. Quando houver foto vinculada, faça a leitura com o Bearer do comprador em `GET /produtos/{id}/fotos/{item}`.
2. Consulte entrega e pagamento com `GET /opcoes`. Para incluir um endereço, consulte `GET /enderecos/referencias` e use `POST /enderecos`.
3. Revise o carrinho em `POST /revisoes`. Mesmo em HTTP 200, confira `dados.pode_enviar` e trate `dados.pendencias`. Se a loja exigir previsão de entrega, informe a data em `AAAA-MM-DD`.
4. Envie o carrinho revisado para `POST /pedidos` com a `assinatura` da revisão mais recente e o cabeçalho `Idempotency-Key`. A primeira gravação bem-sucedida retorna HTTP 201. O pedido pode sair numerado ou aguardar aprovação.
5. Consulte o histórico da integração em `GET /pedidos` e o detalhe em `GET /pedidos/{id}`. Para reaproveitar itens de compras anteriores, use os identificadores de `GET /historico-compras` em `GET /produtos?ids=101,102` ou no campo `ids` de `POST /produtos/busca`. A busca aceita até 500 identificadores. Percorra os resultados com `pagina` e `limite`.

### Reenvio com idempotência

Gere uma chave para cada novo envio intencional. Use de 16 a 64 caracteres entre letras, números, `_` e `-`. Guarde a chave e o corpo da requisição até confirmar o resultado. A chave continua válida para o mesmo comprador na loja depois de um novo login.

| Retorno | Ação |
| --- | --- |
| Timeout ou conexão interrompida | Consulte `GET /pedidos/por-chave/{chave}`. Se retornar HTTP 404 com `NAO_ENCONTRADO` em `erro.codigo`, reenvie o mesmo corpo com a mesma chave. |
| HTTP 409 com `OPERACAO_EM_ANDAMENTO` ou `VENDA_EM_ANDAMENTO` | Aguarde pelo menos 3 segundos e repita o envio com a mesma chave. |
| HTTP 409 com `REVISAO_ALTERADA` | Revise o carrinho, apresente o resultado atualizado e envie com a nova assinatura e a mesma chave. |
| HTTP 409 com `CHAVE_REUTILIZADA` | Consulte o pedido existente pela chave. |
| HTTP 503 com `INDISPONIVEL` | Aguarde pelo menos 30 segundos. Consulte pela mesma chave antes de reenviar. |
| HTTP 201 ou 200 com pedido | Registre o pedido retornado. O HTTP 200 num reenvio recupera o pedido já gravado. |

## Operações do operador

A sessão do operador dá acesso à consulta de clientes por CNPJ, ao catálogo e às operações de foto, preço, custo, margem e preço congelado, conforme as permissões do usuário no G360. Confira a exigência de cada rota na referência.

- **Clientes.** `POST /operadores/clientes/consulta` exige o acesso `00500`.
- **Produtos e preços.** `POST /operadores/produtos/busca` exige `01100` e pode listar produtos fora do catálogo do comprador. `POST /operadores/produtos/precos` recebe o cliente e até 50 IDs. Exige `01100` e `00500`. A visualização de custo e margem exige `01110`.
- **Fotos.** Use as rotas em `/operadores/produtos/{id}/fotos` para listar, ler, incluir, remover e ordenar fotos ou selecionar a capa. A inclusão aceita um JPEG de até 2 MiB por chamada e a galeria aceita até 12 fotos por produto.
- **Preço congelado.** Use `/operadores/clientes/{cliente}/precos-congelados`. O acesso `500110` controla a operação. A vigência inclui as datas inicial e final. Para a mesma combinação de cliente, produto avulso e unidade, os períodos não podem se sobrepor.

## Respostas e suporte

Nas respostas JSON de sucesso, consulte `dados` e `request_id`. Listagens podem trazer `paginacao`. Fotos são retornadas como conteúdo binário. HTTP 204 não tem corpo.

Trate erros pelo status HTTP e por `erro.codigo`. Use `erro.mensagem` para orientar o usuário quando for apropriado e `erro.responsavel` para encaminhar a ocorrência. Se o responsável faltar ou for desconhecido, trate como `integracao`. Métodos e parâmetros de rota inválidos podem ser recusados antes desse envelope.

- `usuario`. Peça a correção dos dados ou apresente uma opção válida.
- `fornecedor`. Encaminhe ao responsável pelo cadastro ou pela configuração no G360.
- `tentar_de_novo`. Respeite o tempo de espera da operação. Para pedidos, siga a tabela de reenvio.
- `integracao`. Registre o `request_id` e use uma mensagem genérica na interface.

Em `REVISAO_BLOQUEADA`, trate cada pendência de `erro.campos.pendencias` pelo seu próprio `responsavel`. No suporte, informe o método, o caminho, o horário, o status e o `request_id`. Omita credenciais, tokens, documentos e dados pessoais dos registros e chamados.

## Limites e CORS

| Limite | Regra |
| --- | --- |
| Chamadas | 240 por minuto por endereço IP e loja, incluindo fotos. Slugs desconhecidos compartilham um limite de 60 por minuto por IP. |
| Login de comprador e de operador | Contadores separados. A cada 15 minutos e por loja, 5 falhas por identificador e IP, 40 por IP e 50 por identificador. O identificador é o documento do comprador ou o usuário do operador. |
| Link | Em 15 minutos, até 3 emissões por documento na loja, 60 por chave de sistema e 10 tentativas de gravar senha por IP. |
| Corpo | Até 65.536 bytes. Na inclusão de foto pelo operador, até 2.804.096 bytes no corpo. |
| Paginação de produtos e pedidos | `pagina` de 1 a 100.000, padrão 1. `limite` de 1 a 50, padrão 20. |
| Carrinho | De 1 a 100 linhas. Até 400 caracteres na observação. |

Para chamadas de navegador, informe à Movimento as origens exatas, incluindo esquema e porta quando necessário. Em HTTP, use somente `localhost` com porta explícita diferente de 80. O preflight aceita `Authorization`, `Content-Type` e `Idempotency-Key`. Integrações que compartilham um IP também compartilham o limite por loja. Em HTTP 429, aumente o intervalo entre tentativas.

## Integração com apoio de IA

Forneça ao assistente o [contrato OpenAPI 3.1](downloads/api-sistemas-externos-2026-11-16.yaml) e indique quais operações você precisa implementar. A referência define os métodos, caminhos, esquemas, permissões e exemplos da versão. Use os exemplos fictícios para gerar código e testes. Forneça a URL de teste e as credenciais ao aplicativo por configuração protegida. Mantenha esses valores fora de prompts e arquivos de exemplo.

> Gere uma integração para consultar o catálogo e enviar pedidos ao G360. Use a especificação OpenAPI desta edição. Confirme a sessão do comprador, valide `pode_enviar` e `pendencias` antes do envio e preserve a `Idempotency-Key` nos reenvios. Use variáveis de ambiente e testes com respostas fictícias.

## Catálogo de mensagens

Use os códigos para controlar o fluxo. As mensagens podem conter valores preenchidos pelo G360 durante a operação.

| Código | Tipo | HTTP | Operações | Quando acontece | Mensagem da API | Quem resolve | O que a tela deve fazer |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `ACESSO_INVALIDO` | Erro | 401 | `POST sessoes` | O documento e a senha não identificam uma conta que possa entrar. | “CNPJ/CPF ou senha inválidos.” | `usuario` | Peça para conferir os campos ou ofereça recuperação com resposta neutra. |
| `BUSCA_INVALIDA` | Erro | 422 | `GET produtos`, `POST operadores/produtos/busca`, `POST produtos/busca` | O texto ou o formato da busca é inválido. | “Busca inválida.” | `usuario` | Peça para ajustar a busca. |
| `CADASTRO_NAO_LOCALIZADO` | Erro | 404 | `POST acessos/links` | O documento não identifica um único cadastro ativo na emissão do link. | “O documento não identifica um cadastro ativo único.” | `usuario` | Mantenha a resposta neutra. |
| `CADASTRO_SEM_ACESSO` | Erro | 403 | `POST acessos/links` | O cadastro não pode usar o link. | “O cadastro está bloqueado para acesso pelo link.” | `fornecedor` | Mantenha a resposta neutra e registre a ocorrência no servidor. |
| `CADASTRO_SEM_EMAIL` | Erro | 422 | `POST acessos/links` | O cadastro não tem e-mail válido para emitir o link. | “O cadastro não tem um e-mail válido.” | `fornecedor` | Mantenha a resposta neutra e registre a ocorrência no servidor. |
| `CAMPO_NAO_PERMITIDO` | Erro | 422 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `GET operadores/clientes/{cliente}/precos-congelados`, `POST acessos/links`, `POST acessos/senha`, `POST enderecos`, `POST operadores/clientes/consulta`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/busca`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `POST operadores/sessoes`, `POST pedidos`, `POST produtos/busca`, `POST revisoes`, `POST sessoes`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem`, `PUT senha` | O corpo traz um campo que a operação não aceita. | “A solicitação tem campos que a API não aceita.” | `integracao` | Mostre a mensagem genérica e confira os campos do contrato. |
| `CHAVE_INVALIDA` | Erro | 400 | `POST pedidos` | A chave de envio está ausente ou tem formato inválido. | “Envio sem identificação. Atualize a página e tente novamente.” | `integracao` | Mostre a mensagem genérica e corrija o cabeçalho. |
| `CHAVE_REUTILIZADA` | Erro | 409 | `POST pedidos` | Já existe pedido para a chave e o envio não é comparável ao original. | “Este envio já foi registrado. Consulte o pedido pela chave de envio.” | `integracao` | Consulte o pedido pela mesma chave antes de oferecer novo envio. |
| `CHAVE_SISTEMA_INVALIDA` | Erro | 401 | `POST acessos/links` | A chave de sistema é inválida ou a chamada chegou com Origin. | “Chave de sistema inválida.” | `integracao` | Preserve a resposta neutra do link e confira a configuração do servidor. |
| `CLIENTE_AMBIGUO` | Erro | 409 | `POST operadores/clientes/consulta` | O operador encontrou mais de um cadastro com o mesmo CNPJ no recorte permitido. | “Há mais de um cadastro com este CNPJ. Confira os cadastros no G360.” | `fornecedor` | Encaminhe a ocorrência para conferência de cadastros. |
| `CLIENTE_NAO_LOCALIZADO` | Erro | 404 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `GET operadores/clientes/{cliente}/precos-congelados`, `POST operadores/clientes/consulta`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/precos`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}` | O operador não encontrou cliente ativo no recorte permitido. | “Cliente não localizado.” | `usuario` | Peça para revisar o CNPJ ou escolher outro cliente. |
| `CNPJ_INVALIDO` | Erro | 422 | `POST operadores/clientes/consulta` | O CNPJ digitado pelo operador não passa na validação. | “Informe um CNPJ válido.” | `usuario` | Peça para conferir o CNPJ e seus dígitos. |
| `CONDICAO_INVALIDA` | Erro | 422 | `POST pedidos`, `POST revisoes` | A condição escolhida não pertence à lista disponível para o comprador. | “Condição de pagamento não disponível para o seu cadastro.” | `usuario` | Atualize as opções e peça para escolher outra condição. |
| `CORPO_GRANDE` | Erro | 413 | `DELETE operadores/produtos/{id}/fotos/{item}`, `DELETE operadores/sessao`, `DELETE sessao`, `GET enderecos/referencias`, `GET grupos`, `GET historico-compras`, `GET loja`, `GET marcas`, `GET me`, `GET opcoes`, `GET operadores/produtos/{id}/fotos`, `GET operadores/produtos/{id}/fotos/{item}`, `GET pedidos`, `GET pedidos/por-chave/{chave}`, `GET pedidos/{id}`, `GET produtos`, `GET produtos/{id}/fotos/{item}`, `POST acessos/links`, `POST acessos/senha`, `POST enderecos`, `POST operadores/clientes/consulta`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/busca`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `POST operadores/sessoes`, `POST pedidos`, `POST produtos/busca`, `POST revisoes`, `POST sessoes`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem`, `PUT senha` | O corpo excede o limite da API. | “Solicitação grande demais.” | `integracao` | Mostre a mensagem genérica e reduza o corpo da requisição. |
| `DADOS_INVALIDOS` | Erro | 422 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `GET enderecos/referencias`, `GET historico-compras`, `GET operadores/clientes/{cliente}/precos-congelados`, `POST enderecos`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `POST pedidos`, `POST revisoes`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem` | O formato da requisição ou dados como data, endereço e filtros do histórico não passam na validação. | “A cidade não corresponde à UF informada.”<br>“A descrição da foto deve ter até 50 caracteres.”<br>“Bairro não encontrado no cadastro.”<br>“Confira o período do histórico.”<br>“Confira os dados do endereço.”<br>“Confira os dados informados.”<br>“Confira os produtos do histórico.”<br>“Informe cada foto do produto uma vez na ordem desejada.”<br>“Informe códigos inteiros positivos de produto.”<br>“Informe de 1 a 50 produtos.”<br>“Informe o código do cliente.”<br>“Informe o número do item que será a capa.”<br>“Informe o tipo e o nome para a busca. Para cidades, informe também a UF.”<br>“Informe um código inteiro positivo de produto.”<br>“Informe um código inteiro válido.”<br>“Informe um nome válido para a busca.”<br>“Informe um preço positivo na precisão da venda e datas válidas, com o início até o fim.”<br>“Informe uma data prevista válida.”<br>“Informe uma unidade do produto ou null para a unidade base.”<br>“Use um produto que não seja kit e uma unidade disponível para venda.” | `usuario` | Mostre a mensagem e as informações em `erro.campos` junto aos campos correspondentes. |
| `ENDERECO_INVALIDO` | Erro | 422 | `POST pedidos`, `POST revisoes` | O endereço não está disponível para entrega ou foi enviado num pedido de retirada. | “Endereço de entrega não encontrado no seu cadastro.”<br>“Pedido para retirada não leva endereço de entrega.” | `usuario` | Atualize as opções. Peça para selecionar um endereço de entrega ou remova-o na retirada. |
| `ENDERECO_REPETIDO` | Erro | 409 | `POST enderecos` | O endereço já existe no cadastro. | “Este endereço já está no seu cadastro.” | `usuario` | Volte às opções para escolher o endereço existente. |
| `ESTOQUE_SEM_CONFIGURACAO` | Erro | 422 | `POST pedidos` | Caso raro no envio. A configuração de estoque mudou entre a revisão do envio e a conclusão. | “Há itens sem configuração de estoque nesta empresa. Fale com seu fornecedor.” | `fornecedor` | Mostre a mensagem e registre para o fornecedor. Em condições normais, a revisão já bloqueia o item. |
| `FILTRO_INVALIDO` | Erro | 422 | `GET produtos`, `POST operadores/produtos/busca`, `POST produtos/busca` | Um filtro de catálogo está fora do formato, quantidade ou faixa permitidos. | “Filtro de catálogo inválido.” | `integracao` | Mostre a mensagem genérica e confira os detalhes em `erro.campos`. |
| `INDISPONIVEL` | Erro | 503 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `DELETE operadores/produtos/{id}/fotos/{item}`, `DELETE operadores/sessao`, `DELETE sessao`, `GET enderecos/referencias`, `GET grupos`, `GET historico-compras`, `GET loja`, `GET marcas`, `GET me`, `GET opcoes`, `GET operadores/clientes/{cliente}/precos-congelados`, `GET operadores/produtos/{id}/fotos`, `GET operadores/produtos/{id}/fotos/{item}`, `GET pedidos`, `GET pedidos/por-chave/{chave}`, `GET pedidos/{id}`, `GET produtos`, `GET produtos/{id}/fotos/{item}`, `POST acessos/links`, `POST acessos/senha`, `POST enderecos`, `POST operadores/clientes/consulta`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/busca`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `POST operadores/sessoes`, `POST pedidos`, `POST produtos/busca`, `POST revisoes`, `POST sessoes`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem`, `PUT senha` | A API está temporariamente indisponível. | “A API está indisponível no momento. Tente novamente em instantes.” | `tentar_de_novo` | Aguarde pelo menos 30 segundos. No envio, siga a matriz da chave. |
| `ITENS_INVALIDOS` | Erro | 422 | `POST pedidos`, `POST revisoes` | A lista está vazia, grande demais, tem item inválido ou o mesmo produto e unidade aparecem duas vezes. | “Envie de 1 a 100 itens no pedido.”<br>“Item inválido no pedido.”<br>“O mesmo produto aparece duas vezes na mesma unidade. Some as quantidades.” | `usuario` | Revise as linhas e some quantidades da mesma unidade. |
| `LICENCA_OPERADOR_INDISPONIVEL` | Erro | 423 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `DELETE operadores/produtos/{id}/fotos/{item}`, `GET operadores/clientes/{cliente}/precos-congelados`, `GET operadores/produtos/{id}/fotos`, `GET operadores/produtos/{id}/fotos/{item}`, `POST operadores/clientes/consulta`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/busca`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `POST operadores/sessoes`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem` | A licença não está disponível para o operador. | “Confira a disponibilidade da sua licença no G360.” | `fornecedor` | No painel, mostre a mensagem e registre a ocorrência. |
| `LIMITE_ENDERECOS` | Erro | 409 | `POST enderecos` | O cadastro já tem o máximo de endereços ativos. | “Seu cadastro já tem o máximo de endereços ativos.” | `usuario` | Ofereça um dos endereços existentes. |
| `LIMITE_FOTOS` | Erro | 422 | `POST operadores/produtos/{id}/fotos` | O produto atingiu o limite da galeria. | “Este produto já tem 12 fotos. Remova uma para incluir outra.” | `usuario` | Peça ao operador para remover uma foto antes de enviar outra. |
| `LINK_INVALIDO` | Erro | 422 | `POST acessos/senha` | O link é inválido, venceu, foi substituído ou já foi usado. | “O link é inválido ou expirou. Solicite um novo link.” | `usuario` | Ofereça a emissão de um novo link. |
| `LOJA_INDISPONIVEL` | Erro | 404 | `DELETE operadores/produtos/{id}/fotos/{item}`, `DELETE operadores/sessao`, `DELETE sessao`, `GET enderecos/referencias`, `GET grupos`, `GET historico-compras`, `GET loja`, `GET marcas`, `GET me`, `GET opcoes`, `GET operadores/produtos/{id}/fotos`, `GET operadores/produtos/{id}/fotos/{item}`, `GET pedidos`, `GET pedidos/por-chave/{chave}`, `GET pedidos/{id}`, `GET produtos`, `GET produtos/{id}/fotos/{item}`, `POST acessos/links`, `POST acessos/senha`, `POST enderecos`, `POST operadores/clientes/consulta`, `POST operadores/produtos/busca`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `POST operadores/sessoes`, `POST pedidos`, `POST produtos/busca`, `POST revisoes`, `POST sessoes`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem`, `PUT senha` | A loja não foi encontrada ou está indisponível para a API. | “Esta loja não está disponível. Fale com o seu fornecedor.” | `fornecedor` | Mostre a mensagem e registre a ocorrência. Confira a URL e a loja. Preserve a resposta neutra no link. |
| `MODALIDADE_INVALIDA` | Erro | 422 | `POST pedidos`, `POST revisoes` | A modalidade não é entrega ou retirada. | “Informe se o pedido é para entrega ou retirada.” | `usuario` | Peça para escolher entrega ou retirada. |
| `MUITAS_TENTATIVAS` | Erro | 429 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `DELETE operadores/produtos/{id}/fotos/{item}`, `DELETE operadores/sessao`, `DELETE sessao`, `GET enderecos/referencias`, `GET grupos`, `GET historico-compras`, `GET loja`, `GET marcas`, `GET me`, `GET opcoes`, `GET operadores/clientes/{cliente}/precos-congelados`, `GET operadores/produtos/{id}/fotos`, `GET operadores/produtos/{id}/fotos/{item}`, `GET pedidos`, `GET pedidos/por-chave/{chave}`, `GET pedidos/{id}`, `GET produtos`, `GET produtos/{id}/fotos/{item}`, `POST acessos/links`, `POST acessos/senha`, `POST enderecos`, `POST operadores/clientes/consulta`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/busca`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `POST operadores/sessoes`, `POST pedidos`, `POST produtos/busca`, `POST revisoes`, `POST sessoes`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem`, `PUT senha` | A requisição excedeu o limite geral ou um dos contadores de acesso. | “Muitas solicitações. Aguarde e tente de novo.”<br>“Muitas solicitações. Aguarde um instante e tente de novo.”<br>“Muitas tentativas de acesso. Aguarde e tente de novo, ou fale com o seu fornecedor.”<br>“Muitas tentativas de acesso. Aguarde e tente de novo.”<br>“Muitas tentativas. Aguarde um pouco e tente de novo.” | `tentar_de_novo` | Aumente a espera a cada nova recusa. No pedido de link, preserve a resposta neutra. |
| `NAO_ENCONTRADO` | Erro | 404 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `DELETE operadores/produtos/{id}/fotos/{item}`, `GET operadores/clientes/{cliente}/precos-congelados`, `GET operadores/produtos/{id}/fotos`, `GET operadores/produtos/{id}/fotos/{item}`, `GET pedidos/por-chave/{chave}`, `GET pedidos/{id}`, `GET produtos/{id}/fotos/{item}`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/{id}/fotos`, `POST pedidos`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem` | O recurso não foi localizado para a operação. | “Foto não encontrada.”<br>“Pedido não encontrado.”<br>“Preço congelado não encontrado.”<br>“Produto não encontrado.”<br>“Recurso não encontrado.” | `integracao` | Após timeout do envio, 404 na consulta por chave permite reenviar o mesmo corpo com a mesma chave. Nos demais casos, aplique o tratamento genérico. |
| `OBSERVACAO_INVALIDA` | Erro | 422 | `POST pedidos`, `POST revisoes` | A observação ultrapassa o limite de caracteres ou tem tipo inválido. | “A observação aceita até 400 caracteres.” | `usuario` | Peça para corrigir a observação no campo. |
| `OPERACAO_EM_ANDAMENTO` | Erro | 409 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `DELETE operadores/produtos/{id}/fotos/{item}`, `DELETE operadores/sessao`, `GET operadores/clientes/{cliente}/precos-congelados`, `GET operadores/produtos/{id}/fotos`, `GET operadores/produtos/{id}/fotos/{item}`, `POST acessos/links`, `POST acessos/senha`, `POST operadores/clientes/consulta`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/busca`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `POST operadores/sessoes`, `POST pedidos`, `POST sessoes`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem`, `PUT senha` | A API encontrou uma operação concorrente. | “Outra operação está alterando este cliente. Tente de novo.”<br>“Seu pedido ainda está sendo processado. Aguarde alguns segundos.” | `tentar_de_novo` | Aguarde pelo menos 3 segundos. Em envio de pedido, preserve corpo e chave. |
| `OPERADOR_LOGIN_INVALIDO` | Erro | 401 | `POST operadores/sessoes` | O operador não pôde iniciar a sessão. | “Usuário ou senha inválidos.” | `usuario` | Peça que confira usuário e senha. |
| `OPERADOR_SEM_ACESSO` | Erro | 403 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `DELETE operadores/produtos/{id}/fotos/{item}`, `GET operadores/clientes/{cliente}/precos-congelados`, `GET operadores/produtos/{id}/fotos`, `GET operadores/produtos/{id}/fotos/{item}`, `POST operadores/clientes/consulta`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/busca`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem` | A operação exige uma permissão que o operador não tem. | “Seu operador não tem acesso a esta operação de fotos do produto.”<br>“Seu operador não tem acesso para gerir preço congelado.”<br>“Seu operador não tem acesso à consulta de clientes.”<br>“Seu operador não tem acesso à consulta de produtos.” | `fornecedor` | No painel, mostre a mensagem e registre a ocorrência para conferir o acesso. |
| `ORIGEM_OPERADOR_NAO_PERMITIDA` | Erro | 403 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `DELETE operadores/produtos/{id}/fotos/{item}`, `DELETE operadores/sessao`, `GET operadores/clientes/{cliente}/precos-congelados`, `GET operadores/produtos/{id}/fotos`, `GET operadores/produtos/{id}/fotos/{item}`, `POST operadores/clientes/consulta`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/busca`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `POST operadores/sessoes`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem` | Uma chamada do painel chegou de origem não permitida. | “Origem não permitida nesta loja.” | `integracao` | No painel, mostre a mensagem genérica e confira a origem cadastrada. |
| `PAGINACAO_INVALIDA` | Erro | 422 | `GET pedidos`, `GET produtos`, `POST operadores/produtos/busca`, `POST produtos/busca` | A página ou o limite não respeita o formato ou a faixa da operação. | “Página ou limite inválidos.” | `integracao` | Mostre a mensagem genérica e corrija a paginação. |
| `PRECO_CONGELADO_ENCERRADO` | Erro | 409 | `PUT operadores/clientes/{cliente}/precos-congelados/{preco}` | Este preço já foi encerrado. | “Este preço já foi encerrado. Grave um novo para outra vigência.” | `usuario` | Grave um novo preço para o período que precisa negociar. |
| `PRECO_CONGELADO_INDISPONIVEL` | Erro | 409 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `POST operadores/clientes/{cliente}/precos-congelados`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}` | A base do G360 ainda não tem a estrutura de preço congelado. | “Atualize o G360 para gerir preços congelados.” | `fornecedor` | Peça ao fornecedor que atualize o G360 antes de gravar. |
| `REVISAO_ALTERADA` | Erro | 409 | `POST pedidos` | A revisão mudou ou a assinatura não corresponde mais ao carrinho. | “O pedido mudou desde a revisão. Confira o carrinho de novo.”<br>“O pedido mudou enquanto era enviado. Confira o carrinho.” | `usuario` | Revise de novo, apresente as mudanças e preserve a chave na mesma tentativa. |
| `REVISAO_BLOQUEADA` | Erro | 422 | `POST pedidos` | O envio encontrou pendências do carrinho em `erro.campos.pendencias`. | “O carrinho tem pendências. Revise antes de enviar.” | `usuario` | Mostre as pendências e trate cada uma pelo próprio responsável. |
| `SENHA_ATUAL_INCORRETA` | Erro | 422 | `PUT senha` | A senha atual não confere na troca autenticada. | “A senha atual não confere.” | `usuario` | Peça para conferir o campo ou iniciar a recuperação. |
| `SENHA_NOVA_INVALIDA` | Erro | 422 | `POST acessos/senha`, `PUT senha` | A nova senha não atende à regra. | “Use de 6 a 8 caracteres, sem espaços nem acentos, diferente do seu código de cliente.” | `usuario` | Mostre a regra junto ao campo de nova senha. |
| `SESSAO_INVALIDA` | Erro | 401 | `DELETE operadores/clientes/{cliente}/precos-congelados/{preco}`, `DELETE operadores/produtos/{id}/fotos/{item}`, `DELETE operadores/sessao`, `DELETE sessao`, `GET enderecos/referencias`, `GET grupos`, `GET historico-compras`, `GET marcas`, `GET me`, `GET opcoes`, `GET operadores/clientes/{cliente}/precos-congelados`, `GET operadores/produtos/{id}/fotos`, `GET operadores/produtos/{id}/fotos/{item}`, `GET pedidos`, `GET pedidos/por-chave/{chave}`, `GET pedidos/{id}`, `GET produtos`, `GET produtos/{id}/fotos/{item}`, `POST enderecos`, `POST operadores/clientes/consulta`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/busca`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `POST pedidos`, `POST produtos/busca`, `POST revisoes`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem`, `PUT senha` | O token está ausente, inválido ou perdeu a validade. | “Sua sessão terminou. Entre novamente.” | `usuario` | Solicite novo login. |
| `SOLICITACAO_INVALIDA` | Erro | 400 | `POST acessos/links`, `POST acessos/senha`, `POST enderecos`, `POST operadores/clientes/consulta`, `POST operadores/clientes/{cliente}/precos-congelados`, `POST operadores/produtos/busca`, `POST operadores/produtos/precos`, `POST operadores/produtos/{id}/fotos`, `POST operadores/sessoes`, `POST pedidos`, `POST produtos/busca`, `POST revisoes`, `POST sessoes`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}`, `PUT operadores/produtos/{id}/fotos/capa`, `PUT operadores/produtos/{id}/fotos/ordem`, `PUT senha` | O JSON ou o formato da solicitação não foi aceito. | “Solicitação inválida.” | `integracao` | Mostre a mensagem genérica e confira a requisição. |
| `TROCA_DE_SENHA_DESLIGADA` | Erro | 403 | `POST acessos/links`, `POST acessos/senha`, `PUT senha` | A loja não libera a definição ou troca de senha pela API. | “A senha é definida pelo seu fornecedor. Fale com ele para alterar.” | `fornecedor` | Registre a ocorrência. Na emissão do link, preserve a resposta neutra. |
| `VENDA_EM_ANDAMENTO` | Erro | 409 | `POST pedidos` | Uma venda do G360 em andamento reservou o saldo de um produto do carrinho e o que sobra não cobre o pedido, ou está gravando a reserva naquele instante. | “Há uma venda em andamento com este cliente ou produto. Aguarde alguns segundos e envie de novo, com a mesma chave de envio.” | `tentar_de_novo` | Aguarde pelo menos 3 segundos e reenvie o mesmo corpo com a mesma chave. |
| `VIGENCIA_SOBREPOSTA` | Erro | 409 | `POST operadores/clientes/{cliente}/precos-congelados`, `PUT operadores/clientes/{cliente}/precos-congelados/{preco}` | Outro preço do mesmo cliente, produto e unidade ocupa parte do período. | “Já existe preço congelado nesta vigência para o cliente, produto e unidade.” | `usuario` | Confira os preços existentes e escolha datas sem sobreposição. |
| `CADASTRO_BLOQUEADO` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | O cadastro está impedido de comprar. | “Há uma pendência no seu cadastro. Fale com o seu fornecedor para liberar novos pedidos.” | `fornecedor` | Mostre a pendência e registre para o fornecedor. |
| `CADASTRO_SEM_ENDERECO` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | A entrega não tem um endereço disponível para o cadastro. | “Seu cadastro não tem endereço de entrega. Peça ao fornecedor para incluir ou escolha retirada.” | `fornecedor` | Ofereça retirada e registre a pendência para o fornecedor. |
| `CONDICAO_CREDITO_BLOQUEADA` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | A regra comercial bloqueia a condição escolhida. | “Esta condição de pagamento não está disponível. Escolha outra ou fale com seu fornecedor.” | `usuario` | Ofereça outra condição. Se nenhuma servir, oriente a falar com o fornecedor. |
| `CONDICAO_INVALIDA` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | A condição escolhida exige configuração do fornecedor. | “Esta condição exige uma configuração do fornecedor. Escolha outra condição.” | `fornecedor` | Ofereça outra condição e registre a pendência para o fornecedor. |
| `CREDITO_INDISPONIVEL` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | A API não conseguiu conferir as condições de crédito do pedido. | “Não foi possível verificar as condições do pedido. Tente novamente.” | `tentar_de_novo` | Aguarde e revise novamente. |
| `DATA_PREVISTA_INVALIDA` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | A data prevista é anterior a hoje. | “A data prevista deve ser de hoje em diante.” | `usuario` | Recalcule a previsão e revise de novo. |
| `DATA_PREVISTA_OBRIGATORIA` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | A loja exige uma previsão de entrega e ela não foi informada. | “Informe a data prevista do pedido.” | `usuario` | Calcule e informe a previsão antes de revisar. |
| `ESCOLHA_O_PAGAMENTO` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | A revisão exige condição de pagamento, mas nenhuma foi escolhida. | “Escolha a condição de pagamento.” | `usuario` | Mostre as condições e peça para escolher uma. |
| `FRETE_A_COMBINAR` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | O frete da entrega está indefinido. | “O fornecedor ainda precisa definir o frete para este endereço.” | `fornecedor` | Mostre a pendência e registre para o fornecedor. Ofereça retirada quando aplicável. |
| `ITEM_BLOQUEADO` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | A revisão não conseguiu vender o item, a unidade ou a quantidade solicitada. Quando só falta o que uma venda do G360 em andamento reservou, o envio responde 409 VENDA_EM_ANDAMENTO. | “Há uma venda em andamento com este produto no fornecedor. Tente de novo em instantes.”<br>“Quantidade maior que a disponível.”<br>“{nome do produto}: Há uma venda em andamento com este produto no fornecedor. Tente de novo em instantes.”<br>“{nome do produto}: Kit com cadastro incompleto. Consulte o seu vendedor.”<br>“{nome do produto}: Kit com item indisponível. Consulte o seu vendedor.”<br>“{nome do produto}: Kit é vendido só na unidade padrão.”<br>“{nome do produto}: Preço sob consulta. Fale com o seu vendedor.”<br>“{nome do produto}: Produto indisponível para venda.”<br>“{nome do produto}: Quantidade maior que a disponível. Reduza a quantidade.”<br>“{nome do produto}: Quantidade pequena demais para este produto.”<br>“{nome do produto}: Unidade não disponível para este produto.” | `usuario` | Mostre o motivo junto ao item. Permita ajustar a quantidade, escolher outra unidade ou remover o item. Na venda em andamento, tente de novo em instantes. |
| `LOJA_SEM_CONFIGURACAO` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | A loja ainda não tem a configuração ou a atualização exigida pelo pedido. | “A natureza do pedido precisa ser configurada pelo fornecedor.”<br>“A previsão precisa de uma atualização do fornecedor.”<br>“O fornecedor ainda não concluiu a configuração da loja. Avise o seu vendedor.”<br>“O fornecedor precisa atualizar a base para concluir pedidos.”<br>“O fornecedor precisa habilitar a cobrança de frete na natureza do pedido.” | `fornecedor` | Mostre a pendência e registre para o fornecedor. |
| `PARCELA_MINIMA` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | Uma parcela calculada fica abaixo do mínimo. | “Nesta condição a parcela mínima é de R$ {valor}. Escolha outra condição ou aumente o pedido.”<br>“O valor do pedido é pequeno demais para esta condição de pagamento. Escolha outra condição.” | `usuario` | Ofereça outra condição ou ajuste do carrinho. |
| `PEDIDO_MINIMO` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | O total do pedido fica abaixo do mínimo da condição. | “Esta condição de pagamento exige pedido mínimo de R$ {valor}.” | `usuario` | Permita trocar a condição ou ajustar o carrinho. |
| `PRODUTO_INDISPONIVEL` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | O produto do carrinho deixou de estar disponível para o comprador. | “Um produto do carrinho não está mais disponível. Remova-o para continuar.” | `usuario` | Peça para remover ou substituir o produto e revisar de novo. |
| `SEM_CONDICAO_DE_PAGAMENTO` | Pendência | 200 com `pode_enviar` falso. 422 `REVISAO_BLOQUEADA` no envio. | `POST revisoes`, `POST pedidos` | O comprador não tem condição de pagamento disponível para o pedido. | “Não há condição de pagamento liberada para o seu cadastro. Fale com o seu fornecedor.” | `fornecedor` | Mostre a pendência e registre para o fornecedor. |
