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:

  1. Abra Chaves de API no Developer Hub e crie uma chave. Copie-a imediatamente: ela é exibida apenas uma vez.
  2. 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.
  3. Envie a chave no cabeçalho Authorization: Bearer YOUR_API_KEY de cada solicitação, junto com Accept: application/json.

Verifique se sua chave funciona perguntando quem você é:

Teste sua chave
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.

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

Parametri del corpo

messagestring • obrigatório

A mensagem impressa no verso do cartão. Máximo de 350 caracteres.

recipient_details.namestring • obrigatório

Nome do destinatário. Máximo de 40 caracteres.

recipient_details.address_line1string • obrigatório

Endereço. Máximo de 64 caracteres.

recipient_details.citystring • obrigatório

Cidade.

recipient_details.statestring • obrigatório

Código de estado de duas letras, ex.: CA.

recipient_details.zipstring • obrigatório

Código ZIP: 12345 ou 12345-6789.

recipient_details.countrystring • obrigatório

Código de país de duas letras. Use US.

design_details.image_urlstring • obrigatório

Un URL pubblicamente accessibile a un'immagine JPG o PNG ad alta risoluzione. Deve essere inferiore a 20 MB.

design_details.sizestring • opcional

Il valore predefinito è 4x6. Valori accettati: 4x6, 5x7, 6x9.

design_details.orientationstring • opcional

landscape ou portrait.

Solicitação
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"
    }
  }'
201 Created
{
  "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.

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

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.

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

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

Ciclo de vida do pedido e cobrança

  1. pending_batch: recebido. Verificamos o endereço, a mensagem e a imagem.
  2. ready_for_batch: pronto para o lote desta noite. Se houver problemas, termina como invalid_address, flagged_for_review ou image_download_failed.
  3. 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_failed até que a forma de pagamento seja atualizada.
  4. Depois sent_to_printer, in_transit e por fim delivered, conforme o USPS informa o andamento.

Webhook

Em vez de consultar repetidamente, registre um endpoint e enviaremos estes eventos por POST:

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

  • 401 chave de API ausente, inválida ou revogada.
  • 403 a chave não pode fazer isso, por exemplo cancelar um cartão-postal que já está sendo impresso.
  • 404 o cartão-postal não existe no seu espaço de trabalho.
  • 422 parâmetros inválidos. A resposta lista cada campo inválido.
  • 429 solicitações demais. O limite é de 600 solicitações por minuto por usuário.
422 ao criar um cartão-postal
{
  "error": "Validation Failed",
  "details": {
    "recipient_details.zip": ["The recipient details.zip field format is invalid."]
  }
}
401 em qualquer endpoint
{
  "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.