Documentazione API
Integra la posta fisica direttamente nel tuo software. La nostra API REST utilizza richieste JSON e codici di risposta HTTP standard.
URL base: https://shipapostcard.com/api/v1
Contrato legível por máquina (importe no Postman, Insomnia ou em um gerador de código): Especificação OpenAPI 3.1
Exemplos prontos para executar em cURL, Node.js, PHP e Python: Repositório no GitHub
Teste cada requisição sem escrever código: Coleção do Postman
Autenticazione
Cada solicitação é autenticada com uma chave de API enviada como token Bearer. Começar leva três passos:
- Abra Chaves de API no Developer Hub e crie uma chave. Copie-a imediatamente: ela é exibida apenas uma vez.
- Uma chave pertence ao espaço de trabalho que você tinha aberto ao criá-la. Os pedidos feitos com ela vão para esse espaço de trabalho e são cobrados do proprietário, então verifique se o proprietário tem uma forma de pagamento cadastrada.
- Envie a chave no cabeçalho
Authorization: Bearer YOUR_API_KEYde cada solicitação, junto comAccept: application/json.
Verifique se sua chave funciona perguntando quem você é:
curl https://shipapostcard.com/api/v1/user \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"Mantenha as chaves no seu servidor e nunca as coloque em código de navegador ou de apps móveis. Se uma chave vazar, revogue-a no Developer Hub e crie uma nova.
Enviar uma Postal
Mette in coda una nuova cartolina per l'elaborazione batch giornaliera. Le cartoline sono stampate su cartoncino lucido da 120 lb e consegnate a USPS. Os destinatários devem ter um endereço nos EUA. Os remetentes podem estar em qualquer lugar.
https://shipapostcard.com/api/v1/postcardsParametri del corpo
messagestring • obrigatórioA mensagem impressa no verso do cartão. Máximo de 350 caracteres.
recipient_details.namestring • obrigatórioNome do destinatário. Máximo de 40 caracteres.
recipient_details.address_line1string • obrigatórioEndereço. Máximo de 64 caracteres.
recipient_details.citystring • obrigatórioCidade.
recipient_details.statestring • obrigatórioCódigo de estado de duas letras, ex.: CA.
recipient_details.zipstring • obrigatórioCódigo ZIP: 12345 ou 12345-6789.
recipient_details.countrystring • obrigatórioCódigo de país de duas letras. Use US.
design_details.image_urlstring • obrigatórioUn URL pubblicamente accessibile a un'immagine JPG o PNG ad alta risoluzione. Deve essere inferiore a 20 MB.
design_details.sizestring • opcionalIl valore predefinito è 4x6. Valori accettati: 4x6, 5x7, 6x9.
design_details.orientationstring • opcionallandscape ou 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": "Grazie per esserti iscritto al nostro piano aziendale!",
"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 é o preço de um cartão individual em USD. O preço final é definido pelo volume quando o lote noturno é executado.
Listar cartões-postais
Retorna os cartões-postais do seu espaço de trabalho, 10 por página. Use o parâmetro page para navegar pelos resultados.
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"
}Obter um cartão-postal
Use o id retornado ao criar o cartão-postal. Funcionam tanto sap_order_94812 quanto apenas o número.
https://shipapostcard.com/api/v1/postcards/sap_order_94812{
"id": "sap_order_94812",
"status": "in_transit",
"amount": 2.25,
"message": "Grazie per esserti iscritto al nostro piano aziendale!",
"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 está em USD, como na resposta de criação. tracking é preenchido quando o cartão postal é enviado para a gráfica.
Cancelar um cartão-postal
Você pode cancelar um cartão-postal até que o lote noturno o processe (status pending_batch ou ready_for_batch). Em caso de sucesso retorna 204 sem corpo; depois disso a API retorna 403.
https://shipapostcard.com/api/v1/postcards/sap_order_94812Ciclo de vida do pedido e cobrança
pending_batch: recebido. Verificamos o endereço, a mensagem e a imagem.ready_for_batch: pronto para o lote desta noite. Se houver problemas, termina comoinvalid_address,flagged_for_reviewouimage_download_failed.- Toda noite às 23:59 UTC, todos os cartões-postais prontos de um espaço de trabalho são cobrados juntos no cartão do proprietário, com preço por volume (ver preços). Se o cartão for recusado, eles aguardam como
payment_failedaté que a forma de pagamento seja atualizada. - Depois
sent_to_printer,in_transite por fimdelivered, conforme o USPS informa o andamento.
Webhook
Em vez de consultar repetidamente, registre um endpoint e enviaremos estes eventos por POST:
postcard.createdpostcard.sent_to_printerpostcard.deliveredpostcard.failedbatch.payment_failed
Cada solicitação é assinada com o segredo do seu endpoint. A página de Webhooks explica como verificar a assinatura.
Erros e limites de uso
401chave de API ausente, inválida ou revogada.403a chave não pode fazer isso, por exemplo cancelar um cartão-postal que já está sendo impresso.404o cartão-postal não existe no seu espaço de trabalho.422parâmetros inválidos. A resposta lista cada campo inválido.429solicitações demais. O limite é de 600 solicitações por minuto por usuário.
{
"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"
}Cada solicitação que você faz aparece com sua resposta em Log delle Richieste API.