> ## Documentation Index > Fetch the complete documentation index at: https://docs.certificados.zapsign.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Recuperar Voucher > Retorna o voucher e seu status atual. ## OpenAPI ````yaml GET /api/v1/partners/{partnerId}/vouchers/{voucher_id} openapi: 3.1.0 info: title: Certificados ZapSign Partner API version: 4.2.0 description: >- API REST para parceiros (revendedores) emitirem vouchers de certificado digital e-CPF e e-CNPJ. Cada criação desconta 1 certificado do saldo da carteira do parceiro. Autenticação por Bearer token com prefixo `czk_live_` gerado em [https://certificados.zapsign.com.br/reseller/api-keys](https://certificados.zapsign.com.br/reseller/api-keys). contact: name: Suporte Certificados ZapSign url: https://wa.me/5511952135263 servers: - url: https://certificados.zapsign.com.br description: Produção security: - bearerAuth: [] tags: - name: Vouchers description: Criação e consulta de vouchers de certificado digital. - name: Carteira description: Saldo disponível do parceiro. paths: /api/v1/partners/{partnerId}/vouchers/{voucher_id}: get: tags: - Vouchers summary: Busca voucher pelo `voucher_id`. description: Retorna o voucher e seu status atual. operationId: getVoucherById parameters: - $ref: '#/components/parameters/PartnerIdParam' - $ref: '#/components/parameters/VoucherIdParam' responses: '200': $ref: '#/components/responses/VoucherFound' '400': $ref: '#/components/responses/InvalidVoucherId' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/VoucherNotFound' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalError' components: parameters: PartnerIdParam: name: partnerId in: path required: true description: Identificador público do parceiro (Partner ID), exibido no portal. schema: type: string minLength: 1 maxLength: 64 VoucherIdParam: name: voucher_id in: path required: true description: >- Identificador do voucher retornado em POST /vouchers/cpf ou /vouchers/cnpj. schema: type: string pattern: ^[A-Z0-9_-]{8,80}$ example: ZS_ECPF_A3_01HXYZABCDEFGHJKMNPQRSTV responses: VoucherFound: description: Voucher encontrado. content: application/json: schema: $ref: '#/components/schemas/VoucherResponse' examples: ecpf: $ref: '#/components/examples/SuccessECPF' ecnpj: $ref: '#/components/examples/SuccessECNPJ' InvalidVoucherId: description: '`voucher_id` na URL fora do padrão `^[A-Z0-9_-]{8,80}$`.' content: application/json: schema: $ref: '#/components/schemas/VoucherErrorEnvelope' examples: invalid_voucher_id: $ref: '#/components/examples/InvalidVoucherIdExample' Unauthorized: description: Não autenticado. content: application/json: schema: $ref: '#/components/schemas/VoucherErrorEnvelope' examples: missing_or_invalid_authorization: $ref: '#/components/examples/MissingOrInvalidAuthorizationExample' invalid_api_key: $ref: '#/components/examples/InvalidApiKeyExample' api_key_revoked: $ref: '#/components/examples/ApiKeyRevokedExample' Forbidden: description: Acesso negado. content: application/json: schema: $ref: '#/components/schemas/VoucherErrorEnvelope' examples: partner_not_approved: $ref: '#/components/examples/PartnerNotApprovedExample' tenant_mismatch: $ref: '#/components/examples/TenantMismatchExample' VoucherNotFound: description: Não existe voucher para este parceiro com o identificador informado. content: application/json: schema: $ref: '#/components/schemas/VoucherErrorEnvelope' examples: voucher_not_found: $ref: '#/components/examples/VoucherNotFoundExample' RateLimitExceeded: description: >- Limite de requisições excedido para a chave. Aguarde a janela e respeite os headers `RateLimit-*`. content: application/json: schema: $ref: '#/components/schemas/VoucherErrorEnvelope' examples: rate_limit_exceeded: $ref: '#/components/examples/RateLimitExceededExample' headers: RateLimit-Limit: description: Limite máximo na janela atual. schema: type: integer RateLimit-Remaining: description: Quantas requisições ainda cabem na janela. schema: type: integer example: 0 RateLimit-Reset: description: Segundos até a janela reabrir. schema: type: integer example: 42 InternalError: description: >- Falha inesperada do servidor. Reenvie com backoff exponencial; o `reference_id` garante idempotência. content: application/json: schema: $ref: '#/components/schemas/VoucherErrorEnvelope' examples: internal_error: $ref: '#/components/examples/InternalErrorExample' schemas: VoucherResponse: type: object description: >- Shape full retornado por `GET /vouchers/{voucher_id}` e por cada item de `GET /vouchers`. required: - voucher_id - certificate_type - status - issued_at - redeemed_at - decline_reason - reference_id - created_at properties: voucher_id: type: string description: Identificador único do voucher. Use no link de resgate e nas buscas. example: ZS_ECPF_A1_01HXYZABCDEFGHJKMNPQRSTV certificate_type: oneOf: - $ref: '#/components/schemas/CertificateType' - type: 'null' description: Tipo do certificado. `null` apenas em vouchers legados. status: $ref: '#/components/schemas/VoucherStatus' issued_at: type: - string - 'null' format: date-time description: >- Timestamp ISO 8601 de quando o status passou para `issued`. Costuma ser igual a `created_at`. example: '2026-05-07T14:32:11.000Z' redeemed_at: type: - string - 'null' format: date-time description: Timestamp ISO 8601 de quando o status passou para `redeemed`. example: null decline_reason: oneOf: - $ref: '#/components/schemas/VoucherDeclineReason' - type: string enum: - reseller_self_cancel - type: 'null' description: >- Motivo quando `status = declined`: um valor de `VoucherDeclineReason` ou o valor de sistema `reseller_self_cancel` (cancelamento pelo próprio revendedor). `null` nos demais estados. reference_id: type: - string - 'null' description: >- Alias enviado pelo parceiro na criação. Sempre presente: `null` quando o voucher foi criado sem alias. example: PEDIDO_12345 created_at: type: - string - 'null' format: date-time description: Timestamp ISO 8601 de criação do voucher. example: '2026-05-07T14:32:11.000Z' VoucherErrorEnvelope: type: object description: >- Envelope de erro dos endpoints de voucher: `error`, `message` e `details` (opcional). required: - error - message properties: error: type: string description: >- Código curto e estável do catálogo fechado. Use para fazer branching no seu cliente. example: validation_error message: type: string description: Mensagem em pt-BR, segura para mostrar a operadores internos. details: description: Estrutura adicional dependente do código. Veja a tabela de erros. CertificateType: type: string description: >- Slug do certificado digital a emitir. Combina o titular (`ecpf_*` pessoa física, `ecnpj_*` pessoa jurídica) com a mídia do certificado (`*_a1` arquivo `.pfx` no computador, `*_a3_nuvem` usa em qualquer dispositivo, autorizado por app de celular). enum: - ecpf_a1 - ecpf_a3_nuvem - ecnpj_a1 - ecnpj_a3_nuvem x-enumDescriptions: ecpf_a1: Pessoa física, arquivo .pfx no computador. ecpf_a3_nuvem: >- Pessoa física, qualquer dispositivo; cada uso autorizado no app de celular do titular. ecnpj_a1: Pessoa jurídica, arquivo .pfx no computador. ecnpj_a3_nuvem: >- Pessoa jurídica, qualquer dispositivo; cada uso autorizado no app de celular do responsável legal. example: ecpf_a1 VoucherStatus: type: string description: Estado atual do voucher no ciclo de vida. enum: - issued - redeemed - expired - declined x-enumDescriptions: issued: Voucher pronto pra ser usado pra emitir um certificado digital. redeemed: >- Titular já usou o voucher e recebeu o protocolo pra fazer a prova de vida e emitir o certificado. expired: Voucher venceu sem ser resgatado. declined: >- A emissão foi recusada, ou o próprio revendedor cancelou o voucher via `POST /vouchers/{voucher_id}/cancel`. Veja `decline_reason` pra o motivo (no self-cancel vale `reseller_self_cancel`). VoucherDeclineReason: type: string description: Motivo da recusa quando `status = declined`. enum: - missing_cnh_or_prior_certificate - voucher_expired - id_mismatch - documentation_invalid - facial_validation_failed - customer_gave_up - other x-enumDescriptions: missing_cnh_or_prior_certificate: Titular não apresentou CNH nem certificado prévio válido. voucher_expired: O voucher já estava vencido na hora da emissão. id_mismatch: Dados do titular não batem com o documento apresentado. documentation_invalid: Documentação entregue está inválida ou ilegível. facial_validation_failed: Validação facial (prova de vida) falhou durante a emissão. customer_gave_up: Titular desistiu da emissão antes de concluir o processo. other: Qualquer outro motivo não classificado. examples: SuccessECPF: summary: Voucher e-CPF retornado por GET /vouchers/{voucher_id} value: voucher_id: ZS_ECPF_A1_01HXYZABCDEFGHJKMNPQRSTV certificate_type: ecpf_a1 status: issued issued_at: '2026-05-07T14:32:11.000Z' redeemed_at: null decline_reason: null reference_id: PEDIDO_12345 created_at: '2026-05-07T14:32:11.000Z' SuccessECNPJ: summary: >- Voucher e-CNPJ retornado por GET /vouchers/{voucher_id} (criado sem reference_id) value: voucher_id: ZS_ECNPJ_A1_01HXYZABCDEFGHJKMNPQRSTV certificate_type: ecnpj_a1 status: issued issued_at: '2026-05-07T14:32:11.000Z' redeemed_at: null decline_reason: null reference_id: null created_at: '2026-05-07T14:32:11.000Z' InvalidVoucherIdExample: summary: '`voucher_id` na URL fora do padrão `^[A-Z0-9_-]{8,80}$`' x-resolution: Use o `voucher_id` retornado na criação (formato `ZS_...`). value: error: invalid_voucher_id message: voucher_id em formato inválido. MissingOrInvalidAuthorizationExample: summary: Header `Authorization` ausente ou fora do formato `Bearer ` x-resolution: Envie o header `Authorization` no formato `Bearer czk_live_...`. value: error: missing_or_invalid_authorization message: Header Authorization ausente ou malformado. InvalidApiKeyExample: summary: Token Bearer não bate com nenhuma chave válida x-resolution: >- Gere uma nova chave em https://certificados.zapsign.com.br/reseller/api-keys e atualize seus secrets. value: error: invalid_api_key message: API key inválida. ApiKeyRevokedExample: summary: Chave existe mas foi revogada no portal x-resolution: >- Gere uma nova chave em https://certificados.zapsign.com.br/reseller/api-keys e atualize seus secrets. value: error: api_key_revoked message: API key revogada. PartnerNotApprovedExample: summary: Parceiro existe mas o status não está em `approved` x-resolution: Aguarde a aprovação do cadastro. Você recebe email quando for liberado. value: error: partner_not_approved message: Parceiro não aprovado. TenantMismatchExample: summary: O `partnerId` da URL não bate com o dono da chave x-resolution: Use a chave do parceiro dono daquele `partnerId`. value: error: tenant_mismatch message: partnerId do path não corresponde ao dono da API key. VoucherNotFoundExample: summary: '`voucher_id` desconhecido para este parceiro' x-resolution: Confira o `voucher_id`. value: error: voucher_not_found message: Voucher não encontrado. RateLimitExceededExample: summary: Limite de requisições excedido para a chave. x-resolution: >- Reduza a frequência das chamadas e use backoff exponencial antes de tentar novamente. value: error: rate_limit_exceeded message: Limite de requisições excedido. InternalErrorExample: summary: Falha não esperada do servidor x-resolution: >- Reenvie com backoff exponencial. O mesmo `reference_id` garante idempotência. value: error: internal_error message: Erro interno do servidor. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: czk_live_* description: >- Token Bearer com prefixo `czk_live_`. Gere a chave no portal em [https://certificados.zapsign.com.br/reseller/api-keys](https://certificados.zapsign.com.br/reseller/api-keys). ````