API fax

Carica un documento

POST /api/v1/documents

Richiedi uno slot di caricamento, poi invia i byte del file con PUT a upload_url. I byte vanno direttamente nell'archivio. Questa richiesta controlla solo i dati dichiarati sul file. Il fax viene creato in seguito usando id dello slot. Non esistono richieste per scaricare documenti o elencarli.

checksum è l'MD5 del file codificato in base64, lo stesso valore dell'intestazione Content-MD5. byte_size è la dimensione esatta in byte. content_type è uno tra application/pdf, image/jpeg, image/png, image/webp, image/heic e image/heif. L'ID dello slot è valido per 1 ora. L'URL di caricamento è valido per 5 minuti. L'archivio rifiuta un file la cui dimensione o MD5 non corrisponda allo slot.

openssl dgst -md5 -binary referral.pdf | openssl base64
wc -c referral.pdf | awk '{print $1}'

curl -s https://eu.faxette.com/api/v1/documents \
  -H "Content-Type: application/json" \
  -d '{"filename":"referral.pdf","byte_size":248113,"checksum":"gbgEgwqIGW9JMTqqgYW+xw==","content_type":"application/pdf"}'

201, con lo slot.

{
  "data": {
    "type": "Document",
    "id": "SIGNED_ID",
    "upload_url": "https://example.r2.cloudflarestorage.com/faxette/...",
    "upload_headers": {
      "Content-Type": "application/pdf",
      "Content-MD5": "gbgEgwqIGW9JMTqqgYW+xw==",
      "Content-Disposition": "inline; filename=\"referral.pdf\"; filename*=UTF-8''referral.pdf"
    }
  }
}

Invia i byte grezzi con PUT a upload_url, includendo tutte le intestazioni in upload_headers. Copia i valori dalla risposta. $UPLOAD_URL qui sotto rappresenta upload_url.

curl -X PUT --data-binary @referral.pdf \
  -H "Content-Type: application/pdf" \
  -H "Content-MD5: gbgEgwqIGW9JMTqqgYW+xw==" \
  -H "Content-Disposition: inline; filename=\"referral.pdf\"; filename*=UTF-8''referral.pdf" \
  "$UPLOAD_URL"

Crea un fax

POST /api/v1/faxes

Creare un fax non addebita una carta. La risposta include token una sola volta. Salvalo: non verrà restituito di nuovo. Interroga GET /api/v1/faxes/:id finché status è documents_ready e checkout_available è true, poi indirizza la persona a status_url. Lì controlla numero di fax, documenti e prezzo e paga. Il pagamento parte dal pulsante Paga su quella pagina. Un link che avviasse il pagamento verrebbe aperto dalle anteprime delle app di chat, quindi non esiste un endpoint per il pagamento.

Inviare questa richiesta due volte crea due fax. Non esiste una chiave di idempotenza.

Con gli ID dei documenti

documents contiene gli ID degli slot, nell'ordine di invio. Un ID già associato a un fax non può essere usato per un altro. Carica di nuovo il file.

curl -s https://eu.faxette.com/api/v1/faxes \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","fax_number":"+442079460958","documents":["SIGNED_ID"]}'

Con i file in un'unica richiesta

Invia documents[] come file multipart, nell'ordine del fax. I byte passano attraverso questo server, quindi per un file grande è preferibile uno slot di caricamento. Il tipo di contenuto deve essere uno dei tipi elencati sopra. type= lo imposta quando il nome del file non lo determina.

curl -s https://eu.faxette.com/api/v1/faxes \
  -F "[email protected]" \
  -F "fax_number=+442079460958" \
  -F "documents[][email protected];type=application/pdf" \
  -F "documents[][email protected];type=image/jpeg"

Una bozza vuota

Ometti documents. Nella risposta, status è draft e la persona aggiunge i file sulla pagina di stato.

curl -s https://eu.faxette.com/api/v1/faxes \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","fax_number":"+442079460958"}'

Campi

201, con il fax e il suo token. Gli altri campi sono null finché il fax non avanza.

{
  "data": {
    "type": "Fax",
    "id": "k3n8q0w1x4y7",
    "status": "processing_documents",
    "fax_number": "+442079460958",
    "page_count": null,
    "retries_remaining": 2,
    "next_attempt_at": null,
    "resend_by": null,
    "updated_at": "2026-10-27T16:04:00.000Z",
    "status_url": "https://eu.faxette.com/f/k3n8q0w1x4y7?token=exampletoken",
    "checkout_available": false,
    "price": null,
    "payment": null,
    "attempt": 1,
    "max_attempts": 3,
    "document_errors": [],
    "failure_reason": null,
    "token": "exampletoken"
  }
}

Dopo il conteggio delle pagine, questi campi appaiono così. Su questo sito currency è eur.

{
  "status": "documents_ready",
  "page_count": 3,
  "checkout_available": true,
  "price": { "amount_cents": 500, "currency": "eur" }
}

Leggi un fax

GET /api/v1/faxes/:id?token=

Restituisce lo stesso oggetto della creazione, senza token. La risposta non include mai documenti o nomi dei file. Interrogalo mentre status è processing_documents. document_errors indica quale file correggere in base alla sua posizione nel fax, a partire da 1.

curl -s "https://eu.faxette.com/api/v1/faxes/k3n8q0w1x4y7?token=exampletoken"

{
  "document_errors": [
    {
      "reason": "password_protected",
      "position": 2,
      "message": "Document 2 is locked with a password. Open it, save or print it as a new PDF without the password, then upload that copy."
    }
  ]
}

Sostituisci i documenti

PATCH /api/v1/faxes/:id/documents?token=

documents è l'elenco completo, nell'ordine del fax. Per conservare un file, invia di nuovo l'ID del suo slot. Per rimuoverlo, omettilo. I file rimossi vengono eliminati e le pagine vengono contate di nuovo. Funziona mentre status è draft, processing_documents o documents_ready. Dopo l'avvio del pagamento, i file non sono più modificabili. Crea un nuovo fax per cambiarli. Gli ID degli slot sono validi per 1 ora e non sono inclusi nella risposta del fax, quindi conserva gli ID caricati.

curl -s -X PATCH "https://eu.faxette.com/api/v1/faxes/k3n8q0w1x4y7/documents?token=exampletoken" \
  -H "Content-Type: application/json" \
  -d '{"documents":["SIGNED_ID","ANOTHER_ID"]}'

200, con il fax. status torna a processing_documents.

Invia di nuovo

POST /api/v1/faxes/:id/resend?token=

Un fax non riuscito può essere inviato di nuovo gratuitamente mentre l'importo è ancora trattenuto sulla carta. resend_by indica la fine di questo periodo. retries_remaining deve essere maggiore di 0; parte da 2. Un fax con failure_reason pari a our_side non può essere inviato di nuovo. L'importo viene sbloccato subito.

fax_number è facoltativo. Omettilo o invialo vuoto per usare lo stesso numero. Un numero senza prefisso internazionale viene interpretato nel paese del numero attuale del fax.

curl -s -X POST "https://eu.faxette.com/api/v1/faxes/k3n8q0w1x4y7/resend?token=exampletoken" \
  -H "Content-Type: application/json" \
  -d '{"fax_number":"+442079460018"}'

200, con il fax. status è scheduled.

{
  "status": "failed",
  "failure_reason": "temporary",
  "retries_remaining": 2,
  "resend_by": "2026-10-29T16:04:00.000Z",
  "payment": { "status": "authorized", "amount_cents": 605, "tax_cents": 105, "currency": "eur" }
}

L'oggetto fax

status

Una linea occupata viene richiamata più tardi. Queste chiamate sono attempt di max_attempts. Sono separate da un nuovo invio richiesto dal cliente.

payment

payment.status è authorized mentre l'importo è trattenuto sulla carta, paid quando il fax è consegnato e l'importo trattenuto viene addebitato, canceled quando l'importo trattenuto viene sbloccato, oppure refunded se l'addebito è stato rimborsato. amount_cents è l'importo trattenuto o addebitato sulla carta, imposte incluse. Su questo sito, al pagamento viene aggiunta l'IVA. tax_cents è quell'IVA. Gli importi dell'esempio rappresentano un singolo caso. L'IVA dipende dal paese del mittente. price resta l'importo prima delle imposte.

failure_reason

Null se status non è failed.

document_errors

Ogni elemento contiene reason, position e message. position è la posizione del documento nel fax, oppure null se il problema riguarda l'intero fax. message è la frase da mostrare alla persona. Gli stessi problemi possono essere restituiti anche come validation_failed durante la creazione, prima che esista un fax.

Errori

message è una frase. Usa code per distinguere i casi: resta stabile.

{
  "code": "validation_failed",
  "message": "Fax number is in a country we can't fax to yet."
}

Limiti

• 10 documenti, 20 MB ciascuno, 200 pagine, 50 megapixel per immagine.

Per Claude, ChatGPT e altri assistenti, Vedi il server MCP →