> ## 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. # Cria protocolo > Cria um protocolo para o titular emitir o certificado digital. > [!NOTE] > > Veja também: > > * [Erros](https://docs.certificados.zapsign.com.br/erros.md) > * [Idempotência](https://docs.certificados.zapsign.com.br/idempotencia.md) > * [Ciclo de vida do protocolo](https://docs.certificados.zapsign.com.br/ciclo-de-vida-do-protocolo.md) ## OpenAPI ````yaml /api-reference/openapi.json post /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: post: tags: - Protocolos summary: Cria protocolo description: Cria um protocolo para o titular emitir o certificado digital. operationId: createProtocol parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateProtocolRequest' examples: e-CPF, sem agendamento: summary: e-CPF, sem agendamento value: certificate: type: e_cpf model: a1 validity_months: 12 customer: type: pf cpf: '52998224725' birth_date: '1990-01-02' email: ana@exemplo.com.br phone: '+5511987654321' address: cep: '01310100' street: Rua das Flores number: '123' neighborhood: Centro city: São Paulo state: SP external_id: PEDIDO_12345 e-CPF, com agendamento: summary: e-CPF, com agendamento value: certificate: type: e_cpf model: a1 validity_months: 12 customer: type: pf cpf: '52998224725' birth_date: '1990-01-02' email: ana@exemplo.com.br phone: '+5511987654321' address: cep: '01310100' street: Rua das Flores number: '123' neighborhood: Centro city: São Paulo state: SP appointment: date: '2026-10-22' time: '11:30' external_id: PEDIDO_12345 e-CNPJ, com representante legal: summary: e-CNPJ, com representante legal value: certificate: type: e_cnpj model: a1 validity_months: 12 customer: type: pj cnpj: '11222333000181' representative: cpf: '52998224725' birth_date: '1990-01-02' email: ana@exemplo.com.br phone: '+5511987654321' address: cep: '01310100' street: Rua das Flores number: '123' neighborhood: Centro city: São Paulo state: SP external_id: PEDIDO_12346 responses: '202': description: >- Protocolo aceito, com `status` `creating`. Consulte o protocolo em `Location` até o `status` ser `protocol_generated` ou `creation_failed`. Com `appointment`, a resposta é a mesma: o horário aparece ao consultar o protocolo. headers: Location: $ref: '#/components/headers/Location' Retry-After: $ref: '#/components/headers/PollAfter' Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Protocol' examples: Protocolo de e-CPF criado: summary: Protocolo de e-CPF criado value: status: creating protocol_id: CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y external_id: PEDIDO_12345 certificate: name: e-CPF A1 (1 ano) type: e_cpf model: a1 validity_months: 12 customer: type: pf name: Ana Souza cpf: '52998224725' birth_date: '1990-01-02' email: ana@exemplo.com.br phone: '+5511987654321' address: cep: '01310100' street: Rua das Flores number: '123' complement: null neighborhood: Centro city: São Paulo state: SP created_at: '2026-10-21T13:00:00.000Z' updated_at: '2026-10-21T13:00:00.000Z' Protocolo de e-CNPJ criado: summary: Protocolo de e-CNPJ criado value: status: creating protocol_id: CPR_01K7Q3Z3H5R10F96C0ZRFZM9B1 certificate: name: e-CNPJ A1 (1 ano) type: e_cnpj model: a1 validity_months: 12 customer: type: pj company_name: Padaria do Bairro LTDA cnpj: '11222333000181' representative: name: Ana Souza cpf: '52998224725' birth_date: '1990-01-02' email: ana@exemplo.com.br phone: '+5511987654321' address: cep: '01310100' street: Rua das Flores number: '123' complement: null neighborhood: Centro city: São Paulo state: SP created_at: '2026-10-21T13:00:00.000Z' updated_at: '2026-10-21T13:00:00.000Z' '400': description: >- Body inválido ou `Idempotency-Key` ausente ou inválida. Veja o que fazer em [Erros](/erros). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: type: object required: - type - status - code - message - retryable - request_id properties: code: type: string description: >- Código do erro. Veja como corrigir em [Erros](/erros). | Valor | Significado | | --- | --- | | `validation_error` | O body, a query ou um header da requisição tem um valor inválido. | | `idempotency_key_required` | A requisição não trouxe o header `Idempotency-Key`. | enum: - validation_error - idempotency_key_required message: type: string description: Mensagem em português sobre o erro. example: Erro de validação no corpo da requisição. retryable: type: boolean description: '`true` quando vale reenviar a mesma chamada.' example: false field_errors: type: array description: Campos que precisam de correção. items: $ref: '#/components/schemas/FieldError' status: type: integer description: Status HTTP da resposta. example: 400 type: type: string description: URL da página do erro. format: uri example: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: type: string description: Identificador da chamada, igual ao header `X-Request-Id`. example: 01K7Q4A1B2C3D4E5F6G7H8J9KM examples: 'Nome do titular enviado: a API já preenche': summary: 'Nome do titular enviado: a API já preenche' value: code: validation_error message: Erro de validação no corpo da requisição. retryable: false field_errors: - field: customer.name message: 'Não envie nomes: eles vêm da consulta oficial.' status: 400 type: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM Certificado não corresponde ao tipo do titular: summary: Certificado não corresponde ao tipo do titular value: code: validation_error message: Erro de validação no corpo da requisição. retryable: false field_errors: - field: certificate.type message: >- O tipo do certificado não corresponde ao tipo do cliente. status: 400 type: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM Certificado sem opção de agendamento: summary: Certificado sem opção de agendamento value: code: validation_error message: Erro de validação no corpo da requisição. retryable: false field_errors: - field: appointment message: >- Este certificado não aceita agendamento: remova appointment. status: 400 type: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM E-mail com o sinal +: summary: E-mail com o sinal + value: code: validation_error message: Erro de validação no corpo da requisição. retryable: false field_errors: - field: customer.email message: O e-mail não pode conter o sinal +. Use outro e-mail. status: 400 type: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM Chave de idempotência não enviada: summary: Chave de idempotência não enviada value: code: idempotency_key_required message: Header Idempotency-Key ausente. retryable: false status: 400 type: >- https://docs.certificados.zapsign.com.br/erros/idempotency_key_required request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '409': $ref: '#/components/responses/ConflictCreate' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' x-codeSamples: - lang: curl label: cURL source: >- # Gere uma chave para cada ação. Ao reenviar a mesma chamada, use a mesma chave. # A resposta é 202. Consulte o protocolo até o status ser protocol_generated ou creation_failed. curl -X POST 'https://certificados.zapsign.com.br/api/v2/partners/protocols' \ -H 'Authorization: Bearer czk_live_SUA_CHAVE' \ -H 'Idempotency-Key: 3f2b8a1e-7c4d-4e0a-9b51-6d2f8c9e1a47' \ -H 'Content-Type: application/json' \ -d '{ "certificate": { "type": "e_cpf", "model": "a1", "validity_months": 12 }, "customer": { "type": "pf", "cpf": "52998224725", "birth_date": "1990-01-02", "email": "ana@exemplo.com.br", "phone": "+5511987654321", "address": { "cep": "01310100", "street": "Rua das Flores", "number": "123", "neighborhood": "Centro", "city": "São Paulo", "state": "SP" } }, "external_id": "PEDIDO_12345" }' - lang: javascript label: Node.js (fetch) source: >- // Gere a chave uma vez por ação e reutilize-a ao reenviar a mesma chamada. const idempotencyKey = crypto.randomUUID(); const res = await fetch( 'https://certificados.zapsign.com.br/api/v2/partners/protocols', { method: 'POST', headers: { Authorization: 'Bearer czk_live_SUA_CHAVE', 'Idempotency-Key': idempotencyKey, 'Content-Type': 'application/json', }, body: JSON.stringify({ certificate: { type: 'e_cpf', model: 'a1', validity_months: 12, }, customer: { type: 'pf', cpf: '52998224725', birth_date: '1990-01-02', email: 'ana@exemplo.com.br', phone: '+5511987654321', address: { cep: '01310100', street: 'Rua das Flores', number: '123', neighborhood: 'Centro', city: 'São Paulo', state: 'SP', }, }, external_id: 'PEDIDO_12345', }), }, ); const protocolo = await res.json(); // A resposta é 202. Consulte o protocolo até `protocolo.status` ser `protocol_generated` ou `creation_failed`. - lang: python label: Python (requests) source: >- import requests import uuid # Gere a chave uma vez por ação e reutilize-a ao reenviar a mesma chamada. idempotency_key = str(uuid.uuid4()) res = requests.post( 'https://certificados.zapsign.com.br/api/v2/partners/protocols', headers={ 'Authorization': 'Bearer czk_live_SUA_CHAVE', 'Idempotency-Key': idempotency_key, }, json={ 'certificate': { 'type': 'e_cpf', 'model': 'a1', 'validity_months': 12, }, 'customer': { 'type': 'pf', 'cpf': '52998224725', 'birth_date': '1990-01-02', 'email': 'ana@exemplo.com.br', 'phone': '+5511987654321', 'address': { 'cep': '01310100', 'street': 'Rua das Flores', 'number': '123', 'neighborhood': 'Centro', 'city': 'São Paulo', 'state': 'SP', }, }, 'external_id': 'PEDIDO_12345', }, ) protocolo = res.json() # A resposta é 202. Consulte o protocolo até protocolo['status'] ser protocol_generated ou creation_failed. components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true description: >- Identificador da ação, para reenviar a chamada sem repeti-la. Use a mesma chave ao reenviar e outra para cada nova ação. Letras, números e `. _ : -`, sem dados pessoais. Não expira. Máx. 128 caracteres. schema: type: string pattern: ^[A-Za-z0-9._:-]{1,128}$ minLength: 1 maxLength: 128 example: 3f2b8a1e-7c4d-4e0a-9b51-6d2f8c9e1a47 schemas: CreateProtocolRequest: type: object additionalProperties: false required: - certificate - customer description: Dados do novo protocolo. properties: certificate: $ref: '#/components/schemas/CertificateRequest' customer: $ref: '#/components/schemas/CustomerRequest' appointment: $ref: '#/components/schemas/AppointmentRequest' description: >- Horário da videoconferência. Escolha um horário livre em [Lista horários](/api-reference/agendamento/lista-horarios): os exemplos têm datas fixas. Sem este campo, o titular pode entrar na fila de atendimento. external_id: type: string description: >- Identificador do pedido no seu sistema. Vem de volta no protocolo. Não pode repetir entre os seus protocolos, nem em um cancelado ou que falhou. Máx. 100 caracteres. minLength: 1 maxLength: 100 example: PEDIDO_12345 Protocol: type: object required: - protocol_id - status - certificate - customer - created_at - updated_at properties: status: $ref: '#/components/schemas/ProtocolStatus' error: $ref: '#/components/schemas/ProtocolError' 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' protocol_url: type: string description: >- Link da fila da videoconferência. Compartilhe com o titular. Aparece só em `protocol_generated`, quando o link está disponível. format: uri example: https://sistemas.gestaocd.com.br/fila/Xk3pQ9vT2a/52998224725/7800 appointment: $ref: '#/components/schemas/Appointment' description: >- Videoconferência agendada. Aparece depois que o horário é confirmado. Ao reagendar, mantém o horário anterior até a confirmação do novo. valid_until: type: - string - 'null' description: >- Fim da validade do certificado, em UTC. Aparece quando o certificado é emitido. format: date-time example: '2027-10-20T14:10:00.000Z' certificate: $ref: '#/components/schemas/Certificate' customer: $ref: '#/components/schemas/Customer' 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' FieldError: type: object description: Campo da requisição que precisa de correção. required: - field - message properties: field: type: string description: >- Caminho do campo com erro, como `customer.address.cep`, ou o nome do header. example: customer.cpf message: type: string description: Mensagem em português sobre o que corrigir. example: CPF inválido. CertificateRequest: type: object additionalProperties: false required: - type - model - validity_months description: >- Certificado a emitir. Use uma combinação de `GET /protocol-products`. O `credits_required` dela é descontado do saldo. properties: type: $ref: '#/components/schemas/CertificateType' model: $ref: '#/components/schemas/CertificateModel' validity_months: $ref: '#/components/schemas/ValidityMonths' CustomerRequest: description: >- Titular do certificado. Não envie `name` nem `company_name`: a API os preenche. oneOf: - $ref: '#/components/schemas/CustomerPfRequest' - $ref: '#/components/schemas/CustomerPjRequest' discriminator: propertyName: type mapping: pf: '#/components/schemas/CustomerPfRequest' pj: '#/components/schemas/CustomerPjRequest' type: object AppointmentRequest: type: object additionalProperties: false required: - date - time description: >- Horário da videoconferência. Escolha um horário livre em [Lista horários](/api-reference/agendamento/lista-horarios): os exemplos têm datas fixas. 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`. pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ example: '11:30' 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 ProtocolError: type: object description: >- Falha da última ação (criar, agendar ou cancelar). Só aparece quando a ação falhou. required: - code - message properties: code: $ref: '#/components/schemas/ProtocolErrorCode' reason: $ref: '#/components/schemas/ProtocolErrorReason' message: type: string description: Mensagem em português sobre a falha. example: O horário escolhido não está mais disponível. Escolha outro horário. 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' Customer: description: >- Titular do certificado. A API preenche o nome (`name` ou `company_name`). oneOf: - $ref: '#/components/schemas/CustomerPf' - $ref: '#/components/schemas/CustomerPj' discriminator: propertyName: type mapping: pf: '#/components/schemas/CustomerPf' pj: '#/components/schemas/CustomerPj' type: object VideoNotEligibleReason: type: string description: >- Motivo pelo qual o titular não pode emitir por videoconferência. | Valor | Significado | | --- | --- | | `identity_not_confirmed` | O CPF e a data de nascimento não conferem. No e-CNPJ, são os do representante legal. | | `legal_representation_not_confirmed` | A pessoa informada não consta como representante legal da empresa. | | `video_requirements_not_met` | Os dados conferem, mas falta biometria cadastrada ou CNH para a videoconferência. No e-CNPJ, vale para o representante legal. | enum: - identity_not_confirmed - legal_representation_not_confirmed - video_requirements_not_met 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 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). CustomerPfRequest: type: object additionalProperties: false required: - type - cpf - birth_date - email - phone - address description: Titular pessoa física, para e-CPF. properties: type: type: string const: pf description: Use `pf` para e-CPF e `pj` para e-CNPJ. cpf: type: string description: CPF do titular, só números. example: '52998224725' birth_date: type: string description: Data de nascimento. Formato `AAAA-MM-DD`. Não pode ser futura. format: date example: '1990-01-02' email: type: string description: >- E-mail do titular. Use o e-mail do próprio cliente. Cada e-mail só pode ser usado com um CPF. Sem o sinal `+`. Máx. 254 caracteres. format: email maxLength: 254 pattern: ^[^+]*$ example: ana@exemplo.com.br phone: type: string description: Celular brasileiro com DDD e código do país, como `+5511987654321`. example: '+5511987654321' address: $ref: '#/components/schemas/AddressRequest' title: Pessoa física CustomerPjRequest: type: object additionalProperties: false required: - type - cnpj - representative description: Titular pessoa jurídica, para e-CNPJ. properties: type: type: string const: pj description: Use `pf` para e-CPF e `pj` para e-CNPJ. cnpj: type: string description: >- CNPJ da empresa, 14 caracteres sem pontuação. Aceita números e letras. example: '11222333000181' representative: $ref: '#/components/schemas/RepresentativeRequest' title: Pessoa jurídica ProtocolErrorCode: type: string description: >- Código da falha. Veja o que fazer em [Ciclo de vida do protocolo](/ciclo-de-vida-do-protocolo). | Valor | Significado | | --- | --- | | `slot_unavailable` | O horário escolhido não está mais disponível. | | `appointment_rejected` | O agendamento não foi confirmado. | | `reschedule_rejected` | O novo horário não foi confirmado. | | `provider_unavailable` | O serviço está indisponível no momento. | | `order_not_created` | A criação do protocolo não foi concluída e nada foi descontado do saldo. Crie outro protocolo com uma nova `Idempotency-Key` e outro `external_id`. | | `protocol_not_created` | O protocolo não foi gerado e nada foi descontado do saldo. Crie outro protocolo com uma nova `Idempotency-Key` e outro `external_id`. | | `invalid_state` | O protocolo não pode ser cancelado. | enum: - slot_unavailable - appointment_rejected - reschedule_rejected - provider_unavailable - order_not_created - protocol_not_created - invalid_state ProtocolErrorReason: type: string description: >- Detalhe da falha. Só aparece com `protocol_not_created`. | Valor | Significado | | --- | --- | | `holder_email_in_use` | O e-mail já estava vinculado a outro CPF e a Autoridade Certificadora recusou o protocolo. Nada foi descontado do saldo. Crie outro protocolo com outro e-mail, uma nova `Idempotency-Key` e outro `external_id`. | enum: - holder_email_in_use CustomerPf: type: object description: Titular pessoa física. required: - type - cpf - birth_date - name - email - phone - address 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' birth_date: type: - string - 'null' description: Data de nascimento. Formato `AAAA-MM-DD`. example: '1990-01-02' email: type: - string - 'null' description: E-mail do titular. example: ana@exemplo.com.br phone: type: - string - 'null' description: Celular com DDD e código do país, como `+5511987654321`. example: '+5511987654321' address: $ref: '#/components/schemas/Address' title: Pessoa física CustomerPj: type: object description: >- Titular pessoa jurídica. Os dados de quem faz a videoconferência ficam em `representative`. required: - type - cnpj - company_name - representative 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' representative: type: object description: >- Representante legal da empresa, quem faz a videoconferência do e-CNPJ. required: - cpf - birth_date - name - email - phone - address properties: name: type: - string - 'null' description: Nome completo do representante legal. example: Ana Souza cpf: type: - string - 'null' description: CPF do representante legal, só números. example: '52998224725' birth_date: type: - string - 'null' description: Data de nascimento. Formato `AAAA-MM-DD`. example: '1990-01-02' email: type: - string - 'null' description: E-mail do representante legal. example: ana@exemplo.com.br phone: type: - string - 'null' description: Celular com DDD e código do país, como `+5511987654321`. example: '+5511987654321' address: $ref: '#/components/schemas/Address' title: Pessoa jurídica AddressRequest: type: object additionalProperties: false description: Endereço do titular. required: - cep - street - number - neighborhood - city - state properties: cep: type: string description: CEP, 8 dígitos, só números. example: '01310100' street: type: string description: Nome da rua ou avenida. Máx. 200 caracteres. minLength: 1 maxLength: 200 example: Rua das Flores number: type: string description: Número do endereço. Use `S/N` se não houver. Máx. 200 caracteres. minLength: 1 maxLength: 200 example: '123' complement: type: - string - 'null' maxLength: 200 description: Complemento do endereço. Máx. 200 caracteres. example: Sala 4 neighborhood: type: string description: Bairro. Máx. 200 caracteres. minLength: 1 maxLength: 200 example: Centro city: type: string description: Cidade. Máx. 200 caracteres. minLength: 1 maxLength: 200 example: São Paulo state: type: string description: Sigla da UF, como `SP`. minLength: 2 maxLength: 2 example: SP RepresentativeRequest: type: object additionalProperties: false description: >- Representante legal da empresa, quem faz a videoconferência do e-CNPJ. O e-mail, o telefone e o endereço do protocolo são os dele. required: - cpf - birth_date - email - phone - address properties: cpf: type: string description: CPF do representante legal, só números. example: '52998224725' birth_date: type: string description: Data de nascimento. Formato `AAAA-MM-DD`. Não pode ser futura. format: date example: '1990-01-02' email: type: string description: >- E-mail do representante legal. Use o e-mail do próprio cliente. Cada e-mail só pode ser usado com um CPF. Sem o sinal `+`. Máx. 254 caracteres. format: email maxLength: 254 pattern: ^[^+]*$ example: ana@exemplo.com.br phone: type: string description: Celular brasileiro com DDD e código do país, como `+5511987654321`. example: '+5511987654321' address: $ref: '#/components/schemas/AddressRequest' description: Endereço do representante legal. Address: type: object description: Endereço do titular. As 7 chaves sempre vêm; sem dados, todas `null`. required: - cep - street - number - complement - neighborhood - city - state properties: cep: type: - string - 'null' description: CEP, 8 dígitos, só números. example: '01310100' street: type: - string - 'null' description: Nome da rua ou avenida. example: Rua das Flores number: type: - string - 'null' description: Número do endereço. example: '123' complement: type: - string - 'null' description: Complemento do endereço. neighborhood: type: - string - 'null' description: Bairro. example: Centro city: type: - string - 'null' description: Cidade. example: São Paulo state: type: - string - 'null' description: Sigla da UF, como `SP`. example: SP headers: Location: description: Caminho para consultar o protocolo criado. schema: type: string example: /api/v2/partners/protocols/CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y PollAfter: description: Segundos para esperar antes de consultar o protocolo, sempre 5. schema: type: integer example: 5 IdempotentReplayed: description: Indica que a API reconheceu um reenvio da mesma chamada. schema: type: string enum: - 'true' XRequestId: description: Identificador da chamada. Informe-o ao suporte se precisar de ajuda. schema: type: string example: 01K7Q4A1B2C3D4E5F6G7H8J9KM WWWAuthenticate: description: Esquema de autenticação, sempre `Bearer`. schema: type: string example: Bearer RetryAfterRateLimit: description: Segundos para aguardar antes de tentar de novo, de 1 a 60. schema: type: integer minimum: 1 maximum: 60 example: 60 RetryAfterUnavailable: description: Segundos para aguardar antes de tentar de novo, sempre 30. schema: type: integer example: 30 responses: Unauthorized: description: >- Chave de API ausente, inválida ou revogada. Veja o que fazer em [Erros](/erros). headers: WWW-Authenticate: $ref: '#/components/headers/WWWAuthenticate' X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: type: object required: - type - status - code - message - retryable - request_id properties: code: type: string description: >- Código do erro. Veja como corrigir em [Erros](/erros). | Valor | Significado | | --- | --- | | `missing_or_invalid_authorization` | O header `Authorization` não veio ou não está no formato `Bearer `. | | `invalid_api_key` | A API key informada não existe. | | `api_key_revoked` | A API key informada foi revogada. | enum: - missing_or_invalid_authorization - invalid_api_key - api_key_revoked message: type: string description: Mensagem em português sobre o erro. example: Erro de validação no corpo da requisição. retryable: type: boolean description: '`true` quando vale reenviar a mesma chamada.' example: false status: type: integer description: Status HTTP da resposta. example: 400 type: type: string description: URL da página do erro. format: uri example: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: type: string description: Identificador da chamada, igual ao header `X-Request-Id`. example: 01K7Q4A1B2C3D4E5F6G7H8J9KM examples: Chave de API não enviada ou fora do formato: summary: Chave de API não enviada ou fora do formato value: code: missing_or_invalid_authorization message: Header Authorization ausente ou malformado. retryable: false status: 401 type: >- https://docs.certificados.zapsign.com.br/erros/missing_or_invalid_authorization request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM Chave de API inválida: summary: Chave de API inválida value: code: invalid_api_key message: API key inválida. retryable: false status: 401 type: https://docs.certificados.zapsign.com.br/erros/invalid_api_key request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM Chave de API revogada: summary: Chave de API revogada value: code: api_key_revoked message: API key revogada. retryable: false status: 401 type: https://docs.certificados.zapsign.com.br/erros/api_key_revoked request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM PaymentRequired: description: >- Saldo insuficiente para criar o protocolo. Veja o que fazer em [Erros](/erros). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: type: object required: - type - status - code - message - retryable - request_id properties: code: type: string description: >- Código do erro. Veja como corrigir em [Erros](/erros). | Valor | Significado | | --- | --- | | `insufficient_credits` | O saldo é menor que 1 certificado. | enum: - insufficient_credits message: type: string description: Mensagem em português sobre o erro. example: Erro de validação no corpo da requisição. retryable: type: boolean description: '`true` quando vale reenviar a mesma chamada.' example: false status: type: integer description: Status HTTP da resposta. example: 400 type: type: string description: URL da página do erro. format: uri example: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: type: string description: Identificador da chamada, igual ao header `X-Request-Id`. example: 01K7Q4A1B2C3D4E5F6G7H8J9KM examples: Saldo insuficiente para criar o protocolo: summary: Saldo insuficiente para criar o protocolo value: code: insufficient_credits message: >- Créditos insuficientes. Compre créditos para criar o protocolo. retryable: false status: 402 type: >- https://docs.certificados.zapsign.com.br/erros/insufficient_credits request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM ConflictCreate: description: >- A chave já foi usada com outro body, ou o `external_id` já pertence a outro protocolo. Veja o que fazer em [Erros](/erros). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: type: object required: - type - status - code - message - retryable - request_id properties: code: type: string description: >- Código do erro. Veja como corrigir em [Erros](/erros). | Valor | Significado | | --- | --- | | `idempotency_conflict` | A `Idempotency-Key` já foi usada com outro body. | | `external_id_taken` | O `external_id` já pertence a outro protocolo. | enum: - idempotency_conflict - external_id_taken message: type: string description: Mensagem em português sobre o erro. example: Erro de validação no corpo da requisição. retryable: type: boolean description: '`true` quando vale reenviar a mesma chamada.' example: false protocol_id: type: string description: Protocolo que já usa o `external_id`. example: CPR_01K7Q3Y4K9B6G9T30H539D34D6 status: type: integer description: Status HTTP da resposta. example: 400 type: type: string description: URL da página do erro. format: uri example: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: type: string description: Identificador da chamada, igual ao header `X-Request-Id`. example: 01K7Q4A1B2C3D4E5F6G7H8J9KM examples: Chave de idempotência já usada com outros dados: summary: Chave de idempotência já usada com outros dados value: code: idempotency_conflict message: >- Esta Idempotency-Key já foi usada com outro corpo. Use uma nova chave. retryable: false status: 409 type: >- https://docs.certificados.zapsign.com.br/erros/idempotency_conflict request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM Identificador do pedido já usado em outro protocolo: summary: Identificador do pedido já usado em outro protocolo value: code: external_id_taken message: >- Este external_id já pertence a outro protocolo. Consulte o protocolo informado. retryable: false protocol_id: CPR_01K7Q3Y4K9B6G9T30H539D34D6 status: 409 type: >- https://docs.certificados.zapsign.com.br/erros/external_id_taken request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM UnprocessableEntity: description: >- Body válido, mas o protocolo não pode ser criado. Veja o que fazer em [Erros](/erros). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: type: object required: - type - status - code - message - retryable - request_id properties: code: type: string description: >- Código do erro. Veja como corrigir em [Erros](/erros). | Valor | Significado | | --- | --- | | `certificate_combination_not_supported` | Essa combinação de tipo, modelo e validade de certificado não existe. | | `video_not_eligible` | O titular não pode emitir por videoconferência. | | `official_data_unavailable` | Não foi possível obter o nome do titular agora. | | `holder_email_in_use` | O e-mail já está vinculado a outro CPF. Cada e-mail só pode ser usado com um CPF. | enum: - certificate_combination_not_supported - video_not_eligible - official_data_unavailable - holder_email_in_use message: type: string description: Mensagem em português sobre o erro. example: Erro de validação no corpo da requisição. retryable: type: boolean description: '`true` quando vale reenviar a mesma chamada.' example: false field_errors: type: array description: Campos que precisam de correção. items: $ref: '#/components/schemas/FieldError' reason: $ref: '#/components/schemas/VideoNotEligibleReason' status: type: integer description: Status HTTP da resposta. example: 400 type: type: string description: URL da página do erro. format: uri example: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: type: string description: Identificador da chamada, igual ao header `X-Request-Id`. example: 01K7Q4A1B2C3D4E5F6G7H8J9KM examples: Certificado não disponível nessa combinação: summary: Certificado não disponível nessa combinação value: code: certificate_combination_not_supported message: >- Combinação de certificado inexistente. Use um produto de /protocol-products. retryable: false field_errors: - field: certificate message: Use um produto de /protocol-products. status: 422 type: >- https://docs.certificados.zapsign.com.br/erros/certificate_combination_not_supported request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM Titular não pode fazer a videoconferência: summary: Titular não pode fazer a videoconferência value: code: video_not_eligible message: >- CPF e data de nascimento não conferem. Confira os dados informados. retryable: false reason: identity_not_confirmed status: 422 type: >- https://docs.certificados.zapsign.com.br/erros/video_not_eligible request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM Nome do titular não encontrado na consulta oficial: summary: Nome do titular não encontrado na consulta oficial value: code: official_data_unavailable message: >- A consulta oficial não retornou o nome do titular. O protocolo não foi criado. retryable: false status: 422 type: >- https://docs.certificados.zapsign.com.br/erros/official_data_unavailable request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM E-mail do titular vinculado a outro CPF (e-CPF): summary: E-mail do titular vinculado a outro CPF (e-CPF) value: code: holder_email_in_use message: >- Este e-mail já está vinculado a outro CPF. Cada CPF precisa de um e-mail próprio. Use outro e-mail. retryable: false field_errors: - field: customer.email message: >- Este e-mail já está vinculado a outro CPF. Cada CPF precisa de um e-mail próprio. Use outro e-mail. status: 422 type: >- https://docs.certificados.zapsign.com.br/erros/holder_email_in_use request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM E-mail do representante vinculado a outro CPF (e-CNPJ): summary: E-mail do representante vinculado a outro CPF (e-CNPJ) value: code: holder_email_in_use message: >- Este e-mail já está vinculado a outro CPF. Cada CPF precisa de um e-mail próprio. Use outro e-mail. retryable: false field_errors: - field: customer.representative.email message: >- Este e-mail já está vinculado a outro CPF. Cada CPF precisa de um e-mail próprio. Use outro e-mail. status: 422 type: >- https://docs.certificados.zapsign.com.br/erros/holder_email_in_use request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM TooManyRequests: description: >- Limite de chamadas excedido. Espere os segundos indicados em `Retry-After`. Veja o que fazer em [Erros](/erros). headers: Retry-After: $ref: '#/components/headers/RetryAfterRateLimit' X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: type: object required: - type - status - code - message - retryable - request_id properties: code: type: string description: >- Código do erro. Veja como corrigir em [Erros](/erros). | Valor | Significado | | --- | --- | | `rate_limited` | Você enviou chamadas demais em pouco tempo. | enum: - rate_limited message: type: string description: Mensagem em português sobre o erro. example: Erro de validação no corpo da requisição. retryable: type: boolean description: '`true` quando vale reenviar a mesma chamada.' example: false status: type: integer description: Status HTTP da resposta. example: 400 type: type: string description: URL da página do erro. format: uri example: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: type: string description: Identificador da chamada, igual ao header `X-Request-Id`. example: 01K7Q4A1B2C3D4E5F6G7H8J9KM examples: Muitas chamadas em pouco tempo: summary: Muitas chamadas em pouco tempo value: code: rate_limited message: Limite de requisições excedido. retryable: true status: 429 type: https://docs.certificados.zapsign.com.br/erros/rate_limited request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM InternalError: description: Erro inesperado no servidor. Veja o que fazer em [Erros](/erros). headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: type: object required: - type - status - code - message - retryable - request_id properties: code: type: string description: |- Código do erro. Veja como corrigir em [Erros](/erros). | Valor | Significado | | --- | --- | | `internal_error` | Ocorreu um erro inesperado no servidor. | enum: - internal_error message: type: string description: Mensagem em português sobre o erro. example: Erro de validação no corpo da requisição. retryable: type: boolean description: '`true` quando vale reenviar a mesma chamada.' example: false status: type: integer description: Status HTTP da resposta. example: 400 type: type: string description: URL da página do erro. format: uri example: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: type: string description: Identificador da chamada, igual ao header `X-Request-Id`. example: 01K7Q4A1B2C3D4E5F6G7H8J9KM examples: Erro inesperado no servidor: summary: Erro inesperado no servidor value: code: internal_error message: Erro interno do servidor. retryable: true status: 500 type: https://docs.certificados.zapsign.com.br/erros/internal_error request_id: 01K7Q4A1B2C3D4E5F6G7H8J9KM ServiceUnavailable: description: >- Serviço temporariamente indisponível. Espere os segundos indicados em `Retry-After` e tente de novo. Veja o que fazer em [Erros](/erros). headers: Retry-After: $ref: '#/components/headers/RetryAfterUnavailable' X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/problem+json: schema: type: object required: - type - status - code - message - retryable - request_id properties: code: type: string description: >- Código do erro. Veja como corrigir em [Erros](/erros). | Valor | Significado | | --- | --- | | `service_unavailable` | O serviço está temporariamente indisponível. | enum: - service_unavailable message: type: string description: Mensagem em português sobre o erro. example: Erro de validação no corpo da requisição. retryable: type: boolean description: '`true` quando vale reenviar a mesma chamada.' example: false status: type: integer description: Status HTTP da resposta. example: 400 type: type: string description: URL da página do erro. format: uri example: >- https://docs.certificados.zapsign.com.br/erros/validation_error request_id: type: string description: Identificador da chamada, igual ao header `X-Request-Id`. example: 01K7Q4A1B2C3D4E5F6G7H8J9KM examples: Serviço temporariamente indisponível: summary: Serviço temporariamente indisponível value: code: service_unavailable message: Serviço temporariamente indisponível. retryable: true status: 503 type: >- https://docs.certificados.zapsign.com.br/erros/service_unavailable request_id: 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.