Download de Certificados de QR Code Pix

Visão Geral

Esta API permite que os clientes obtenham, de forma automatizada, o pacote diário de certificados de QR Code Pix disponibilizado pelo Banco Central do Brasil (BCB). O retorno da consulta é um arquivo compactado no formato .zip, contendo todos os certificados válidos publicados na data de referência.

Esses certificados são utilizados para validar a autenticidade dos QR Codes estáticos e dinâmicos gerados no âmbito do arranjo Pix, conforme especificações técnicas do BCB.

Observações Importantes

Os certificados são atualizados diariamente pelo Banco Central do Brasil e disponibilizados por esta API assim que processados.
Recomenda-se que os clientes automatizem a consulta diária a este endpoint para manter sua base de certificados sempre atualizada.
O uso de certificados desatualizados pode comprometer a validação correta dos QR Codes Pix.
No máximo 1 chamada com sucesso por dia de negócio. O dia de negócio reseta às 00:00 no horário de Brasília (03:00 UTC), calculado sempre em UTC fixo — não depende do fuso do servidor do cliente.
Caso já tenha realizado o download no mesmo dia, o cliente pode enviar o cabeçalho If-None-Match com o valor do ETag recebido em uma resposta anterior, a fim de economizar banda. Se o conteúdo não tiver sido alterado, a resposta será 304 Not Modified, sem corpo. O uso desse cabeçalho é opcional: caso não seja enviado, a API sempre retorna 200 OK com o conteúdo completo.

Request

Header

Sem parâmetros de rota, query string ou corpo — é um GET simples.

GET
https://sandbox.openfinance.celcoin.dev/pix-indirect/v1/certificate/download

Header	Obrigatório	Descrição	Exemplo
Authorization	Sim	Bearer token JWT do webservice	Bearer eyJhbGciOi...
If-None-Match	Não	ETag recebido numa resposta anterior — se o conteúdo não mudou, retorna 304	"a1b2c3d4"

Response 200

Corpo binário (application/zip), transmitido via stream (FileStreamResult). Nome sugerido do arquivo: certificates_latest.zip.

Header	Descrição
Content-Type	application/zip
ETag	Etag lógico para o conteúdo atual — pode ser reenviado em `If-None-Match` na próxima chamada

304 Not Modified

Sem corpo. Retornado quando o If-None-Match enviado bate com o etag atual do certificado em cache.

Header	Descrição
ETag	Mesmo etag informado pelo cliente

503 Service Unavailable

Certificado indisponível — sem cache local.

{
  "code": "CERT001",
  "message": "Certificado indisponível no momento."
}

Erros

Status	Código	Mensagem
503	CERT001	Certificado indisponível no momento.
500	PIE001	Houve um erro interno na api.