Envíos

La API de Envíos contiene todos los endpoints para crear envíos y obtener los datos de tus envíos creados. También encontrarás los endpoints para recibir notificaciones sobre las novedades del estado de tus envíos mediante un webhook.

Envíos Externos

A la hora de definir tu integración, podrás optar por NO utilizar nuestro servicio de distribución de tarjetas.

En ese caso, los grupos de afinidad reflejarán la configuración que hayas elegido. Además, al momento de crear una tarjeta o un lote de tarjetas, te devolveremos un identificador en el campo shipment_id, que te recomendamos almacenar en tu integración ya que lo necesitarás para hacer el retiro. Las tarjetas estarán disponibles para su retiro en la planta embozadora definida en la integración.

Crear Envío

El endpoint /shipping/v1/ se usa para crear un nuevo envío de una tarjeta innominada. Ten en cuenta que para crear un envío, es requisito que hayas creado un lote de tarjetas innominadas.

Consideraciones

El campo region se corresponde con:

  • Provincia en Argentina
  • Estado en Brasil
  • Estado en Colombia
  • Estado en Mexico

El campo courier.tracking_url de la respuesta, estará disponible una vez que el envío sea confirmado por el partner logístico correspondiente. Hasta entonces, tendrá valor nulo

Para Brasil

  • Si operas en Brasil, el taxIdentificationNumber siempre será obligatorio.
  • Los campos documentNumber y documentType no serán requeridos.
  • Además, deberás completar el campo region con el código UF de dos caracteres. Ejemplo: 'SP' para 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)

Para Colombia

Si operas en Colombia, el campo zip_code es opcional, es decir que podrás no enviarlo.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
x-idempotency-keystringrequired
ID único en cada request para usar nuestro esquema de idempotencia.
Ejemplo: fRwX12Dg3345AD
Body Parameters
shipment_typestringrequired
Enum: CARD_FROM_WAREHOUSE
affinity_group_idstringrequired
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
countrystringrequired
Ejemplo: ARG
addressobjectrequired
receiverobjectrequired
Detalle de respuestas
dataobject

¿Te resultó útil esta sección?

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"
"email":
"document_type":
"dni"
"document_number":
"243432423"
"tax_identification_number":
"38912151888"
"telephone_number":
"53454342"
}
}
Ejemplo de respuestas
{
"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"
"batch":{
...
}
"address":{
...
}
"receiver":{
...
}
}
}

Buscar Envios

El endpoint /shipping/v1/ te permite buscar un grupo de envios según los atributos que especifiques.

Podrás filtrar y ordenar los envíos siguiendo esta documentación.

Los atributos para ordenar son:

  • shipment_type
  • status
  • status_detail
  • created_at
Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Query Parameters
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[country_code]string
ISO 3166-1 alpha-3
page[size]number
Tamaño de página.
page[number]number
Número de página. El número de la primer página es 0.
sortstring
Ejemplo: pid, shipment_type, status, status_detail
Detalle de respuestas
idstring
Ejemplo: shi-23hJL4bm94q9BFEd2sGhBjY6xbH
external_tracking_idstring
Ejemplo: f923da123
statusstring
Enum: CREATEDPENDINGTRACKEDREJECTEDIN_WAREHOUSEIN_TRANSITFAILED_DELIVERY_ATTEMPTDISTRIBUTIONDELIVEREDNOT_DELIVEREDSTART_OF_CUSTODYEND_OF_CUSTODYDESTRUCTIONACCIDENT
status_detailstring
Enum: CREATEDPENDINGTRACKEDREADY_FOR_DISTRIBUTIONROAD_TO_PICKUPUNSUCCESSFUL_PICKUPROAD_TO_RETURNUNSUCCESSFUL_RETURNREJECTEDSHIPMENT_SENTSHIPMENT_CONFIRMEDIN_WAREHOUSEIN_TRANSITRECEIVED_BY_CARRIERFAILED_DELIVERY_ATTEMPTWRONG_ADDRESSSHIPMENT_CONSOLIDATEDDISTRIBUTIONDELIVEREDNOT_DELIVEREDSTART_OF_CUSTODYEND_OF_CUSTODYZONE_ASSIGNEDDESTRUCTIONACCIDENTSTOLENVISIT_SCHEDULEDCALL_SCHEDULEDVISIT_CONFIRMEDCALL_FAILED_UNKNOWNNO_ACCESSFAILED_VISIT_DEADWRONG_OPERATOR_ZONECALL_RESCHEDULEDCALL_FAILED_DEADCALL_FAILEDWHATSAPP_FAILEDCOURIER_FAILEDMISSING_DOCUMENTSRETURNED_TO_WAREHOUSECLIENT_NOT_PRESENTINCOMPLETE_ADDRESSCOVERAGEOPERATOR_REASSIGNEDCLIENT_UNKNOWNNO_CALLZONE_PROBLEMSCLIENT_WORKFRAUDFRAUD_CLIENTMISSING_NUMBERCLIENT_CANCELEDDESTROYED_BY_CLIENTWEATHERLOSTCLIENT_TRIPFAILED_VISIT_UNKNOWNRETURNED
shipment_typestring
Enum: SINGLE_CARDBOXWAREHOUSE_BOXCARD_FROM_WAREHOUSEEXTERNAL_SINGLE_CARDEXTERNAL_BOX
affinity_group_idstring
Ejemplo: afg-20MpN8vmIPj77ujhb9cS8ctstN2
affinity_group_namestring
Ejemplo: Pomelo Nominate Basic Physical
courierobject
country_codestring
Ejemplo: ARG
created_atstring
Ejemplo: 2020-07-10 15:00:00.000
batchobject
addressobject
receiverobject

¿Te resultó útil esta sección?

GET/shipping/v1
Ejemplo de respuestas
{
"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":{
"company":
"ANDREANI"
"tracking_url":
"https://www.api.qa.com/#!/informacionEnv ..."
}
"country_code":
"ARG"
"created_at":
"2020-07-10 15:00:00.000"
"batch":{
"id":
"bch-23WEkAaZsqubbke9pYVAt9sG81e"
"quantity":
100
"has_stock":
true
"status":
"PENDING"
}
"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"
"email":
"document_type":
"dni"
"document_number":
"243432423"
"tax_identification_number":
"38912151888"
"telephone_number":
"53454342"
}
}

Obtener Envío

El endpoint /shipping/v1/{shipment_id} te permite obtener información sobre un envío en particular.

¿Tienes dudas sobre el estado de los envíos? Te contamos qué significa cada uno en nuestra documentación.

Consideraciones

Deberás especificar el shipment_id para hacer la consulta.

Envíos hacia un warehouse y en territorio mexicano:

Para los envíos hacia un warehouse y también para los que se realizan en México, no devolveremos un ID externo de seguimiento, ¡pero descuida! Te mantendremos informado sobre el estado del envío desde el Dashboard y también vía webhooks.

Parámetros disponibles
Header Parameters
Authorizationstringrequired
Ejemplo: Bearer {access_token}
Path Parameters
shipment_idstringrequired
Id del envío
Detalle de respuestas
dataobject

¿Te resultó útil esta sección?

GET/shipping/v1/{shipment_id}
Ejemplo de respuestas
{
"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"
"batch":{
...
}
"address":{
...
}
"receiver":{
...
}
}
}

Notificaciones de los envíos

Debes incluir este endpoint en tu servicio para que podamos comunicarte las novedades de los envíos en tiempo real.

Si tienes dudas sobre cómo configurar un webhook, visita nuestra documentación.

Consideraciones

  • En las novedades te notificaremos si hay actualizaciones sobre un envío. Ten en cuenta que serás responsable de obtener el envío para consultar el estado actualizado.
  • Esperamos una respuesta del tipo 2XX para asegurarnos de que recibiste la notificación. Caso contrario, volveremos a enviarla.

Encuentra más información sobre el estado de los envíos en nuestra documentación.

Parámetros disponibles
Header Parameters
X-Api-Keystringrequired
Este header te permitirá identificar qué api-secret tenés que usar en el caso que se hayan configurado múltiples pares de api-key y api-secret.
Ejemplo: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
Este header contiene la firma digital (timestamp + endpoint + body) que deberás verificar para asegurar la integridad del request. Si la firma no coincide, deberás rechazar el pedido.
Ejemplo: X-Signature: hmac-sha256 kLV3Jeyn7qbKfGHLDQKKuy5xzG/kbPrYEg8RvD8jb8A=
X-Timestampstringrequired
Este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.
Ejemplo: X-Timestamp: 1637117179
X-Endpointstringrequired
El endpoint al que se realiza el pedido y usaste para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.
Ejemplo: X-Endpoint: {clientPath}/shipping/updates
Body Parameters
shipment_idstring
Id del envío.
Ejemplo: shi-23hJL4bm94q9BFEd2sGhBjY6xbH
event_idstring
Identificador de evento.
Ejemplo: shipment-status-changed
idempotency_keystring
Identificador idempotente de creación del evento.
Ejemplo: e42c0eb9-3986-4f01-9f4a-df8d02a9a92f
metaobject

¿Te resultó útil esta sección?

POST/shipping/updates
{
"shipment_id":
"shi-23hJL4bm94q9BFEd2sGhBjY6xbH"
"event_id":
"shipment-status-changed"
"idempotency_key":
"e42c0eb9-3986-4f01-9f4a-df8d02a9a92f"
"meta":{
"resource_url":
"https://api.pomelo.la/shipping/v1/shi-23 ..."
}
}
Ejemplo de respuestas