Maggu API V3 — Cookbook

Appearance

Boas Práticas ​

Resumo das regras operacionais que garantem uma integração confiável e previsível com a Maggu.

Polling de Comandos ​

Intervalo fixo de 1s — sem backoff

Consulte GET /v3/comandos/pendentes a cada 1s. Em caso de erro HTTP 5xx da Maggu, não aplique backoff exponencial — aguarde o próximo ciclo normal.

Motivo: o backoff pode atrasar a execução de comandos urgentes por minutos. A Maggu é dimensionada para absorver o volume fixo de polling de comandos.

python
while True:
    executar()
    time.sleep(1)  # sempre 1 segundo

Processamento de comandos ​

Ordenar do mais antigo para o mais recente

Processe os comandos em ordem crescente de criadoEm. Isso garante consistência temporal — ex.: enviar vendas antes de enviar contra-provas do mesmo dia.

python
for cmd in sorted(comandos, key=lambda c: c["criadoEm"]):
    processar(cmd)

Confirmar ou reportar falha individualmente

Nunca confirme um lote de comandos de uma vez. Cada id deve ter sua própria chamada a /completou ou /falhou.

python
# Correto: um por vez
session.post("api/v3/comandos/completou", json={"id": cmd["id"]})

# Incorreto: não existe endpoint de confirmação em lote

Envio em lote ​

Máximo de 400 registros por requisição

Todos os endpoints /registrar-em-lote aceitam no máximo 400 itens por chamada. Para volumes maiores, quebre em lotes:

python
def chunk(lst, n):
    for i in range(0, len(lst), n):
        yield lst[i:i+n]

for lote in chunk(registros, 400):
    session.post("api/v3/usuarios/registrar-em-lote", json={"comandoId": cmd["id"], "conteudo": lote})
# Confirmar o comando SOMENTE aqui, após todos os lotes

WARNING

Confirme o comando somente após todos os lotes serem enviados com sucesso. Se um lote falhar, o comando inteiro ainda não foi concluído.

Idempotência ​

Reenvios são seguros — não duplicam dados

Todos os endpoints de lote da Maggu são idempotentes pela chave codigoExterno (ou ean para produtos, cpfCnpj para clientes). Reprocessar o mesmo comando não cria registros duplicados.

Ainda assim, mantenha controle local para evitar reprocessar comandos desnecessariamente:

python
estado_comandos[cmd["id"]] = "pendente"

Retry local ​

Até 3 tentativas antes de reportar falha

Se o ERP falhar ao acessar o banco local (timeout, lock, etc.), tente novamente até 3 vezes antes de chamar /falhou:

python
ultimo_erro = None

for i in range(3):
    try:
        executar_operacao_local()
        break  # sucesso
    except Exception as e:
        ultimo_erro = e
        time.sleep(0.2)  # espera progressiva só no retry local

if ultimo_erro:
    raise ultimo_erro  # propaga para /falhou

O retry com espera progressiva aplica-se apenas ao acesso local (banco de dados do ERP). Não aplique backoff nas chamadas à API Maggu.

Tratamento de erros da API Maggu ​

Código recebidoAção recomendada
202 AcceptedLote aceito — próximo lote ou confirmar comando
204 No ContentOperação concluída — confirmar comando
400 Bad RequestDados inválidos — reportar falha com o corpo do erro como motivo
403 ForbiddenToken inválido — verificar configuração, não tentar novamente automaticamente
404 Not FoundComando não encontrado — ignorar (pode ter expirado)
5xxFalha temporária — aguardar próximo ciclo de polling de comandos, não incrementar falhas

Adicionando um novo tipo de comando ​

  1. Crie uma função que recebe cmd e implementa a lógica local + chamada à API Maggu.
  2. Adicione um case na função processar.
python
def novo_comando(cmd):
    # lógica local...
    # chamada à API Maggu...
    pass

# Em processar():
case "NOVO_TIPO":
    novo_comando(cmd)