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:

  1. Apri Chiavi API nel Developer Hub e crea una chiave. Copiala subito: viene mostrata una sola volta.
  2. 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.
  3. Invia la chiave nell'intestazione Authorization: Bearer YOUR_API_KEY di ogni richiesta, insieme a Accept: application/json.

Verifica che la chiave funzioni chiedendo chi sei:

Prova la tua chiave
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.

POSThttps://shipapostcard.com/api/v1/postcards

Parâmetros do Corpo

messagestring • obbligatorio

Il messaggio stampato sul retro della cartolina. Massimo 350 caratteri.

recipient_details.namestring • obbligatorio

Nome del destinatario. Massimo 40 caratteri.

recipient_details.address_line1string • obbligatorio

Indirizzo. Massimo 64 caratteri.

recipient_details.citystring • obbligatorio

Città.

recipient_details.statestring • obbligatorio

Codice di stato di due lettere, ad es. CA.

recipient_details.zipstring • obbligatorio

Codice ZIP: 12345 o 12345-6789.

recipient_details.countrystring • obbligatorio

Codice paese di due lettere. Usa US.

design_details.image_urlstring • obbligatorio

Uma URL acessível publicamente para uma imagem JPG ou PNG de alta resolução. Deve ter menos de 20 MB.

design_details.sizestring • facoltativo

O padrão é 4x6. Valores aceitos: 4x6, 5x7, 6x9.

design_details.orientationstring • facoltativo

landscape o portrait.

Richiesta
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"
    }
  }'
201 Created
{
  "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.

GEThttps://shipapostcard.com/api/v1/postcards?page=1
200 OK
{
  "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.

GEThttps://shipapostcard.com/api/v1/postcards/sap_order_94812
200 OK
{
  "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.

DELETEhttps://shipapostcard.com/api/v1/postcards/sap_order_94812

Ciclo di vita dell'ordine e fatturazione

  1. pending_batch: ricevuta. Controlliamo l'indirizzo, il messaggio e l'immagine.
  2. ready_for_batch: pronta per il lotto di stanotte. In caso di problemi termina invece come invalid_address, flagged_for_review o image_download_failed.
  3. 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_failed finché il metodo di pagamento non viene aggiornato.
  4. Poi sent_to_printer, in_transit e infine delivered, man mano che USPS comunica l'avanzamento.

Webhooks

Invece di interrogare l'API, registra un endpoint e gli invieremo questi eventi tramite POST:

  • postcard.created
  • postcard.sent_to_printer
  • postcard.delivered
  • postcard.failed
  • batch.payment_failed

Ogni richiesta è firmata con il segreto del tuo endpoint. La pagina Webhook spiega come verificare la firma.

Errori e limiti di utilizzo

  • 401 chiave API mancante, non valida o revocata.
  • 403 la chiave non può farlo, ad esempio annullare una cartolina già in stampa.
  • 404 la cartolina non esiste nel tuo spazio di lavoro.
  • 422 parametri non validi. La risposta elenca ogni campo non valido.
  • 429 troppe richieste. Il limite è di 600 richieste al minuto per utente.
422 durante la creazione di una cartolina
{
  "error": "Validation Failed",
  "details": {
    "recipient_details.zip": ["The recipient details.zip field format is invalid."]
  }
}
401 su qualsiasi endpoint
{
  "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.