# Oratrix API - Envio em Lote ## Status Documentacao parcial baseada na parte enviada para o projeto Wezapp Shots. Este grupo e prioridade alta para o **Wezapp Shots**, pois esta diretamente relacionado aos disparos em massa. ## Base URL ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID} ``` ## Autenticacao ```http Authorization: Bearer {token} ``` ## Endpoints do grupo Total documentado nesta parte: 8 endpoints. --- ## 1. Disparo rapido para lista de numeros sem criar tickets ```http POST /bulkFastMessage ``` Nome na documentacao Oratrix: ```text BulkFastMessage ``` Descricao: Disparo rapido para lista de numeros sem criar tickets. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/bulkFastMessage ``` Body: ```text Form Data ``` Campos: | Campo | Tipo | Obrigatorio | Descricao | |---|---|---:|---| | contacts | JSON array | Sim | Lista de contatos no formato `[{"number":"5511999999999","name":"Nome"}]` | | message | Texto | Sim | Texto da mensagem | | whatsappId | ID | Sim | ID da sessao | | media | Arquivo | Nao | Arquivo opcional | Observacao para Wezapp Shots: Este endpoint parece ser candidato para disparos de alto volume quando nao for necessario criar ticket para cada contato. Deve ser testado com controle de limite, retorno e falhas por item. --- ## 2. Disparo em lote criando tickets ```http POST /bulkSendMessage ``` Nome na documentacao Oratrix: ```text BulkSendMessage ``` Descricao: Disparo em lote criando tickets para cada contato. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/bulkSendMessage ``` Body: ```text Form Data ``` Campos: | Campo | Tipo | Obrigatorio | Descricao | |---|---|---:|---| | contacts | JSON array | Sim | Lista de contatos no formato `[{"number":"5511999999999","name":"Nome"}]` | | message | Texto | Sim | Texto da mensagem | | whatsappId | ID | Sim | ID da sessao | | media | Arquivo | Nao | Arquivo opcional | Observacao para Wezapp Shots: Este endpoint cria tickets e pode gerar mais carga operacional no Oratrix. Deve ser usado apenas quando o fluxo exigir atendimento/conversa vinculada. --- ## 3. Disparo em lote com variaveis personalizadas ```http POST /bulkSendMessageWithVariable ``` Nome na documentacao Oratrix: ```text BulkSendMessageWithVariable ``` Descricao: Disparo em lote com variaveis personalizadas por contato. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/bulkSendMessageWithVariable ``` Body: ```text Form Data ``` Campos: | Campo | Tipo | Obrigatorio | Descricao | |---|---|---:|---| | contacts | JSON array | Sim | Lista de contatos com variaveis, no formato `[{"number":"5511999999999","name":"Nome","variables":{"campo":"valor"}}]` | | message | Texto | Sim | Mensagem com `{variavel}` | | whatsappId | ID | Sim | ID da sessao | Observacao para Wezapp Shots: Este endpoint e candidato para campanhas personalizadas. O Wezapp deve gerar as variaveis por contato a partir da base interna e registrar o payload enviado. --- ## 4. Disparo individual ```http POST /bulkIndividual ``` Nome na documentacao Oratrix: ```text BulkIndividual ``` Descricao: Disparo individual de mensagem a um unico numero. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/bulkIndividual ``` Body: ```text Form Data ``` Campos: | Campo | Tipo | Obrigatorio | Descricao | |---|---|---:|---| | number | Texto | Sim | Numero no formato internacional, exemplo `5511999999999` | | message | Texto | Sim | Texto da mensagem | | whatsappId | ID | Sim | ID da sessao | | media | Arquivo | Nao | Arquivo opcional | Observacao para Wezapp Shots: Pode ser usado em testes, reenvios pontuais ou disparos unitarios. Nao deve substituir o fluxo de fila interna para campanhas grandes. --- ## 5. Listar registros de disparos em lote ```http GET /bulkDispatch/list ``` Nome na documentacao Oratrix: ```text BulkDispatchList ``` Descricao: Listar registros de disparos em lote. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/bulkDispatch/list ``` Query params: | Parametro | Obrigatorio | Descricao | Exemplo | |---|---:|---|---| | page | Sim | Numero da pagina | 1 | | status | Nao | `pending`, `running`, `completed`, `cancelled` | running | --- ## 6. Exibir disparo em lote ```http GET /bulkDispatch/show/:id ``` Nome na documentacao Oratrix: ```text BulkDispatchShow ``` Descricao: Exibir registro de um disparo em lote pelo ID. --- ## 7. Atualizar status de disparo em lote ```http POST /bulkDispatch/update/:id ``` Nome na documentacao Oratrix: ```text BulkDispatchUpdate ``` Descricao: Atualizar status de um disparo em lote. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/bulkDispatch/update/:id ``` Body JSON: ```json { "status": "cancelled", "cancellationReason": "Motivo do cancelamento" } ``` --- ## 8. Incrementar progresso de disparo em lote ```http POST /bulkDispatch/incrementProgress/:id ``` Nome na documentacao Oratrix: ```text BulkDispatchIncrementProgress ``` Descricao: Incrementar o progresso de um disparo em lote. URL completa: ```text https://api-pro1.oratrixchat.com.br/v2/api/external/{ApiID}/bulkDispatch/incrementProgress/:id ``` Body JSON: ```json { "success": true, "error": null } ``` ## Mapeamento sugerido com Wezapp Shots | Wezapp Shots | Oratrix | |---|---| | `wezapp_dispatch_jobs.id` | ID interno do job no Wezapp | | campo futuro `external_bulk_dispatch_id` | ID de bulkDispatch no Oratrix | | `wezapp_dispatch_items` | Contatos enviados no lote | | `wezapp_channels.external_channel_id` | `whatsappId` | | `wezapp_dispatch_logs.request_payload_json` | Form data enviado ao Oratrix | | `wezapp_dispatch_logs.response_payload_json` | Resposta retornada pelo Oratrix | ## Decisao inicial recomendada para o Shots Para a primeira versao, avaliar dois caminhos: ### Caminho A - Lote delegado ao Oratrix O Wezapp cria um lote interno e envia varios contatos para um endpoint bulk do Oratrix. Vantagens: - Menos chamadas HTTP. - Execucao mais simples no Wezapp. - Possivel uso dos controles internos do Oratrix. Riscos: - Menos controle por item no Wezapp. - Precisa entender retorno por contato. - Pode dificultar consumo exato de shots em caso de falha parcial. ### Caminho B - Fila controlada pelo Wezapp O Wezapp controla cada item e chama envio individual ou pequenos lotes por canal. Vantagens: - Maior controle de shots. - Melhor auditoria por contato. - Melhor distribuicao multicanal. - Melhor retomada em caso de erro. Riscos: - Mais chamadas HTTP. - Precisa de fila/worker bem implementado. Recomendacao atual: Para bases grandes e chipeira digital, o **Caminho B** tende a ser mais seguro arquiteturalmente, mesmo que use endpoints bulk em pequenos blocos. O consumo de shots deve continuar controlado no Wezapp. ## Pendencias tecnicas para validar - Limite maximo de contatos no campo `contacts`. - Formato exato esperado para `contacts` em form-data. - Se o retorno informa sucesso/falha por contato. - Se o retorno cria e retorna `bulkDispatchId`. - Se `bulkFastMessage` gera algum historico consultavel depois. - Diferenca real entre `bulkFastMessage` e `bulkSendMessage` alem da criacao de tickets. - Como a API trata media em arquivo. - Tamanho maximo de arquivo em `media`. - Se `bulkSendMessageWithVariable` aceita media. - Como funciona `incrementProgress` e se deve ser chamado pelo cliente externo ou pelo proprio Oratrix. - Se `bulkDispatch/update` pode cancelar disparos em andamento. ## Regras recomendadas para o Wezapp Shots 1. Nenhum envio em lote deve ocorrer sem saldo de shots. 2. Nenhum envio em lote deve ocorrer sem job interno. 3. Todo envio deve registrar request e response. 4. Todo consumo de shot deve ficar no ledger interno. 5. Falha parcial nao deve consumir shot sem regra clara. 6. A distribuicao entre canais deve ser controlada pelo Wezapp. 7. Endpoints bulk podem ser usados em blocos, nao necessariamente com a base inteira de uma vez. 8. O painel do Wezapp deve mostrar status interno, mesmo quando houver status externo do Oratrix.