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://api-mtls.sandbox.bankly.com.br/cards/{{proxy}}/tracking

--request GET \
--url 'https://api-mtls.sandbox.bankly.com.br/cards/{{proxy}}/tracking' \ 
--header 'accept: application/json' \ 
--header 'api-version: 1' \
--header 'Authorization: Bearer {{token}}'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:

Cabeçalhos (Headers)

Parâmetros da rota (Path)

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

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:

{
  "name": "Nísia Floresta",
  "alias": "Cruzeiro",
  "externalTracking": {
    "code": "YB859409450BR",
    "partner": "CORREIOS"
  },
  "function": "Combo",
  "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

Lista de reasons por status

• 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 (acontece após atualizar endereço ou quando há acordo de realizar nova tentativa de entrega).

• 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 e esperando uma ação de atualização de endereço. Caso nenhuma ação seja tomada, o cartão poderá ser cancelado;
  • “Returned”: o cartão retornou para o emissor.

• Cancelled

  • "Lost /Sinister": cartão extraviado ou que sofreu algum tipo de sinistro, sem possibilidade de nova entrega e sem possibilidade de solicitar uma nova via;
  • "Cancelled": cartão extraviado ou devolvido, sem possibilidade de nova entrega e sem possibilidade de solicitar uma nova via;
  • “Destroyed”: o cartão foi completamente destruído. Isso pode ocorrer após algumas tentativas de entrega, de acordo com o contrato entre o parceiro e a transportadora.

🚧

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

Status de rastreio

👍

Dica

Para simular uma requisição nesse endpoint, acesse o API Reference.

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: