Documentação da API
Integre o correio físico diretamente no seu software. Nossa API REST usa solicitações JSON e códigos de resposta HTTP padrão.
URL di base: https://shipapostcard.com/api/v1
Contratto leggibile dalle macchine (importalo in Postman, Insomnia o in un generatore di codice): Specifica OpenAPI 3.1
Esempi pronti da eseguire in cURL, Node.js, PHP e Python: Repository su GitHub
Prova ogni richiesta senza scrivere codice: Collezione Postman
Autenticação
Ogni richiesta è autenticata con una chiave API inviata come token Bearer. Per iniziare bastano tre passaggi:
- Apri Chiavi API nel Developer Hub e crea una chiave. Copiala subito: viene mostrata una sola volta.
- Una chiave appartiene allo spazio di lavoro che avevi aperto quando l'hai creata. Gli ordini fatti con essa vanno a quello spazio di lavoro e vengono addebitati al suo proprietario, quindi assicurati che il proprietario abbia un metodo di pagamento registrato.
- Invia la chiave nell'intestazione
Authorization: Bearer YOUR_API_KEYdi ogni richiesta, insieme aAccept: application/json.
Verifica che la chiave funzioni chiedendo chi sei:
curl https://shipapostcard.com/api/v1/user \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"Conserva le chiavi sul tuo server e non inserirle mai nel codice del browser o delle app mobili. Se una chiave viene esposta, revocala nel Developer Hub e creane una nuova.
Invia una Cartolina
Coloca um novo cartão postal na fila para processamento em lote diário. Os cartões postais são impressos em papel couchê brilhante de 120 lb e entregues ao USPS. I destinatari devono avere un indirizzo negli Stati Uniti. I mittenti possono trovarsi ovunque.
https://shipapostcard.com/api/v1/postcardsParâmetros do Corpo
messagestring • obbligatorioIl messaggio stampato sul retro della cartolina. Massimo 350 caratteri.
recipient_details.namestring • obbligatorioNome del destinatario. Massimo 40 caratteri.
recipient_details.address_line1string • obbligatorioIndirizzo. Massimo 64 caratteri.
recipient_details.citystring • obbligatorioCittà.
recipient_details.statestring • obbligatorioCodice di stato di due lettere, ad es. CA.
recipient_details.zipstring • obbligatorioCodice ZIP: 12345 o 12345-6789.
recipient_details.countrystring • obbligatorioCodice paese di due lettere. Usa US.
design_details.image_urlstring • obbligatorioUma URL acessível publicamente para uma imagem JPG ou PNG de alta resolução. Deve ter menos de 20 MB.
design_details.sizestring • facoltativoO padrão é 4x6. Valores aceitos: 4x6, 5x7, 6x9.
design_details.orientationstring • facoltativolandscape o portrait.
curl -X POST https://shipapostcard.com/api/v1/postcards \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"message": "Obrigado por assinar nosso plano corporativo!",
"recipient_details": {
"name": "Jane Doe",
"address_line1": "123 Tech Blvd",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
},
"design_details": {
"image_url": "https://example.com/images/art.jpg",
"size": "4x6",
"orientation": "landscape"
}
}'{
"id": "sap_order_94812",
"status": "pending_batch",
"amount": 2.25,
"message": "Postcard queued for daily batch processing."
}amount è il prezzo di una singola cartolina in USD. Il prezzo finale viene stabilito in base al volume quando viene eseguito il lotto notturno.
Elenca le cartoline
Restituisce le cartoline del tuo spazio di lavoro, 10 per pagina. Usa il parametro page per scorrere i risultati.
https://shipapostcard.com/api/v1/postcards?page=1{
"current_page": 1,
"data": [ { "id": "sap_order_94812", "status": "in_transit", ... } ],
"per_page": 10,
"total": 37,
"next_page_url": "https://shipapostcard.com/api/v1/postcards?page=2"
}Recupera una cartolina
Usa l'id restituito quando hai creato la cartolina. Funzionano sia sap_order_94812 sia il solo numero.
https://shipapostcard.com/api/v1/postcards/sap_order_94812{
"id": "sap_order_94812",
"status": "in_transit",
"amount": 2.25,
"message": "Obrigado por assinar nosso plano corporativo!",
"recipient_details": {
"name": "Jane Doe",
"address_line1": "123 Tech Blvd",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
},
"design_details": {
"image_url": "https://example.com/images/art.jpg",
"size": "4x6",
"orientation": "landscape"
},
"tracking": {
"expected_delivery_date": "2026-10-22",
"events": [
{ "event": "sent_to_printer", "timestamp": "2026-10-16 23:59:41" },
{ "event": "postcard.in_transit", "timestamp": "2026-10-18 09:12:05" }
]
},
"created_at": "2026-10-16T14:03:11+00:00",
"updated_at": "2026-10-18T09:12:05+00:00"
}amount è in USD, come nella risposta di creazione. tracking si compila quando la cartolina viene inviata in stampa.
Annulla una cartolina
Puoi annullare una cartolina finché il lotto notturno non la prende in carico (stato pending_batch o ready_for_batch). In caso di successo restituisce 204 senza corpo; dopo quel momento l'API restituisce 403.
https://shipapostcard.com/api/v1/postcards/sap_order_94812Ciclo di vita dell'ordine e fatturazione
pending_batch: ricevuta. Controlliamo l'indirizzo, il messaggio e l'immagine.ready_for_batch: pronta per il lotto di stanotte. In caso di problemi termina invece comeinvalid_address,flagged_for_reviewoimage_download_failed.- Ogni notte alle 23:59 UTC, tutte le cartoline pronte di uno spazio di lavoro vengono addebitate insieme sulla carta del proprietario, con prezzo in base al volume (vedi prezzi). Se la carta viene rifiutata, restano in
payment_failedfinché il metodo di pagamento non viene aggiornato. - Poi
sent_to_printer,in_transite infinedelivered, man mano che USPS comunica l'avanzamento.
Webhooks
Invece di interrogare l'API, registra un endpoint e gli invieremo questi eventi tramite POST:
postcard.createdpostcard.sent_to_printerpostcard.deliveredpostcard.failedbatch.payment_failed
Ogni richiesta è firmata con il segreto del tuo endpoint. La pagina Webhook spiega come verificare la firma.
Errori e limiti di utilizzo
401chiave API mancante, non valida o revocata.403la chiave non può farlo, ad esempio annullare una cartolina già in stampa.404la cartolina non esiste nel tuo spazio di lavoro.422parametri non validi. La risposta elenca ogni campo non valido.429troppe richieste. Il limite è di 600 richieste al minuto per utente.
{
"error": "Validation Failed",
"details": {
"recipient_details.zip": ["The recipient details.zip field format is invalid."]
}
}{
"success": false,
"message": "Unauthenticated",
"errors": null,
"error_code": "AUTH_ERROR"
}Ogni richiesta che fai è elencata con la sua risposta in Logs de Solicitações API.