> ## 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. # Lista protocolos > Lista os protocolos do parceiro, do mais novo para o mais antigo. > [!NOTE] > > Veja também: > > * [Erros](https://docs.certificados.zapsign.com.br/erros.md) > * [Paginação](https://docs.certificados.zapsign.com.br/paginacao.md) ## OpenAPI ````yaml /api-reference/openapi.json get /api/v2/partners/protocols openapi: 3.1.0 info: title: Certificados ZapSign Partner API v2 version: 2.0.0 description: >- API REST para parceiros criarem e acompanharem protocolos de certificado digital e-CPF e e-CNPJ (A1 e A3 em nuvem), emitidos por videoconferência. contact: name: Suporte Certificados ZapSign url: https://wa.me/5511952135263 servers: - url: https://certificados.zapsign.com.br description: Produção security: - bearerAuth: [] tags: - name: Protocolos description: Criação, consulta, listagem e cancelamento de protocolos. - name: Verificação description: Verificação opcional do titular antes de criar o protocolo. - name: Agendamento description: Horários livres e agendamento da videoconferência. - name: Saldo e catálogo description: Saldo atual e certificados disponíveis para o parceiro. paths: /api/v2/partners/protocols: get: tags: - Protocolos summary: Lista protocolos description: Lista os protocolos do parceiro, do mais novo para o mais antigo. operationId: listProtocols parameters: - name: status in: query required: false description: Status do protocolo. Aceita um só valor. schema: $ref: '#/components/schemas/ProtocolStatus' example: protocol_generated - name: certificate_type in: query required: false description: Tipo do certificado. schema: $ref: '#/components/schemas/CertificateType' example: e_cpf - name: document in: query required: false description: >- CPF (11 números) ou CNPJ (14 caracteres, com letras e números) do titular, sem pontuação. Não busca o CPF do representante legal. schema: type: string example: '52998224725' - name: created_after in: query required: false description: >- Início do período de criação, inclusive. Formato ISO 8601 em UTC, terminado em `Z`, como `2026-10-01T00:00:00Z`. Não aceita deslocamento, como `-03:00`. schema: type: string format: date-time example: '2026-10-01T00:00:00Z' - name: created_before in: query required: false description: >- Fim do período de criação, exclusive. Mesmo formato de `created_after`, terminado em `Z`. schema: type: string format: date-time example: '2026-11-01T00:00:00Z' - name: limit in: query required: false description: Quantidade de protocolos por página. Mín. 1. Máx. 100. Padrão `20`. schema: type: integer minimum: 1 maximum: 100 default: 20 example: 20 - name: after in: query required: false description: >- Cursor da próxima página: o `protocol_id` do último protocolo recebido. Não use junto com `before`. schema: type: string pattern: ^CPR_[0-9A-HJKMNP-TV-Z]{26}$ example: CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y - name: before in: query required: false description: >- Cursor da página anterior: o `protocol_id` do primeiro protocolo recebido. Não use junto com `after`. schema: type: string pattern: ^CPR_[0-9A-HJKMNP-TV-Z]{26}$ example: CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y responses: '200': description: >- Página de protocolos. Se `has_more` é `true`, peça a próxima página com `after`. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ProtocolList' examples: Primeira página, com mais resultados: summary: Primeira página, com mais resultados value: data: - status: creating protocol_id: CPR_01K7Q3XWVTR3397NXS3140MKR8 certificate: name: e-CPF A1 (1 ano) type: e_cpf model: a1 validity_months: 12 customer: type: pf name: Ana Souza cpf: '52998224725' created_at: '2026-10-21T13:01:00.000Z' updated_at: '2026-10-21T13:01:30.000Z' - status: creating protocol_id: CPR_01K7Q3XN4BEZN33DCZF0AK48K0 certificate: name: e-CPF A1 (1 ano) type: e_cpf model: a1 validity_months: 12 customer: type: pf name: Ana Souza cpf: '52998224725' created_at: '2026-10-21T13:00:00.000Z' updated_at: '2026-10-21T13:00:30.000Z' has_more: true object: list x-codeSamples: - lang: curl label: cURL source: >- # Página 1: sem `after`. curl -G 'https://certificados.zapsign.com.br/api/v2/partners/protocols' \ -H 'Authorization: Bearer czk_live_SUA_CHAVE' \ --data-urlencode 'status=protocol_generated' \ --data-urlencode 'limit=20' # Página 2: envie em `after` o protocol_id do último protocolo da página 1. curl -G 'https://certificados.zapsign.com.br/api/v2/partners/protocols' \ -H 'Authorization: Bearer czk_live_SUA_CHAVE' \ --data-urlencode 'status=protocol_generated' \ --data-urlencode 'limit=20' \ --data-urlencode 'after=CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y' - lang: javascript label: Node.js (fetch) source: |- async function listPage(after) { const params = new URLSearchParams({ status: 'protocol_generated', limit: '20' }); if (after) params.append('after', after); const res = await fetch( `https://certificados.zapsign.com.br/api/v2/partners/protocols?${params}`, { headers: { Authorization: 'Bearer czk_live_SUA_CHAVE' }, }, ); return res.json(); } // Repita enquanto houver mais páginas. let cursor; do { const { has_more, data } = await listPage(cursor); // Aqui você usa os protocolos de `data`. cursor = has_more ? data[data.length - 1].protocol_id : undefined; } while (cursor); - lang: python label: Python (requests) source: |- import requests def list_page(after=None): params = {'status': 'protocol_generated', 'limit': 20} if after: params['after'] = after res = requests.get( 'https://certificados.zapsign.com.br/api/v2/partners/protocols', headers={'Authorization': 'Bearer czk_live_SUA_CHAVE'}, params=params, ) return res.json() # Repita enquanto houver mais páginas. cursor = None while True: page = list_page(cursor) # Aqui você usa os protocolos de page['data']. if not page['has_more']: break cursor = page['data'][-1]['protocol_id'] components: schemas: ProtocolStatus: type: string description: >- Status do protocolo. | Valor | Significado | | --- | --- | | `creating` | O protocolo está sendo criado. | | `protocol_generated` | O protocolo foi gerado e já tem número. | | `appointment_scheduled` | A videoconferência está agendada para o horário de `appointment`. | | `certificate_issued` | O certificado foi emitido. | | `cancelled` | O protocolo foi cancelado e o certificado voltou ao saldo. | | `creation_failed` | Não foi possível criar o protocolo. Nada foi descontado do saldo. | enum: - creating - protocol_generated - appointment_scheduled - certificate_issued - cancelled - creation_failed CertificateType: type: string description: >- Tipo do certificado. `e_cpf` é para titular `pf` e `e_cnpj` para titular `pj`. | Valor | Significado | | --- | --- | | `e_cpf` | Certificado e-CPF, para titular pessoa física. | | `e_cnpj` | Certificado e-CNPJ, para titular pessoa jurídica. | enum: - e_cpf - e_cnpj ProtocolList: type: object required: - object - has_more - data properties: data: type: array description: Protocolos da página, do mais novo para o mais antigo. items: $ref: '#/components/schemas/ProtocolSummary' has_more: type: boolean description: >- `true` se há mais protocolos depois desta página. Peça a próxima com `after`. example: true object: type: string const: list description: Sempre `list`. ProtocolSummary: type: object description: >- Resumo do protocolo. Não traz endereço, contato, `protocol_url`, `error` nem `valid_until`: consulte o protocolo para vê-los. required: - protocol_id - status - certificate - customer - created_at - updated_at properties: status: $ref: '#/components/schemas/ProtocolStatus' protocol_id: type: string description: >- Identificador do protocolo. Use nas chamadas de consulta, agendamento e cancelamento. pattern: ^CPR_[0-9A-HJKMNP-TV-Z]{26}$ example: CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y external_id: type: string description: Seu identificador do pedido, se você enviou um ao criar. example: PEDIDO_12345 protocol_number: type: string description: >- Número do protocolo. Compartilhe com o titular para emitir o certificado. Disponível depois que o protocolo é gerado. example: '7800' appointment: $ref: '#/components/schemas/Appointment' description: >- Videoconferência agendada. Aparece depois que o horário é confirmado. certificate: $ref: '#/components/schemas/Certificate' customer: $ref: '#/components/schemas/CustomerSummary' created_at: type: string description: Data e hora de criação do protocolo, em UTC. format: date-time example: '2026-10-21T13:00:00.000Z' updated_at: type: string description: Data e hora da última atualização do protocolo, em UTC. format: date-time example: '2026-10-21T13:00:30.000Z' Appointment: type: object description: Videoconferência agendada. required: - date - time - timezone properties: date: type: string description: Dia da videoconferência. Formato `AAAA-MM-DD`. format: date example: '2026-10-22' time: type: string description: Horário da videoconferência, de Brasília. Formato `HH:MM`. example: '11:30' timezone: type: string description: Fuso horário de `date` e `time`, hoje `America/Sao_Paulo`. example: America/Sao_Paulo Certificate: type: object description: Certificado do protocolo. required: - type - model - validity_months - name properties: name: type: string description: Nome do certificado, para exibir ao titular. example: e-CPF A1 (1 ano) type: $ref: '#/components/schemas/CertificateType' model: $ref: '#/components/schemas/CertificateModel' validity_months: $ref: '#/components/schemas/ValidityMonths' CustomerSummary: description: Titular na lista de protocolos, com documento e nome. oneOf: - $ref: '#/components/schemas/CustomerSummaryPf' - $ref: '#/components/schemas/CustomerSummaryPj' discriminator: propertyName: type mapping: pf: '#/components/schemas/CustomerSummaryPf' pj: '#/components/schemas/CustomerSummaryPj' type: object CertificateModel: type: string description: >- Modelo do certificado. | Valor | Significado | | --- | --- | | `a1` | Certificado em arquivo, instalado no computador do titular. | | `a3_em_nuvem` | Certificado guardado na nuvem, usado de qualquer dispositivo. | enum: - a1 - a3_em_nuvem ValidityMonths: type: integer enum: - 12 description: Validade do certificado, em meses. Hoje só `12` (1 ano). CustomerSummaryPf: type: object description: Resumo do titular pessoa física. required: - type - cpf - name properties: type: type: string const: pf description: Tipo do titular, `pf` para e-CPF. name: type: - string - 'null' description: Nome completo do titular. example: Ana Souza cpf: type: string description: CPF do titular, só números. example: '52998224725' title: Pessoa física CustomerSummaryPj: type: object description: Resumo do titular pessoa jurídica. required: - type - cnpj - company_name properties: type: type: string const: pj description: Tipo do titular, `pj` para e-CNPJ. company_name: type: - string - 'null' description: Razão social da empresa. example: Padaria do Bairro LTDA cnpj: type: string description: CNPJ da empresa, 14 caracteres sem pontuação. example: '11222333000181' title: Pessoa jurídica headers: XRequestId: description: Identificador da chamada. Informe-o ao suporte se precisar de ajuda. schema: type: string example: 01K7Q4A1B2C3D4E5F6G7H8J9KM securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: czk_live_* description: >- API key criada no [portal do parceiro](https://certificados.zapsign.com.br/reseller/api-keys). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.