Shipments

The Shipping API comprises all the endpoints for creating shipments and retrieving data for your created shipments. You will also find endpoints to receive notifications about updates on the status of your shipments via a webhook.

External shipments

When defining your integration, you will have the option to NOT use our card distribution service.

In that case, the affinity groups will reflect the settings you have chosen. Also, when creating a card or a batch of cards, we will return an identifier in the shipment_id field, which we recommend you store in your integration, since you will need it for pick-up. The cards will be available for pick-up at the embossing facility specified in integration.

Create Shipment

The /shipping/v1/ endpoint is used to create a new shipment for an unnamed card. Please note that in order to create a shipment, it is required that you have batch of unnamed cards created.

Considerations

The region field corresponds to:

  • Province in Argentina
  • State in Brazil
  • State in Colombia
  • State in Mexico

The courier.tracking_url field of the response will be available once the shipment is reported by the corresponding logistics partner. Until then, it will have a null value

For Brazil

  • If you operate in Brazil, the taxIdentificationNumber is always mandatory.
  • The fields 'documentNumber' and 'documentType' will not be required.
  • You must also fill out the region field with the two-character UF code. Example: 'SP' for São Paulo
    • Rondônia (RO)
    • Acre (AC)
    • Amazonas (AM)
    • Roraima (RR)
    • Pará (PA)
    • Amapá (AP)
    • Tocantins (TO)
    • Maranhão (MA)
    • Piauí (PI)
    • Ceará (CE)
    • Rio Grande do Norte (RN)
    • Paraíba (PB)
    • Pernambuco (PE)
    • Alagoas (AL)
    • Sergipe (SE)
    • Bahia (BA)
    • Minas Gerais (MG)
    • Espírito Santo (ES)
    • Rio de Janeiro (RJ)
    • São Paulo (SP)
    • Paraná (PR)
    • Santa Catarina (SC)
    • Rio Grande do Sul (RS)
    • Mato Grosso do Sul (MS)
    • Mato Grosso (MT)
    • Goiás (GO)
    • Distrito Federal (DF)

For Colombia

If operating in Colombia, the zip_code field is optional, i.e. you may choose not to submit it.

Envio de tarjetas innominadas desde deposito

Puedes asociar un envío con el usuario al que le enviarás la tarjeta especificando el user_id en el body del shipment.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
x-idempotency-keystringrequired
Unique ID in each request to utilize our idempotency scheme.
Example: fRwX12Dg3345AD
Body Parameters
shipment_typestringrequired
Enum: CARD_FROM_WAREHOUSE
affinity_group_idstringrequired
Example: afg-20MpN8vmIPj77ujhb9cS8ctstN2
countrystringrequired
Example: ARG
addressobjectrequired
receiverobjectrequired
user_idstring
Example: usr-20MpN8vmIPj77ujhb9cS8ctstN2
Response details
dataobject

Was this section helpful to you?

POST/shipping/v1
{
"shipment_type":
"CARD_FROM_WAREHOUSE"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"country":
"ARG"
"address":{
"street_name":
"Libertador"
"street_number":
"539"
"floor":
"2"
"apartment":
"B"
"city":
"Buenos Aires"
"region":
"Buenos Aires"
"country":
"Argentina"
"zip_code":
"5346"
"neighborhood":
"string"
}
"receiver":{
"full_name":
"Gonzalo Iglesias"
"document_type":
"dni"
"document_number":
"243432423"
"tax_identification_number":
"38912151888"
"telephone_number":
"53454342"
}
"user_id":
"usr-20MpN8vmIPj77ujhb9cS8ctstN2"
}
Response examples
{
"data":{
"id":
"shi-23hJL4bm94q9BFEd2sGhBjY6xbH"
"external_tracking_id":
"f923da123"
"status":
"CREATED"
"status_detail":
"CREATED"
"shipment_type":
"SINGLE_CARD"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"affinity_group_name":
"Pomelo Nominate Basic Physical"
"courier":{
...
}
"country_code":
"ARG"
"created_at":
"2020-07-10 15:00:00.000"
"due_delivery_date":
"2020-07-20T00:00:00.000Z"
"batch":{
...
}
"address":{
...
}
"receiver":{
...
}
"user_id":
"usr-20MpN8vmIPj77ujhb9cS8ctstN2"
}
}

Search shipment

The endpoint /shipping/v1/ enables searching for a group of cards based on the attributes specified.

You'll know how to apply filters and sort the shipments by following this documentation.

The possible sorting attributes are:

  • shipment_type
  • status
  • status_detail
  • created_at
Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Query Parameters
filter[id]string
filter[shipment_type]string
Enum: SINGLE_CARDBOXCARD_FROM_WAREHOUSEWAREHOUSE_BOX
filter[batch_id]string
filter[email]string
filter[status]string
filter[batch_status]string
filter[document_number]string
filter[start_date]string
filter[end_date]string
filter[start_due_delivery_date]string
filter[end_due_delivery_date]string
filter[country_code]string
ISO 3166-1 alpha-3
filter[user_id]string
page[size]number
Page size.
page[number]number
Page number The number on the first page is 0.
sortstring
Example: pid, shipment_type, status, status_detail
Response details
dataarray
metaobject

Was this section helpful to you?

GET/shipping/v1
Response examples
{
"data":[
0:{
...
}
]
"meta":{
"pagination":{
...
}
"filter":[
...
]
}
}

Get Shipping

The /shipping/v1/{shipment_id} endpoint allows you to get information about a particular shipment.

Do you have any doubts regarding the shipment statuses? We explain the meaning of each one in our documentation.

Considerations

You will need to specify the shipment_id to perform the query.

Shipments to a warehouse and in Mexican territory:

For shipments heading to a warehouse and for those within Mexico, we won't provide an external tracking ID. But no need to fret! We'll keep you updated on the shipment status through the Dashboard and also via webhooks.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
shipment_idstringrequired
Shipment ID
Response details
dataobject

Was this section helpful to you?

GET/shipping/v1/{shipment_id}
Response examples
{
"data":{
"id":
"shi-23hJL4bm94q9BFEd2sGhBjY6xbH"
"external_tracking_id":
"f923da123"
"status":
"CREATED"
"status_detail":
"CREATED"
"shipment_type":
"SINGLE_CARD"
"affinity_group_id":
"afg-20MpN8vmIPj77ujhb9cS8ctstN2"
"affinity_group_name":
"Pomelo Nominate Basic Physical"
"courier":{
...
}
"country_code":
"ARG"
"created_at":
"2020-07-10 15:00:00.000"
"due_delivery_date":
"2020-07-20T00:00:00.000Z"
"batch":{
...
}
"address":{
...
}
"receiver":{
...
}
"user_id":
"usr-20MpN8vmIPj77ujhb9cS8ctstN2"
}
}

Get shipment history

The /shipping/v1/{shipment_id}/history endpoint allows you to get the history of states of a specific shipment.

Do you have any doubts regarding the shipment statuses? We explain the meaning of each one in our documentation.

Considerations

You will need to specify the shipment_id to perform the query.

The list of events is ordered in ascending order by update date, i. e. the most recent status is at the end of the list.

Available parameters
Header Parameters
Authorizationstringrequired
Example: Bearer {access_token}
Path Parameters
shipment_idstringrequired
Shipment ID
Response details
dataobject

Was this section helpful to you?

GET/shipping/v1/{shipment_id}/history
Response examples
{
"data":{
"id":
"shi-23hJL4bm94q9BFEd2sGhBjY6xbH"
"external_tracking_id":
"f923da123"
"failed_delivery_attempts":
1
"max_delivery_attempts":
3
"events":[
...
]
}
}

Shipments notifications

You must include this endpoint in your service so that we can provide you with real-time updates on shipments.

If you have doubts about how to set up a webhook, visit our documentation.

Considerations

  • In the updates, we'll notify you if there are any changes regarding a shipment. Please note that you'll be responsible for fetching the shipment to check the updated status.
  • We expect a response in the 2XX range to ensure that you've received the notification. Otherwise, we'll resend it.

Find more information about the shipment status in our documentation.

Available parameters
Header Parameters
X-Api-Keystringrequired
This header helps you identify which api-secret to use if multiple api-key and api-secret pairs were configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (timestamp + endpoint + body) that must be verified to ensure the integrity of the request. If the signature does not match, the order must be rejected.
Example: X-Signature: hmac-sha256 kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=
X-Timestampstringrequired
This header has the moment the order was signed in unix-epoch format so that you can verify the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint where the order is placed and used to create the signature. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.
Example: X-Endpoint: {clientPath}/shipping/updates
Body Parameters
event_idstring
Event identifier.
Example: shipment-status-changed
shipment_idstring
Id del envío.
Example: shi-23hJL4bm94q9BFEd2sGhBjY6xbH
statusstring
Estado del envío.
Example: IN_TRANSIT
updated_atstring
Fecha de actualización.
Example: 2023-09-21T14:15:31.186Z
metaobject
idempotency_keystring
Idempotent identifier for creating the event.
Example: e42c0eb9-3986-4f01-9f4a-df8d02a9a92f

Was this section helpful to you?

POST/shipping/updates
{
"event_id":
"shipment-status-changed"
"shipment_id":
"shi-23hJL4bm94q9BFEd2sGhBjY6xbH"
"status":
"IN_TRANSIT"
"updated_at":
"2023-09-21T14:15:31.186Z"
"meta":{
"resource_url":
"https://api.pomelo.la/shipping/v1/shi-23 ..."
}
"idempotency_key":
"e42c0eb9-3986-4f01-9f4a-df8d02a9a92f"
}
Response examples