Enviar um fax | MultiTEL

Antes de enviar

Use um número de remetente que você tenha autorização para apresentar e envie o fax a um destinatário que o esteja esperando. Esta solicitação cria uma transmissão real que pode gerar cobrança. Use um documento PDF ou TIFF preparado para tornar a detecção de páginas o mais previsível possível. Uma resposta que indique que o fax está na fila confirma a aceitação, não a entrega.

Use uma conta habilitada da API da MultiTEL. Envie credenciais HTTP Basic para uma conta com senha, ou um token Bearer para uma conta com token. As permissões da conta e as restrições de IP continuam se aplicando. Não use credenciais internas do processo de trabalho.

Carregar o documento

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --form-string from_number=+12125550123 \
  --form-string to_number=+12125550124 \
  --form fax_file=@./document.pdf \
  https://api.multitel.net/v3/send_fax

Campos da solicitação
Campo	Obrigatório	Significado
`from_number`	Sim	Seu número de remetente autorizado. Use o formato internacional, começando com + e o código do país.
`to_number`	Sim	O número de fax de destino, no formato internacional.
`fax_file`	Sim, para solicitações multiparte	O documento carregado. Deixe que curl defina o Content-Type e o delimitador da solicitação multiparte.
`webhook_url`	Não	URL opcional para notificações de retorno por HTTP ou HTTPS; é preferível usar HTTPS. O conteúdo dessas notificações e as garantias de entrega ainda estão em revisão: consulte periodicamente fax_status para seguir o procedimento documentado de consulta de estado.

Também é aceito JSON com Content-Type: application/json, os mesmos campos de números e o campo opcional webhook_url, além de file_name e file_b64. file_b64 contém os bytes do documento codificados estritamente em Base64, sem o prefixo data:. Um fax_file válido enviado em uma solicitação multiparte tem precedência. Esta API não permite obter arquivos a partir de uma URL.

Limites de documentos e envios

A aplicação aceita no máximo 15,728,640 bytes de documento decodificados (15 MiB), com as extensões pdf, tif, tiff, jpg, jpeg, png, doc, docx ou txt. Uma extensão permitida não garante que o serviço consiga contar ou converter as páginas. Os limites de tamanho das solicitações impostos pela infraestrutura podem ser menores, e Base64 aumenta o tamanho da solicitação.

Por conta, a aplicação atual permite um trabalho na fila ou em envio para o mesmo destino, no máximo cinco envios para esse destino na hora anterior e no máximo 50 envios no total na hora anterior. Uma resposta por limite de frequência usa o código 429 da API. Aguarde antes de tentar novamente; não tente contornar os limites.

Guardar o identificador do trabalho

Leia tanto o resultado HTTP quanto o campo status.code de JSON. Erros em JSON podem chegar com HTTP 200. Uma resposta JSON bem-sucedida contém status e response; os exemplos usam dados fictícios.

{
  "status": {
    "code": 200,
    "msg": "Fax queued"
  },
  "response": {
    "job_id": "0123456789abcdef0123456789abcdef"
  }
}

Consulte periodicamente fax_status usando response.job_id. Se a resposta ao envio for perdida, verifique a caixa de saída do portal antes de enviar novamente: solicitações repetidas podem criar transmissões separadas. Este manipulador não expõe nenhum parâmetro de idempotência para o cliente.

Erros e verificações de saldo

Os códigos da API incluem 400 para campos ausentes, URL de notificação de retorno inválida, documento rejeitado ou falha na detecção de páginas; 401 para ausência de autenticação; 402 quando o custo estimado do fax, somado às estimativas dos trabalhos na fila ou em envio, excede o saldo disponível da conta; 429 para limites de frequência; e 500 para uma falha na preparação do envio. Leia status.msg para saber o motivo específico.

A fila registra um custo estimado antes da transmissão. Não interprete a aceitação, a verificação de saldo ou essa estimativa como confirmação de que uma cobrança foi efetivada. O faturamento final e os detalhes das notificações de retorno continuam sujeitos a verificação.