---
updatedAt: 2025-09-29T22:40:45.000Z
agentTools:
projectIndex: https://docs.bankly.com.br/llms.txt
---
# Por proxy
stable pré pós
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](\[https://docs.bankly.com.br/docs/emissao-cartao-fisico]\(https://docs.bankly.com.br/docs/emissao-cartao-fisico\)), de um [cartão múltiplo](\[https://docs.bankly.com.br/docs/emissao-cartao-multiplo]\(https://docs.bankly.com.br/docs/emissao-cartao-multiplo\)) ou da [segunda via](\[https://docs.bankly.com.br/docs/emissao-segunda-via]\(https://docs.bankly.com.br/docs/emissao-segunda-via\)) de um cartão.
## Requisição (Request)
### Requisição HTTP
```http
GET https://api-mtls.sandbox.bankly.com.br/cards/{{proxy}}/tracking
```
```curl cURL
--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](https://docs.bankly.com.br/docs/scopes)* como parte do seu [fluxo de autorização](https://docs.bankly.com.br/docs/fluxos-autorizacao).\
Esta requisição requer o *scope* descrito a seguir:
| Scope | Descrição |
| ----------- | --------------------------------------------------------- |
| `card.read` | Concede acesso para consultar dados não PCI de um cartão. |
### Cabeçalhos (Headers)
| Nome | Descrição |
| --------------- | ----------------------------------------------------------------- |
| `api-version` | **Obrigatório**. Versão da API. Atualmente estamos na versão 1.0. |
| `Authorization` | **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. Este campo **somente** será retornado caso o cartão ainda não tenha sido entregue. |
| `address` | `array of objects` | Lista de objetos contendo informações sobre o endereço do titular do cartão no qual 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. |
| `stastus.type` | `string` | Tipo ou nome dos *status* em que se encontra o cartão criado. Consulte a [tabela de *status*](https://docs.bankly.com.br/docs/cartoes-rastreio#tabela-de-status) para mais detalhes. |
| `status.reason` | `string` | Informações sobre o [*status* do rastreio](https://docs.bankly.com.br/docs/cartoes-rastreio#lista-de-reasons) . |
| `status.createdDate` | `string` | Data e hora em que o registro foi criado **na base Bankly**, 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 Bankly**, no formato ISO 8601 - UTC. |
| `finalized.finalizedDate` | `string` | Data de entrega do cartão, no formato ISO 8601 - UTC. |
```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*
| 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](https://docs.bankly.com.br/docs/alteracao-endereco). Verifique as *reasons* a seguir. |
### 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](https://docs.bankly.com.br/docs/alteracao-endereco) 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](https://docs.bankly.com.br/reference/rastreio-por-proxy).
## Erros
Este *endpoint* não retorna erros específicos. Porém, ele poderá retornar alguns [erros comuns](https://docs.bankly.com.br/docs/erros) entre todos os *endpoints*.
## Eventos
Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse *endpoint*, é preciso [configurar o webhook](https://docs.bankly.com.br/docs/configuracao-webhooks). Os eventos são:
| Nome do evento | Descrição |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| [`TRACKING_STATUS_CHANGED`](https://docs.bankly.com.br/docs/eventos-cartoes#tracking_status_changed) | Houve uma atualização no status de rastreio. |