Agrupamento de pacotes para a Coleta

1. Validar usuário

Chamada:

curl -X GET "https://api.mercadolibre.com/soe/bundles/users/validate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Exemplo:

curl -X GET "https://api.mercadolibre.com/soe/bundles/users/validate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {ACCESS_TOKEN}"

// Respuesta:
// 200 OK
{
  "active": true,
  "init_date": 2026-03-12T13:09:00Z
}

// 200 OK
{
  "active": false,
  "reason": "FEATURE_DISABLED"
}

Campos da resposta

• active: Campo boolean que indica se o integrador tem a experiência ativa.
• init_date: Campo que indica a data de ativação da feature.
• reason: Campo que indica a razão de NÃO ativação da feature. Isso significa que se active for true, o campo retornará nulo. Caso contrário, retornará o valor FEATURE_DISABLED.

Erros

Http Code	Message	Solution
403	At least one policy returned UNAUTHORIZED	O integrador não possui as permissões de leitura/escrita em Envios e Vendas ou não tem a feature de agrupamento ativada.
424	An external dependency has failed	Erro em serviço externo.
500	Internal server error	Erro interno do servidor.

2. Criar Bundle

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles

Parâmetros obrigatórios

Variable	Descrição
N/A	Todos os parâmetros vão no body

Body

Campo	Descrição
name	Nome do bundle
volumes	Listagem de IDs de shipment (opcional)

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name": "{bundle_name}", "volumes": ["123", "234"]}' \
https://api.mercadolibre.com/soe/bundles

// Resposta:
{
  "id": 2073,
  "name": "{bundle_name}",
  "status": "OPENED",
  "service_type": "XD",
  "create_date": "2025-11-05T16:13:02.710912202",
  "update_date": "2025-11-05T16:13:02.710912202",
  "scan_code_id": "",
 "volumes": [{
      ...,
      "reference_id": {shipment_id}
      ...
  }],
  "hash": "abcd1234"
}

Campos da resposta

• id: Campo numérico com o ID do bundle. (Tipo: Long)
• name: Campo string com o Nome do bundle. (Tipo: String, Tamanho: 15, Requerido: Sim)
• status: Campo string com o Estado do bundle. (Tipo: Constante, Requerido: Sim, Valores: OPENED)
• create_date: Campo de data com a data de criação do bundle. (Tipo: LocalDateTime)
• update_date: Campo de data com a data de atualização do bundle. (Tipo: LocalDateTime)
• service_type: Campo constante (Tipo: Constante, Requerido: Sim, Valores: XD)
• hash: Campo string com hash associado ao bundle para permitir adição/remoção de pacotes (Tipo: String, Requerido: Sim)
• volumes.reference_id: ID de envios (shipments) (Tipo: String, Tamanho: 12, Requerido: Não)

Resposta em erro ao validar volume 409:

{
  "volume_id": "{volume_id}",
  "bundle_name": "(depende do caso de uso)",
  "reason": "{reason}"
}

Erros

Variable	Descrição	Valores	Detalhe
volume_id	Id do volume em erro	String
		ERR_SHIPMENT_INVALID	ocorre quando o shipment é inválido para a operação.
		ERR_SHIPMENT_CANCELLED	ocorre quando um shipment foi cancelado.
		ERR_SHIPMENT_NOT_FOUND	ocorre quando o shipment não existe.
		ERR_SHIPMENT_FEATURE_DISABLED	ocorre quando o usuario dono do shipment não tem a experiencia de OneBip ativa.
reason	Descrição do erro	ERR_LOGISTIC	ocorre quando a logística é inválida.
		ERR_NOT_READY_FOR_PICKUP_OR_NOT_PRINTED	ocorre quando o shipment não está no estado e subestado corretos.
		ERR_SHIPMENT_EXIST_IN_OTHER_BUNDLE	ocorre quando o shipment existe em outro bundle.
		ERR_SHIPMENT_DUPLICATED	erro de validação de duplicidade
		ERR_BUNDLE_LIMIT_EXCEEDED_SHIPMENT	O limite de shipment excedeu o limite máximo 450.

Erros genéricos:

Http Code	Message	Solution
201	Created	-
400	Bad arguments	Validar o formato do JSON
401	User is not authorized into the application	O usuário não tem acesso à aplicação
409	The request generates conflict with existing data	Já existe um bundle com características similares. Verificar unicidade dos dados
424	An external dependency has failed	Erro em serviço externo de gestão de bundles
500	Internal server error	Erro interno do servidor

3.1. Busca de Bundle por ID

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/{bundle_id}/summary

Parâmetros de consulta obrigatórios

Variable	Descrição
bundle_id	ID do bundle a buscar

Exemplo

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/12345/summary

Campos de resposta para todas as buscas

Bundle Summary

• id: Id do bundle
• bundle_name: Nome do bundle
• service_type: Tipo de serviço/logística com o qual o bundle será operado
• status: Estado atual do bundle
• created_date: Data de criação do bundle
• update_date: Data da última atualização do bundle
• scan_code_id: Id da etiqueta do bundle

Volume

• id: Id do volume
• bundle_id: Id do bundle
• reference_id: Id do volume na network da MELI
• status: Estado atual do volume no contexto de kitting
• create_date: Data de criação do volume
• update_date: Data da última atualização do volume

Erros

3.2. Busca de Bundle por Referência

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/search

Parâmetros de consulta obrigatórios

Variable	Descrição
bundle_reference	Parte do nome ou do código bipável do bundle

Exemplo

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/search?bundle_reference=ABCD1234

Erros

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verificar se bundle_reference é válido. bundle_reference não pode ser vazio ou null
401	User is not authorized into the application	Verificar se o token de autorização é válido e está presente no header
404	Bundle data not found for given user	O usuário ou o bundle especificado não existe no sistema
424	An external dependency has failed	Erro em serviço externo.
500	Internal server error	Erro interno do servidor.

3.3. Busca de Bundles por usuário

Este recurso permite buscar todos os bundles do usuário integrado. Esta busca traz as informações de todos os bundles abertos, fechados, finalizados e cancelados. Este recurso não traz informações sobre volumes, no entanto, fornece informações suficientes para executar consultas subsequentes em níveis de bundles (ou grupos de bundles) específicos.

Chamada

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles

Exemplo

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles

// Resposta
[
  {
    "id": 2073,
    "name": "{bundle_name}",
    "status": "OPENED",
    "service_type": "XD",
    "create_date": "2025-11-05T16:13:02.710912202",
    "update_date": "2025-11-05T16:13:02.710912202",
    "scan_code_id": "",
    "hash": "abcd1234"
  },
  ...
]

Campos da resposta (Lista de objetos)

Erros

Http Code	Message	Solution
401	User is not authorized into the application	Verificar se o token de autorização é válido e está presente no header.
404	Bundle data not found for given user	O usuário especificado não existe no sistema.
424	An external dependency has failed	Erro em serviço externo.
500	Internal server error	Erro interno do servidor.

3.4. Busca de Volumes por ID de Bundle

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/{bundle_id}/volumes

Parâmetros de consulta obrigatórios

Variable	Descrição
bundle_id	ID do bundle cujos volumes devem ser buscados

Exemplo

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/12345/volumes

Erros

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verificar se bundle_id é válido. bundle_id não pode ser vazio ou null
401	User is not authorized into the application	Verificar se o token de autorização é válido e está presente no header
404	Management data not found for given user	O usuário especificado não existe no sistema
424	An external dependency has failed	Erro em serviço externo.
500	Internal server error	Erro interno do servidor.

3.5. Busca de volumes por referência e ID de Bundle

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/{bundle_id}/volumes/search

Parâmetros de consulta obrigatórios

Variable	Descrição
bundle_id	ID do bundle cujos volumes devem ser buscados
volume_reference	Parte do ID do shipment que se deseja buscar dentro do bundle

Exemplo

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/12345/volumes/search?volume_reference=451235132

Erros

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verificar se bundle_id e volume_references são válidos. bundle_id e volume_reference não podem ser vazios ou null
401	User is not authorized into the application	Verificar se o token de autorização é válido e está presente no header
404	Volume data not found for given user	O usuário ou o volume especificado não existe no sistema
424	An external dependency has failed	Erro em serviço externo.
500	Internal server error	Erro interno do servidor.

4. Atualizar Bundle

Variable	Descrição
bundleId	ID do bundle a atualizar (path parameter)

Chamada:

curl -X PUT "https://api.mercadolibre.com/soe/bundles/{bundleId}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{"name": "name", "status": "status"}'

Body

Campo	Descrição	Valores permitidos
name	Nome atualizado do bundle
status	Status do bundle	CLOSED, DELETED

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name": "Bundle atualizado", "status": "CLOSED"}' \
https://api.mercadolibre.com/soe/bundles/789

Campos da resposta

• id: Campo numérico com o ID do bundle. (Tipo: Long)
• name: Campo string com o Nome do bundle. (Tipo: String, Tamanho: 15, Requerido: Sim)
• status: Campo string com o Estado do bundle. (Tipo: Constante, Requerido: Sim, Valores: OPENED, CLOSED)
• create_date: Campo de data com a data de criação do bundle. (Tipo: LocalDateTime)
• update_date: Campo de data com a data de atualização do bundle. (Tipo: LocalDateTime)
• service_type: Campo constante (Tipo: Constante, Requerido: Sim, Valores: XD)
• hash: Campo string com hash associado ao bundle para permitir adição/remoção de pacotes (Tipo: String, Requerido: Sim)

Erros de validação

Variável	Descrição	Valores	Detalhe
status	estado do bundle	String
bundle_name	nome do bundle	String
		ERR_USER_WITH_FEATURE_DISABLED	ocorre quando o usuário não tem a experiência ativa.
		ERR_BUNDLE_FINISHED	ocorre quando um bundle está finalizado e você tenta excluí-lo.
		ERR_DELETING_BUNDLE	Ocorre quando a exclusão de um bundle falha.
		ERR_DATA_NOT_FOUND	ocorre quando um bundle não é encontrado.
		ERR_BUNDLE_IS_DELETED	ocorre quando você tenta excluir um bundle que já está excluído.
reason	Descrição do erro	ERR_TRANSITION_BUNDLE_STATUS	ocorre quando você tenta fechar um bundle que não possui o estado OPENED.
		ERR_TRANSITION_STATUS_CLOSED_WITH_BUNDLE_EMPTY	ocorre quando você tenta fechar um bundle que não possui envios (shipments) adicionados.
		ERR_TRANSITION_BUNDLE_STATUS_WITH_ALL_VOLUMES_CANCELLED	ocorre quando você tenta fechar um bundle com todos os seus envios (shipments) cancelados.
		ERR_TRANSITION_BUNDLE_TEST_USER	ocorre quando se tenta fechar um bundle criado em produção com um usuário de teste.
		ERR_CLOSING_BUNDLE	Ocorre quando o fechamento de um bundle falha; detalhes da falha são omitidos.

Erros

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verificar se bundleId é um número positivo válido
400	Bad arguments	Validar o formato do body JSON e que cumpram as validações
401	User is not authorized into the application	Verificar se o token de autorização é válido e está presente no header
404	Bundle data not found for given user	O bundle especificado não existe
409	The request generates conflict with existing data	A atualização gera conflito com o estado atual do bundle
424	An external dependency has failed	Erro em serviço externo.
500	Internal server error	Erro interno do servidor.

5. Adicionar Volumes ao Bundle

Chamada:

curl -X PUT "https://api.mercadolibre.com/soe/bundles/{bundle_id}/volumes" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{"volumes": ["volume_id", "volume_id", ...], "hash": "hashcode"}'

Parâmetros obrigatórios

Variable	Descrição
bundleId	ID do bundle que deve conter os volumes (path parameter)

Body

Campos	Descrição
volumes	Listagem de IDs de shipments a adicionar
hash	Hash associado ao bundle

Exemplo:

curl -X PUT "https://api.mercadolibre.com/soe/bundles/12345/volumes" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{"volumes": ["123456789", "987654321", "555666777", "111222333", "444555666"], "hash": "abcd1234"}'

// Resposta:
// 200 OK

// Response Error:
{
  "status": "CLOSED",
  "reason": "ERR_INVALID_BUNDLE_STATUS",
  "max_limit": 0,
  "bundle_name": "GRUPO 7"
}

// Or:
{
  "status": "OPENED",
  "reason": "ERR_BUNDLE_IS_DELETED",
  "max_limit": 0
}

// Or:
{
  "reason": "ERR_BUNDLE_HASH_MISMATCH",
  "max_limit": 0
}

// Or:
{
  "volume_id": "{volume_id}",
  "bundle_name": "(depende do caso de uso)",
  "reason": "{reason}"
}

Erros de validação (Campos de resposta de erro)

Variable	Descrição	Valores	Detalhe
volume_id	Id do volume em erro	String
		ERR_SHIPMENT_INVALID	ocorre quando o shipment é inválido ou não existe.
		ERR_SHIPMENT_CANCELLED	ocorre quando um shipment foi cancelado.
		ERR_SHIPMENT_NOT_FOUND	ocorre quando o shipment não existe.
		ERR_BUNDLE_HASH_MISMATCH	ocorre quando o hash do body não coincide com o calculado na criação do bundle.
		ERR_SHIPMENT_FEATURE_DISABLED	ocorre quando o usuario dono do shipment não tem a experiencia de OneBip ativa.
reason	Descrição do erro	ERR_LOGISTIC	ocorre quando a logística é inválida.
		ERR_NOT_READY_FOR_PICKUP_OR_NOT_PRINTED	ocorre quando o shipment não está no estado e subestado corretos.
		ERR_SHIPMENT_ALREADY_EXIST_IN_THE_BUNDLE	ocorre quando o shipment já existe no bundle atual.
		ERR_SHIPMENT_EXIST_IN_OTHER_BUNDLE	ocorre quando o shipment existe em outro bundle.

Erros

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verificar se bundleId é um número positivo válido
400	Bad arguments	Validar o formato do body JSON com lista de volumes válida
401	User is not authorized into the application	Verificar se o token de autorização é válido e está presente no header
404	Bundle data not found for given user	O bundle especificado não existe
409	The request generates conflict with existing data	Os volumes já estão associados ao bundle ou há conflito de estado
424	An external dependency has failed	Erro em serviço externo.
500	Internal server error	Erro interno do servidor.

6. Remover Volumes do Bundle

Chamada:

curl -X DELETE "https://api.mercadolibre.com/soe/bundles/{bundle_id}/volumes" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{"volumes": ["volume_id", "volume_id", "volume_id"], "hash": "hashcode"}'

Parâmetros obrigatórios

Variable	Descrição
bundleId	ID do bundle do qual devem ser removidos os shipments (path parameter)

Body

Campos	Descrição
volumes	Listagem de IDs de shipments a remover
hash	Hash associado ao bundle

Exemplo:

curl -X DELETE "https://api.mercadolibre.com/soe/bundles/12345/volumes" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {tu_token}" \
-d '{"volumes": ["123456789", "987654321", "555666777"], "hash": "abcd1234"}'

// Resposta:
// 200 OK

Erros

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verificar se bundleId é um número positivo válido
401	User is not authorized into the application	Verificar se o token de autorização é válido e está presente no header
404	Bundle data not found for given user	O bundle especificado não existe
409	The request generates conflict with existing data	Os volumes não podem ser removidos devido ao seu estado atual
424	An external dependency has failed	Erro em serviço externo.
500	Internal server error	Erro interno do servidor.

7. Baixar Arquivo

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/{bundleId}/file

Parâmetros de consulta obrigatórios

Variable	Descrição
bundleId	ID do bundle para baixar o arquivo (path parameter)

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/789/file

// Resposta:
// Binary file content (CSV)

Campos da resposta

• file: Conteúdo do arquivo

Headers da resposta

• content_disposition: Disposição de conteúdo
• content_type: Tipo de conteúdo do arquivo

Erros

Http Code	Message	Solution
400	One or more of the given parameters is invalid	Verificar se bundleId é um número positivo válido
401	User is not authorized into the application	Verificar se o token de autorização é válido e está presente no header
404	Bundle data not found for given user	O bundle ou usuário especificado não existe
424	An external dependency has failed	Erro em serviço externo de geração de arquivos
500	Internal server error	Erro interno do servidor ao gerar o arquivo

8. Baixar Etiqueta

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/soe/bundles/label

Body Label DownLoad Request (JSON válido)

Campos	Descrição
bundle_id	Id do bundle cuja etiqueta se deseja imprimir
format	Opcional. Formato que se deseja forçar para a impressião da etiqueta. Valores válidos: pdf, zpl. Se enviar null, se define pelas preferencias do usuario

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"bundle_id": 789}' \
https://api.mercadolibre.com/soe/bundles/label

// Respuesta:
{
  "file": "base64_encoded_data",
  "content_type": "application/pdf",
  "file_name": "ETIQUETA_789"
}

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"bundle_id": 789, 'format': 'zpl'}' \
https://api.mercadolibre.com/soe/bundles/label

// Respuesta:
{
  "file": "base64_encoded_data",
  "content_type": "text/plain",
  "file_name": "ETIQUETA_789"
}

Campos da resposta

• file: Binário da etiqueta
• content_type: Tipo de conteúdo
• file_name: Nome do arquivo

Erros

Http Code	Message	Solution
400	Bad arguments	Validar o formato do body JSON com parâmetros válidos
401	User is not authorized into the application	Verificar se o token de autorização é válido e está presente no header
404	Management data not found for given user	O bundle especificado para gerar etiqueta não existe
424	An external dependency has failed	Erro em serviço externo de geração de etiquetas
500	Internal server error	Erro interno do servidor ao gerar a etiqueta

9. Status possíveis

Status Bundle

Valor	Descrição
OPENED (“Em preparação”)	Status com o qual o bundle é criado. Neste estado, são permitidas a edição do bundle, a adição e a remoção de envios (shipments) no mesmo. Não é permitida a geração de etiquetas nem de arquivos (listagem de envios).
CLOSED (“A despachar”)	Status de bundle fechado; não é mais possível adicionar e remover envios nem alterar dados sobre o bundle. É permitida a geração de etiquetas e de arquivos (listagem de envios). Uma vez fechado, um bundle não pode ser reaberto.
IN_PROCESS	Status intermediário no processo de fechamento do bundle. É um estado que existe para prevenir a edição do bundle e a adição e remoção de envios enquanto a etiqueta e o container (que será coletado posteriormente) estão sendo gerados. A transição é automática e, em caso de falhas no fechamento, um bundle neste estado pode ser transicionado manualmente para CLOSED.
FINISHED (“Finalizado”)	Status de bundle coletado. É permitido o download do arquivo (listagem de envios). A transição para este estado é automática.
CANCELLED (“Cancelado”)	Status de bundle cancelado. A transição para este estado é automática e ocorre quando um envio (shipment) agrupado em um bundle é coletado fora do bundle.
DELETED	O bundle é excluído e não aparece mais nas buscas. Da mesma forma, os volumes associados são excluídos e é permitido agrupar os mesmos envios em um novo bundle. Uma vez excluído, o bundle não pode ser recuperado.

Status Volumes

Valor	Descrição
ADDED	O volume foi adicionado a um bundle
PICKED_UP	O volume foi coletado dentro do bundle.
EXTERNAL_PICKED_UP	O envio (shipment) associado ao volume foi coletado fora do bundle, em uma coleta distinta.
EXTERNAL_CANCELLED	O envio (shipment) associado ao volume foi cancelado.