Destino REST: envio em lote e confirmação pela fila

Vale para qualquer destino REST que receba lista de registros e/ou processe depois do envio (APIs de cadastro e de venda em lote, como o Meu Cliente). Tudo se configura na conexão de destino, sem código.

Envio em lote

• Forma do corpo JSON — Objeto (uma mensagem por envio) ou Array JSON (lista de objetos). O lote exige Array JSON.
• Registros por envio (lote) — de 1 a 1000. Cada registro é um item do array enviado; ex.: 500. Com 1 (o padrão), cada mensagem sai sozinha, como sempre. Com 500, o Lefia junta mensagens da mesma integração num POST só até somar 500 registros, na ordem em que chegaram; a mensagem que já leva vários registros (um documento que vira N registros) conta todos eles e entra inteira. O mesmo número limita quantos registros um documento põe num corpo só.
• Espera para completar o lote (segundos) — o lote incompleto espera este tempo por mais mensagens antes de sair (padrão 30).

Cada mensagem passa pelos portões de sempre (spec, conciliação) antes de entrar no lote. No Monitor, cada uma mostra o lote em que saiu e o id do processo que o destino devolveu. Não combina com o upsert por chave externa (o lote não tem uma chave só).

Se o lote falhar, a falha aparece em cada mensagem dele, com a causa e o número do lote. Erro temporário (5xx, rede, 429) reenvia o mesmo lote pela política de retry da integração, com a mesma chave de idempotência; enquanto isso, os lotes mais novos esperam (a ordem nunca se inverte). No Monitor: Reprocessar lote reenvia o lote inteiro; Reprocessar tira só aquela mensagem do lote e ela vai no próximo.

Idempotência: cada lote leva uma Idempotency-Key própria, a mesma em todo reenvio das mesmas mensagens (e nova se a composição do lote mudou). Se a conexão cair depois de o destino aceitar o POST e antes de o Lefia gravar o id do processo, o reenvio só não duplica se o destino honrar a Idempotency-Key (ou substituir pela chave de negócio, como o Meu Cliente faz por loja e data).

Confirmação pela fila (passo guiado)

Para o destino que aceita o envio, devolve um id de processo e processa depois:

1. Como o destino confirma — escolha Consultar a fila do destino pelo id do processo.
2. Onde consultar — caminho no servidor do destino com {id}, ex.: /api/v2/fila/{id}.
3. Onde estão o id e o status — caminho do id na resposta do envio (vazio = automático; a resposta que é só o id em texto também vale), do status e do motivo do erro na consulta.
4. O que cada status significa — listas de sucesso, falha e processando. Só um status da lista de sucesso conta como aceito. Um status fora das três listas nunca vira aceito: escolha entre seguir aguardando, com aviso, até o prazo ou erro na hora.
5. Intervalo e prazo — de quanto em quanto tempo consultar e até quando; passado o prazo, a mensagem vai para erro com o último status visto.
6. Testar — informe um id de processo real: o Lefia consulta com a autenticação da conexão e mostra o HTTP, o status lido e o que faria com a resposta. Nada é gravado.

Com envio em lote, uma consulta pelo id do lote confirma (ou recusa, com o motivo) todas as mensagens dele.