Por proxy

O endpoint de consulta de rastreio de cartões dá visibilidade de cada etapa do processo de entrega de um cartão físico, desde a fabricação até a operação logística.

O processo de rastreio é iniciado alguns minutos após a solicitação de um novo cartão. Como este tempo é variável, pois depende dos parceiros e de validações internas de segurança, recomendamos que a consulta inicie-se após, no mínimo, 20 minutos.

Pré-requisito

Para que seja possível utilizar este endpoint, é necessário que:

O cliente tenha solicitado a emissão de um cartão físico, de um cartão múltiplo ou da segunda via de um cartão.

Requisição (Request)

Requisição HTTP

GET https://sandbox.hiperbanco.com.br/Cards/tracking/{proxy}

--request GET 'https://sandbox.hiperbanco.com.br/Cards/tracking/{proxy}' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}'

Cabeçalhos (Headers)

Nome	Propriedade	Descrição
`version`	`cutting-edge`	Essa propriedade garante que o response da API seja retornado no formato JSON
`Authorization`	`Bearer token`	Obrigatório. Token de autorização do tipo Bearer.

Parâmetros da rota (Path)

No path desta requisição envie os seguintes campos:

Nome	Tipo	Descrição	Especificação
`proxy`	`path`	Obrigatório. Código identificador do cartão.	Insira somente números, sem caracteres especiais.

Corpo da requisição (Body)

Não é necessário enviar campos no body desta requisição.

Resposta (Response)

O status code 200 indicará sucesso na busca.

Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`name`	`string`	Nome do proprietário do cartão.
`alias`	`string`	Apelido dado ao cartão. Exemplo: "cartão educação".
`externalTracking`	`object`	Objeto que contém informações sobre o código de rastreio e o nome do parceiro que realizará a entrega.
`externalTracking.code`	`string`	Código de rastreio do cartão.
`externalTracking.partner`	`string`	Nome do parceiro responsável pela entrega.
`function`	`string`	Função do cartão, que pode ser “Pré”, “Pós”, “Débito” ou "Combo".
`estimatedDeliveryDate`	`string`	Data de entrega estimada. Retornado apenas se o cartão ainda não tiver sido entregue.
`address`	`array of objects`	Lista de objetos contendo informações sobre o endereço do titular do cartão onde deve ser realizada a entrega.
`address.zipcode`	`string`	Código postal do endereço.
`address.address`	`string`	Logradouro (nome da rua, avenida etc.).
`address.number`	`string`	Número do imóvel.
`address.neighborhood`	`string`	Nome do bairro.
`address.complement`	`string`	Complemento do endereço.
`address.city`	`string`	Nome da cidade.
`address.state`	`string`	Nome do estado.
`address.country`	`string`	Nome do país.
`status`	`array of objects`	Lista de objetos contendo o histórico dos status, desde a criação do cartão até a entrega ao destinatário, do mais recente para o mais antigo.
`status.type`	`string`	Tipo ou nome dos status em que se encontra o cartão criado. Consulte a tabela de status para mais detalhes.
`status.reason`	`string`	Informações sobre o status do rastreio.
`status.createdDate`	`string`	Data e hora em que o registro foi criado na base Banco Liquidante, no formato ISO 8601 - UTC.
`status.statusDate`	`string`	Data e hora em que o status passou a entrar em vigor na courier, no formato ISO 8601 - UTC.
`finalized`	`array of objects`	Lista de objetos contendo informações sobre a entrega e recebimento do cartão.
`finalized.recipientName`	`string`	Nome do recebedor do cartão.
`finalized.recipientKinship`	`string`	Grau de parentesco do recebedor com o proprietário do cartão.
`finalized.documentNumber`	`string`	Número de documento do recebedor do cartão.
`finalized.atempts`	`number`	Número de tentativas de entrega.
`finalized.createdDate`	`string`	Data e hora em que o registro foi criado na base Banco Liquidante, no formato ISO 8601 - UTC.
`finalized.finalizedDate`	`string`	Data de entrega do cartão, no formato ISO 8601 - UTC.

{
   "name": "Nísia Floresta",
   "alias": "Cruzeiro",
   "externalTracking": {
      "code": "YB859409450BR",
      "partner": "CORREIOS"
   },
   "function": "Pré",
   "estimatedDeliveryDate": "2025-06-21T19:31:59.739Z",
   "address": [
      {
         "zipCode": "68060115",
         "address": "Rua 15 de Março",
         "number": "2515",
         "neighborhood": "Alter do Chão",
         "complement": "",
         "city": "Santarém",
         "state": "PA",
         "country": "Brasil"
      }
   ],
   "status": [
      {
         "type": "Delivered",
         "reason": "Proof of Delivery Registered",
         "createdDate": "2025-06-18T22:00:38.155Z",
         "statusDate": "2025-06-17T20:46:24.875Z"
      },
      {
         "type": "Delivered",
         "reason": "Object delivered",
         "createdDate": "2025-06-18T22:00:38.155Z",
         "statusDate": "2025-06-17T20:46:24.652Z"
      },
      {
         "type": "Delivered",
         "reason": "RT Delivery Registered",
         "createdDate": "2025-06-18T22:00:38.155Z",
         "statusDate": "2025-06-17T20:41:00.199Z"
      },
      {
         "type": "InProgress",
         "reason": "In route to delivery",
         "createdDate": "2025-06-18T22:00:38.155Z",
         "statusDate": "2025-06-17T20:36:36.940Z"
      },
      {
         "type": "InProgress",
         "reason": "Sended to delivery",
         "createdDate": "2025-06-17T16:00:07.076Z",
         "statusDate": "2025-06-17T15:33:07.076Z"
      },
      {
         "type": "InProgress",
         "reason": "Received by the shipping company",
         "createdDate": "2025-06-16T04:30:23.325Z",
         "statusDate": "2025-06-16T04:02:23.325Z"
      },
      {
         "type": "Building",
         "reason": "Card was embossed",
         "createdDate": "2025-06-07T02:00:55.000Z",
         "statusDate": "2025-06-07T01:31:55.000Z"
      },
      {
         "type": "Created",
         "reason": "Waiting for post",
         "createdDate": "2025-06-06T13:31:59.739Z",
         "statusDate": "2025-06-06T13:31:59.739Z"
      }
   ],
   "finalized": [
      {
         "recipientName": "Cláudia Raia da Silva",
         "recipientKinship": "Mãe",
         "documentNumber": "42304434191",
         "attempts": 1,
         "createdDate": "2025-06-17T22:00:12",
         "finalizedDate": "2025-06-17T20:47:18"
      }
   ]
}

Tabela de status

Tipo de status	Significado
`Created`	Primeiro registro do cartão.
`Building`	O cartão está sendo confeccionado.
`InProgress`	O cartão está sendo transferido de local.
`Delivered`	O cartão foi entregue. Este é um status final, portanto, não são necessárias novas consultas.
`Cancelled`	Dentre outros motivos, este status é exibido quando o cartão foi extraviado ou quando entrou em processo de custódia, porém o prazo para tomar uma ação a respeito expirou.
`NotDelivered`	Status relacionado a cartão não entregue, seja por endereço incorreto, seja por ter sido recusado, ou então porque o número máximo de tentativa de entregas foi excedido.
`Custody`	Situação em que o cartão não foi entregue com sucesso e fica sob custódia da transportadora. Dependendo do contrato entre o parceiro e a transportadora, são realizadas algumas tentativas de entrega até o seu retorno e atualização do endereço de entrega. Verifique as reasons a seguir.

Lista de reasons por status

Status	Reason	Descrição
Created	Waiting for post	O cartão foi solicitado.
Building	Card was embossed	Cartão confeccionado pela processadora.
	Building completed	O processo de fabricação do cartão foi finalizado.
	Sent to ship company	Cartão enviado para a transportadora.
InProgress	Received by the shipping company	Recebido pela empresa de transporte.
	Sended to Correios	Enviado aos Correios.
	Sended to delivery	Enviado à transportadora.
	In route to delivery	Em rota de entrega.
	Resented to delivery	Reenviado para entrega após atualização de endereço ou nova tentativa.
Delivered	Object delivered	Cartão entregue com sucesso.
	RT Delivery Registered	Entrega registrada via RT.
	Proof of Delivery Registered	Comprovante de entrega registrado.
	Delivered by Third Party	Entregue pela empresa de transporte.
NotDelivered	Out	Não foi possível entregar.
	Moved	Destinatário mudou-se.
	Incorrect Address	Endereço incorreto.
	Unable to deliver	Não foi possível entregar.
	Unable to access	Não foi possível acessar o endereço.
	Unknow	Destinatário desconhecido no endereço.
	Refused	Recebimento recusado.
Custody	Waiting action	Cartão não entregue, aguardando atualização de endereço.
	Returned	O cartão retornou para o emissor.
Cancelled	Lost /Sinister	Cartão extraviado ou com sinistro, sem possibilidade de nova entrega.
	Cancelled	Cartão extraviado ou devolvido, sem possibilidade de nova entrega.
	Destroyed	Cartão completamente destruído após tentativas de entrega.

⚠️
Importante
Os status de rastreio "Created" e "Building" têm um limite de permanência de cinco dias; ao final deste período, uma consulta junto à transportadora pode ser realizada, desencadeando uma possível atualização do status para "InProgress".

Fluxo dos status de rastreio

Erros

Este endpoint não retorna erros específicos. Porém, ele poderá retornar alguns erros comuns entre todos os endpoints.

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:

Nome do evento	Descrição
`TRACKING_STATUS_CHANGED`	Houve uma atualização no status de rastreio.