Documentación de la API
Integra el correo físico directamente en tu software. Nuestra API REST utiliza solicitudes JSON y códigos de respuesta HTTP estándar.
URL base: https://shipapostcard.com/api/v1
Contrato legible por máquinas (impórtalo en Postman, Insomnia o un generador de código): Especificación OpenAPI 3.1
Ejemplos listos para ejecutar en cURL, Node.js, PHP y Python: Repositorio en GitHub
Prueba cada petición sin escribir código: Colección de Postman
Autenticación
Cada solicitud se autentica con una clave de API enviada como token Bearer. Empezar lleva tres pasos:
- Abre Claves de API en el Developer Hub y crea una clave. Cópiala de inmediato: solo se muestra una vez.
- Una clave pertenece al espacio de trabajo que tenías abierto al crearla. Los pedidos hechos con ella van a ese espacio de trabajo y se cobran a su propietario, así que asegúrate de que el propietario tenga un método de pago registrado.
- Envía la clave en el encabezado
Authorization: Bearer YOUR_API_KEYde cada solicitud, junto conAccept: application/json.
Comprueba que tu clave funciona preguntando quién eres:
curl https://shipapostcard.com/api/v1/user \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"Guarda las claves en tu servidor y nunca las pongas en código de navegador o de apps móviles. Si una clave se filtra, revócala en el Developer Hub y crea una nueva.
Enviar una Postal
Poner en cola una nueva postal para procesamiento por lotes diario. Las postales se imprimen en cartulina brillante de 120 lb y se entregan a USPS. Los destinatarios deben tener una dirección en EE. UU. Los remitentes pueden estar en cualquier lugar.
https://shipapostcard.com/api/v1/postcardsParámetros del cuerpo
messagestring • obligatorioEl mensaje impreso en el reverso de la postal. Máximo 350 caracteres.
recipient_details.namestring • obligatorioNombre del destinatario. Máximo 40 caracteres.
recipient_details.address_line1string • obligatorioDirección. Máximo 64 caracteres.
recipient_details.citystring • obligatorioCiudad.
recipient_details.statestring • obligatorioCódigo de estado de dos letras, p. ej. CA.
recipient_details.zipstring • obligatorioCódigo ZIP: 12345 o 12345-6789.
recipient_details.countrystring • obligatorioCódigo de país de dos letras. Usa US.
design_details.image_urlstring • obligatorioUna URL accesible públicamente a una imagen JPG o PNG de alta resolución. Debe tener menos de 20MB.
design_details.sizestring • opcionalPor defecto 4x6. Valores aceptados: 4x6, 5x7, 6x9.
design_details.orientationstring • opcionallandscape 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": "¡Gracias por suscribirte a nuestro plan empresarial!",
"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 es el precio de una postal individual en USD. El precio final se fija por volumen cuando se ejecuta el lote nocturno.
Listar postales
Devuelve las postales de tu espacio de trabajo, 10 por página. Usa el parámetro page para recorrer los 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"
}Obtener una postal
Usa el id que se devolvió al crear la postal. Funcionan tanto sap_order_94812 como el número solo.
https://shipapostcard.com/api/v1/postcards/sap_order_94812{
"id": "sap_order_94812",
"status": "in_transit",
"amount": 2.25,
"message": "¡Gracias por suscribirte a nuestro plan empresarial!",
"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á en USD, como en la respuesta de creación. tracking se completa cuando la postal se envía a la imprenta.
Cancelar una postal
Puedes cancelar una postal hasta que el lote nocturno la tome (estado pending_batch o ready_for_batch). Si se cancela, devuelve 204 sin cuerpo; a partir de ese momento la API devuelve 403.
https://shipapostcard.com/api/v1/postcards/sap_order_94812Ciclo de vida del pedido y facturación
pending_batch: recibida. Verificamos la dirección, el mensaje y la imagen.ready_for_batch: lista para el lote de esta noche. Si hay problemas, termina en su lugar comoinvalid_address,flagged_for_reviewoimage_download_failed.- Cada noche a las 23:59 UTC, todas las postales listas de un espacio de trabajo se cobran juntas a la tarjeta del propietario, con precio por volumen (ver precios). Si la tarjeta es rechazada, esperan como
payment_failedhasta que se actualice el método de pago. - Luego
sent_to_printer,in_transity finalmentedelivered, a medida que USPS informa el avance.
Webhooks
En lugar de consultar repetidamente, registra un endpoint y le enviaremos estos eventos por POST:
postcard.createdpostcard.sent_to_printerpostcard.deliveredpostcard.failedbatch.payment_failed
Cada solicitud se firma con el secreto de tu endpoint. La página de Webhooks explica cómo verificar la firma.
Errores y límites de uso
401clave de API ausente, inválida o revocada.403la clave no puede hacer esto, por ejemplo cancelar una postal que ya se está imprimiendo.404la postal no existe en tu espacio de trabajo.422parámetros inválidos. La respuesta indica cada campo inválido.429demasiadas solicitudes. El límite es de 600 solicitudes por minuto por usuario.
{
"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 solicitud que haces aparece con su respuesta en Registros de Solicitudes API.