Enviar un fax | MultiTEL

Antes de enviar

Use un número de remitente que esté autorizado a presentar y envíe el fax a un destinatario que lo espere. Esta solicitud genera una transmisión real que puede conllevar un cargo. Use un documento PDF o TIFF preparado para que la detección de páginas sea lo más predecible posible. Una respuesta que indique que el fax está en cola confirma la aceptación, no la entrega.

Use una cuenta habilitada de la API de MultiTEL. Envíe credenciales HTTP Basic si la cuenta usa contraseña, o un token Bearer si la cuenta usa tokens. Los permisos de la cuenta y las restricciones de IP siguen siendo aplicables. No use credenciales internas del proceso de trabajo.

Subir el 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 de la solicitud
Campo	Obligatorio	Significado
`from_number`	Sí	Su número de remitente autorizado. Use el formato internacional, comenzando por + y el código de país.
`to_number`	Sí	El número de fax de destino, en formato internacional.
`fax_file`	Sí, para solicitudes multiparte	El documento subido. Deje que curl establezca el Content-Type y el delimitador de la solicitud multiparte.
`webhook_url`	No	URL opcional de notificación de retorno mediante HTTP o HTTPS; es preferible usar HTTPS. El contenido de estas notificaciones y las garantías de entrega siguen en revisión: consulte periódicamente fax_status para seguir el procedimiento documentado de consulta de estado.

También se acepta JSON con Content-Type: application/json, los mismos campos de números y el campo opcional webhook_url, además de file_name y file_b64. file_b64 contiene los bytes del documento codificados estrictamente en Base64, sin el prefijo data:. Un fax_file válido enviado en una solicitud multiparte tiene prioridad. Esta API no permite obtener archivos a partir de una URL.

Límites de documentos y envíos

La aplicación acepta como máximo 15,728,640 bytes de documento decodificados (15 MiB), con las extensiones pdf, tif, tiff, jpg, jpeg, png, doc, docx o txt. Que una extensión esté permitida no garantiza que el servicio pueda contar o convertir las páginas. Los límites de tamaño de las solicitudes impuestos por la infraestructura pueden ser inferiores, y Base64 aumenta el tamaño de la solicitud.

Por cuenta, la aplicación actual permite un trabajo en cola o en proceso de envío al mismo destino, un máximo de cinco envíos a ese destino durante la hora anterior y un máximo de 50 envíos en total durante la hora anterior. Una respuesta por límite de frecuencia usa el código 429 de la API. Espere antes de volver a intentarlo; no intente eludir los límites.

Conservar el identificador del trabajo

Lea tanto el resultado HTTP como el campo status.code de JSON. Los errores en JSON pueden llegar con HTTP 200. Una respuesta JSON correcta contiene status y response; los ejemplos usan datos ficticios.

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

Consulte periódicamente fax_status usando response.job_id. Si se pierde la respuesta al envío, revise la bandeja de salida del portal antes de volver a enviar: las solicitudes repetidas pueden generar transmisiones independientes. Este manejador no expone ningún parámetro de idempotencia para el cliente.

Errores y comprobaciones de saldo

Los códigos de la API incluyen 400 si faltan campos, la URL de notificación de retorno no es válida, se rechaza el documento o falla la detección de páginas; 401 si falta la autenticación; 402 cuando el coste estimado del fax, sumado a las estimaciones de los trabajos en cola o en proceso de envío, supera el saldo disponible de la cuenta; 429 para los límites de frecuencia; y 500 si falla la preparación del envío. Lea status.msg para conocer el motivo concreto.

La cola registra un coste estimado antes de la transmisión. No interprete la aceptación, la comprobación de saldo ni esta estimación como confirmación de que se haya efectuado un cargo. La facturación final y los detalles de las notificaciones de retorno siguen sujetos a verificación.