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:

  1. Abre Claves de API en el Developer Hub y crea una clave. Cópiala de inmediato: solo se muestra una vez.
  2. 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.
  3. Envía la clave en el encabezado Authorization: Bearer YOUR_API_KEY de cada solicitud, junto con Accept: application/json.

Comprueba que tu clave funciona preguntando quién eres:

Prueba tu clave
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.

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

Parámetros del cuerpo

messagestring • obligatorio

El mensaje impreso en el reverso de la postal. Máximo 350 caracteres.

recipient_details.namestring • obligatorio

Nombre del destinatario. Máximo 40 caracteres.

recipient_details.address_line1string • obligatorio

Dirección. Máximo 64 caracteres.

recipient_details.citystring • obligatorio

Ciudad.

recipient_details.statestring • obligatorio

Código de estado de dos letras, p. ej. CA.

recipient_details.zipstring • obligatorio

Código ZIP: 12345 o 12345-6789.

recipient_details.countrystring • obligatorio

Código de país de dos letras. Usa US.

design_details.image_urlstring • obligatorio

Una URL accesible públicamente a una imagen JPG o PNG de alta resolución. Debe tener menos de 20MB.

design_details.sizestring • opcional

Por defecto 4x6. Valores aceptados: 4x6, 5x7, 6x9.

design_details.orientationstring • opcional

landscape o portrait.

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

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"
}

Obtener una postal

Usa el id que se devolvió al crear la postal. Funcionan tanto sap_order_94812 como el número solo.

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

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

Ciclo de vida del pedido y facturación

  1. pending_batch: recibida. Verificamos la dirección, el mensaje y la imagen.
  2. ready_for_batch: lista para el lote de esta noche. Si hay problemas, termina en su lugar como invalid_address, flagged_for_review o image_download_failed.
  3. 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_failed hasta que se actualice el método de pago.
  4. Luego sent_to_printer, in_transit y finalmente delivered, a medida que USPS informa el avance.

Webhooks

En lugar de consultar repetidamente, registra un endpoint y le enviaremos estos eventos por POST:

  • postcard.created
  • postcard.sent_to_printer
  • postcard.delivered
  • postcard.failed
  • batch.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

  • 401 clave de API ausente, inválida o revocada.
  • 403 la clave no puede hacer esto, por ejemplo cancelar una postal que ya se está imprimiendo.
  • 404 la postal no existe en tu espacio de trabajo.
  • 422 parámetros inválidos. La respuesta indica cada campo inválido.
  • 429 demasiadas solicitudes. El límite es de 600 solicitudes por minuto por usuario.
422 al crear una postal
{
  "error": "Validation Failed",
  "details": {
    "recipient_details.zip": ["The recipient details.zip field format is invalid."]
  }
}
401 en cualquier endpoint
{
  "success": false,
  "message": "Unauthenticated",
  "errors": null,
  "error_code": "AUTH_ERROR"
}

Cada solicitud que haces aparece con su respuesta en Registros de Solicitudes API.