Índice da API
GET
/api/v1Escopo:
sem chaveLista as rotas, as regras de paginação e de escrita. Não exige chave.
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | Indice | Índice. |
Documentação · versão 1.0.1
API do CardSign
API REST do CardSign para criar, enviar e acompanhar documentos para assinatura eletrônica a partir do seu sistema, baixar o PDF final selado, a trilha de auditoria e o pacote de provas, e receber webhooks assinados a cada passo.
- Base:
https://cardsign.gopixeltecnologiaa.com.br/api/v1 - Formato: JSON UTF-8; datas ISO 8601 em UTC; ids são UUID.
- Limite: 120 chamadas por minuto por chave (acima disso,
429comretry-after). - Escrita: todo
POSTexige o cabeçalhoIdempotency-Key.
GET /api/v1200
{
"api": "CardSign",
"versao": "v1",
"documentacao": "https://cardsign.gopixeltecnologiaa.com.br/docs/api",
"rotas": [
"GET /api/v1/eu",
"GET /api/v1/empresas",
"GET /api/v1/modelos",
"GET /api/v1/pastas",
"GET /api/v1/envelopes"
]
}Autorização
Toda chamada leva a chave no cabeçalho Authorization: Bearer cs_<prefixo>_<segredo>. A chave é criada em Configurações › API e mostrada uma única vez; o CardSign guarda só o SHA-256 dela.
A chave age em nome de quem a criou: em cada chamada valem as permissões que essa pessoa tem agora no painel, empresa por empresa. Cada rota exige um escopo (x-escopo em cada operação), e cada escopo exige uma permissão do painel de quem criou a chave.
Tirar a permissão no painel leva a chave junto em até 30 s. A chave pode ter validade e lista de IPs permitidos (IPv4 ou CIDR).
Cabeçalho de autorização
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorization | string | Bearer cs_<prefixo>_<segredo> — prefixo de 8 caracteres [a-z0-9] e segredo de 40 [A-Za-z0-9]. |
Escopos
| Escopo | Permissão do painel | Libera |
|---|---|---|
documentos:ler | docs.ver | Listar e consultar documentos e envelopes. |
documentos:baixar | docs.baixar | Baixar o PDF final selado. |
trilha:ler | audit.trilha | Ler a trilha de auditoria. |
envelopes:criar | docs.criar | Criar e montar rascunhos (arquivos, pessoas, campos). |
envelopes:enviar | docs.enviar | Enviar para assinatura. |
envelopes:gerir | docs.cancelar | Cancelar, pausar, retomar, lembrar; receber links de assinatura. |
provas:baixar | docs.baixar | Baixar o pacote de provas (ZIP). |
webhooks:gerir | org.api | Cadastrar e gerir webhooks. |
modelos:ler | docs.ver | Listar modelos de documento. |
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/eu" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Sem chave401
{
"erro": {
"codigo": "sem_chave",
"mensagem": "Envie a chave no cabeçalho Authorization: Bearer cs_…"
}
}Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1"Exemplo Resposta200
{
"api": "CardSign",
"versao": "v1",
"documentacao": "https://cardsign.gopixeltecnologiaa.com.br/docs/api",
"rotas": [
"GET /api/v1/documentos",
"POST /api/v1/envelopes",
"GET /api/v1/envelopes/{id}"
],
"paginacao": {
"cursor": "Use \"depois\" com o valor de \"proximo\" da resposta anterior (ou siga \"proxima_url\"); \"proximo\" null = acabou.",
"limite": "\"limite\" de 1 a 200 (padrão 50)."
},
"escrita": "Todo POST exige o cabeçalho Idempotency-Key (1 a 200 caracteres): a mesma chave com o mesmo corpo em 24 h devolve a mesma resposta.",
"cache": "Permissões de quem criou a chave são conferidas no banco e guardadas por até 30 s."
}Quem sou eu
GET
/api/v1/euEscopo:
qualquer chave válidaA chave (escopos, validade), o grupo e as empresas em que ela age (união de todos os escopos), e o limite por minuto. Bom para testar a chave.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | Eu | A chave e o alcance dela. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/eu" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"chave": {
"id": "0e1d2c3b-4a59-4687-9a8b-7c6d5e4f3a2b",
"prefixo": "a1b2c3d4",
"nome": "Programa DIAS — produção",
"expira_em": "2027-10-20T02:59:59.000Z",
"escopos": [
"documentos:ler",
"documentos:baixar",
"trilha:ler",
"envelopes:criar",
"envelopes:enviar",
"envelopes:gerir",
"provas:baixar",
"webhooks:gerir"
]
},
"grupo": {
"id": "9a2e7c41-5d3b-4e8f-b1a6-7c0d2f9e8b13",
"nome": "Grupo Dias"
},
"empresas": [
{
"id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"nome": "Clínica Dias Saúde Ocupacional",
"cnpj": "12345678000190"
},
{
"id": "4a7d2e3b-9c5f-4a2b-8d8e-3f6c9b2a5d01",
"nome": "Clínica Dias Ipatinga",
"cnpj": "12345678000271"
}
],
"limite_por_minuto": 120
}Empresas da chave
GET
/api/v1/empresasEscopo:
qualquer chave válidaEmpresas do grupo em que a chave age (para qualquer um dos escopos dela), por nome.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | objeto | Lista de empresas. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/empresas" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"empresas": [
{
"id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"nome": "Clínica Dias Saúde Ocupacional",
"cnpj": "12345678000190"
},
{
"id": "4a7d2e3b-9c5f-4a2b-8d8e-3f6c9b2a5d01",
"nome": "Clínica Dias Ipatinga",
"cnpj": "12345678000271"
}
]
}Modelos de documento
GET
/api/v1/modelosEscopo:
modelos:lerModelos não arquivados das empresas liberadas (somente leitura; criar documento a partir de modelo fica para uma próxima versão).
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | objeto | Lista de modelos. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/modelos" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"modelos": [
{
"id": "2b7e9c4d-1f3a-4b5c-8d6e-9f0a1b2c3d4e",
"nome": "Termo de ciência de POP",
"tipo_id": "6d1c8e2f-4a5b-4c3d-9e8f-0a1b2c3d4e5f",
"versao": 3,
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"status": "ativo"
}
]
}Pastas
GET
/api/v1/pastasEscopo:
documentos:lerAs pastas das empresas liberadas, com o caminho completo. Serve para o seu sistema ligar cada pasta do CardSign a uma pasta dele (o envelope traz pasta.id). ?empresa_id= filtra uma empresa.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
empresa_idquery | string (uuid) |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | objeto | Lista de pastas. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/pastas" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"pastas": [
{
"id": "7a1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"pai_id": null,
"codigo": "01",
"nome": "Recursos Humanos",
"caminho": "Recursos Humanos"
}
]
}Primeiros passos
- Peça a um administrador uma chave da API em Conta › API e chaves do CardSign, com os escopos de que a integração precisa. Guarde-a num cofre de segredos: ela só aparece uma vez.
- Teste a chave com
GET /eu: a resposta traz os escopos e as empresas em que ela age (use oidde uma delas comoempresa_id). - Crie o envelope com
POST /envelopes— PDF por URL, base64 ou multipart, as pessoas e os campos. Ele nasce comorascunho. - Envie com
POST /envelopes/{id}/enviar. Os convites saem por e-mail, WhatsApp ou SMS (ou peça os links comdevolver_links). - Cadastre um webhook para saber de cada assinatura e da conclusão, e baixe o PDF final com
GET /envelopes/{id}/pdf. Quer testar sem código? Use a coleção Postman abaixo.
Do zero ao PDF assinado (cURL)
export CARDSIGN_CHAVE="cs_a1b2c3d4_…" # Conta › API e chaves
export API="https://cardsign.gopixeltecnologiaa.com.br/api/v1"
# 1. Teste a chave e pegue o id da empresa
curl -s "$API/eu" -H "Authorization: Bearer $CARDSIGN_CHAVE"
# 2. Crie o rascunho (PDF por URL; também aceita base64 ou multipart)
curl -s -X POST "$API/envelopes" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: dias-4821-criar" \
-H "Content-Type: application/json" \
-d '{
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"titulo": "POP 014 — Higienização das mãos",
"external_id": "dias:pop:4821",
"arquivos": [{"nome": "pop-014.pdf", "url": "https://seu-sistema.com.br/pop-014.pdf"}],
"signatarios": [{"nome": "Mariana Costa Ribeiro", "email": "[email protected]"}]
}'
# 3. Envie para assinatura (id = "id" da resposta anterior)
curl -s -X POST "$API/envelopes/$ID/enviar" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: dias-4821-enviar"
# 4. Acompanhe por webhook (envelope.concluido) ou consulte
curl -s "$API/envelopes/$ID" -H "Authorization: Bearer $CARDSIGN_CHAVE"
# 5. Concluído: baixe o PDF final selado
curl -s "$API/envelopes/$ID/pdf" -H "Authorization: Bearer $CARDSIGN_CHAVE"Envelopes
Um envelope é o documento a assinar: um ou mais PDFs, as pessoas (signatários) e os campos de cada uma. Ele nasce como rascunho, vai para andamento ao ser enviado e termina como concluido, cancelado, expirado ou recusado (pausado é temporário).
Criar envelope
POST
/api/v1/envelopesEscopo:
envelopes:criarExige Idempotency-KeyCria o rascunho completo (arquivos, pessoas e campos) ou nada. Aceita JSON ou multipart/form-data (campo dados com o JSON e arquivo repetido com os PDFs). Depois, envie com POST /envelopes/{id}/enviar. external_id repetido para a mesma chave → 409 external_id_em_uso, com o envelope_id existente em detalhes.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Content-Type | string | application/json multipart/form-data |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
empresa_idobrigatório | string (uuid) | Empresa liberada para envelopes:criar. |
tituloobrigatório | string | (3 a 200 caracteres) |
external_id | string | null | Seu identificador; repetido para a mesma chave → 409. (1 a 200 caracteres) |
external_ref | objeto | null | Dados livres (até 4 KB) |
prazo | string | null | AAAA-MM-DD (23:59 de Brasília) ou ISO 8601; no futuro. (até 40 caracteres) |
mensagem | string | null | Vai no convite. (até 2000 caracteres) |
assinatura_como | cpf | cnpj | misto | cpf (padrão): todo signatário precisa de CPF. cnpj: cada um assina em nome de uma empresa (CPF e CNPJ). misto: sem exigência fixa; o nível qualificado continua exigindo CPF e certificado. (padrão "cpf") |
arquivos | array de ArquivoEntrada | (até 20 itens) |
arquivos[].nomeobrigatório | string | Nome do arquivo (".pdf" é acrescentado se faltar). (1 a 200 caracteres) [Por URL] · Em base64 |
arquivos[].urlobrigatório | string (uri) | https pública; sem redirecionamento. (até 2000 caracteres) [Por URL] |
arquivos[].base64obrigatório | string | Conteúdo do PDF em base64. (8 a 28000000 caracteres) [Em base64] |
signatarios | array de SignatarioEntrada | (até 50 itens) |
signatarios[].nomeobrigatório | string | (2 a 200 caracteres) |
signatarios[].funcao | assinar | aprovar | testemunha | observador | (padrão "assinar") |
signatarios[].ordem | integer | Padrão: a posição na lista. Mesma ordem = em paralelo. (de 1 a 50) |
signatarios[].canal | whatsapp | sms | email | link | Por onde vai o convite. Com |
signatarios[].email | string (email) | null | Obrigatório para enviar (exceto observador): o código de confirmação segue por e-mail. (até 200 caracteres) |
signatarios[].telefone | string | null | Com |
signatarios[].cpf | string | null | Com ou sem pontuação; 11 dígitos. (até 20 caracteres) |
signatarios[].nivel | simples | avancada | qualificada | (padrão "avancada") |
signatarios[].campos | array de CampoPosicao ou CampoAncora | Sem campos, quem assina ganha uma caixa automática na última página. (até 50 itens) |
signatarios[].campos[].tipoobrigatório | assinatura | rubrica | data | nome | cpf | [Por posição] · Por âncora |
signatarios[].campos[].arquivo | integer | Índice do arquivo no envelope (1 = primeiro). (de 1 a 20; padrão 1) [Por posição] |
signatarios[].campos[].paginaobrigatório | integer | (de 1 a 5000) [Por posição] |
signatarios[].campos[].xobrigatório | number | (de 0 a 100) [Por posição] |
signatarios[].campos[].yobrigatório | number | (de 0 a 100) [Por posição] |
signatarios[].campos[].larguraobrigatório | number | [Por posição] · Por âncora |
signatarios[].campos[].alturaobrigatório | number | [Por posição] · Por âncora |
signatarios[].campos[].ancoraobrigatório | string | (2 a 100 caracteres) [Por âncora] |
signatarios[].campos[].deslocamento_x | number | % da página a partir do início do texto. (de -100 a 100) [Por âncora] |
signatarios[].campos[].deslocamento_y | number | (de -100 a 100) [Por âncora] |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
201 | Envelope | Rascunho criado. |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
409 | Erro |
|
413 | Erro |
|
415 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-criarEnvelope-123" \
-H "Content-Type: application/json" \
-d '{
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"external_id": "dias:pop:4821",
"external_ref": {
"origem": "programa-dias",
"pop": "014",
"turma": "2026-10"
},
"prazo": "2026-10-30",
"mensagem": "Olá! Leia o POP de higienização das mãos e assine a ciência até sexta.",
"arquivos": [
{
"nome": "POP-014-higienizacao-das-maos.pdf",
"url": "https://treinamento.gopixeltecnologia.com/arquivos/pop-014.pdf"
}
],
"signatarios": [
{
"nome": "Mariana Costa Ribeiro",
"email": "[email protected]",
"cpf": "52998224725",
"canal": "email",
"nivel": "avancada",
"campos": [
{
"tipo": "assinatura",
"ancora": "{{assinatura:1}}"
}
]
},
{
"nome": "Rafael Almeida Pinto",
"funcao": "testemunha",
"ordem": 2,
"canal": "whatsapp",
"email": "[email protected]",
"telefone": "+55 31 99876-5432"
}
]
}'Exemplo Resposta201
{
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"status": "rascunho",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"external_id": "dias:pop:4821",
"external_ref": {
"origem": "programa-dias",
"pop": "014",
"turma": "2026-10"
},
"origem": "api",
"prazo": "2026-10-31T02:59:00+00:00",
"mensagem": "Olá! Leia o POP de higienização das mãos e assine a ciência até sexta.",
"criado_em": "2026-10-19T13:42:07.481233+00:00",
"concluido_em": null,
"motivo_cancelamento": null,
"arquivos": [
{
"id": "2c8d5e1f-3a4b-4c6d-9e7f-8a9b0c1d2e3f",
"nome": "POP-014-higienizacao-das-maos.pdf",
"sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
"paginas": 3,
"ordem": 1
}
],
"signatarios": [
{
"id": "4d9e6f2a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
"nome": "Mariana Costa Ribeiro",
"funcao": "assinar",
"ordem": 1,
"canal": "email",
"nivel": "avancada",
"status": "aguardando",
"email_mascarado": "m***@clinicadias.com.br",
"telefone_mascarado": null,
"assinado_em": null,
"motivo_recusa": null
},
{
"id": "5e0f7a3b-2c4d-4e6f-9a0b-1c2d3e4f5a6b",
"nome": "Rafael Almeida Pinto",
"funcao": "testemunha",
"ordem": 2,
"canal": "whatsapp",
"nivel": "avancada",
"status": "aguardando",
"email_mascarado": "r***@clinicadias.com.br",
"telefone_mascarado": "+55 31 9****-5432",
"assinado_em": null,
"motivo_recusa": null
}
],
"pdfs_finais": []
}Consultar envelope
GET
/api/v1/envelopes/{id}Escopo:
documentos:lerO envelope completo (rascunho incluído) — situação, arquivos, pessoas (contato mascarado) e PDFs finais com o link de verificação.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | Envelope | O envelope. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"status": "concluido",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"external_id": "dias:pop:4821",
"external_ref": {
"origem": "programa-dias",
"pop": "014",
"turma": "2026-10"
},
"origem": "api",
"prazo": "2026-10-31T02:59:00+00:00",
"mensagem": "Olá! Leia o POP de higienização das mãos e assine a ciência até sexta.",
"criado_em": "2026-10-19T13:42:07.481233+00:00",
"concluido_em": "2026-10-20T11:05:31.204118+00:00",
"motivo_cancelamento": null,
"arquivos": [
{
"id": "2c8d5e1f-3a4b-4c6d-9e7f-8a9b0c1d2e3f",
"nome": "POP-014-higienizacao-das-maos.pdf",
"sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
"paginas": 3,
"ordem": 1
}
],
"signatarios": [
{
"id": "4d9e6f2a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
"nome": "Mariana Costa Ribeiro",
"funcao": "assinar",
"ordem": 1,
"canal": "email",
"nivel": "avancada",
"status": "assinou",
"email_mascarado": "m***@clinicadias.com.br",
"telefone_mascarado": null,
"assinado_em": "2026-10-20T10:58:12.903311+00:00",
"motivo_recusa": null
},
{
"id": "5e0f7a3b-2c4d-4e6f-9a0b-1c2d3e4f5a6b",
"nome": "Rafael Almeida Pinto",
"funcao": "testemunha",
"ordem": 2,
"canal": "whatsapp",
"nivel": "avancada",
"status": "assinou",
"email_mascarado": "r***@clinicadias.com.br",
"telefone_mascarado": "+55 31 9****-5432",
"assinado_em": "2026-10-20T11:05:29.118024+00:00",
"motivo_recusa": null
}
],
"pdfs_finais": [
{
"nome": "POP-014-higienizacao-das-maos-assinado.pdf",
"sha256": "8e3b1f0c9d2a47b6e5f4c3d2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e",
"criado_em": "2026-10-20T11:05:40.552910+00:00",
"verificar": "https://cardsign.gopixeltecnologiaa.com.br/verificar?h=8e3b1f0c9d2a47b6e5f4c3d2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e"
}
]
}Editar rascunho
PATCH
/api/v1/envelopes/{id}Escopo:
envelopes:criarSó no rascunho. Envie ao menos um de titulo, prazo (AAAA-MM-DD = 23:59 de Brasília, ou ISO 8601) e mensagem.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Content-Type | string | application/json |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
titulo | string | (3 a 200 caracteres) |
prazo | string | null | AAAA-MM-DD ou ISO 8601; null tira o prazo. (até 40 caracteres) |
mensagem | string | null | (até 2000 caracteres) |
assinatura_como | cpf | cnpj | misto | — |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | Envelope | O envelope atualizado. |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
415 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X PATCH "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"titulo": "POP 014 — Higienização das mãos (revisão 2)",
"prazo": "2026-11-07"
}'Exemplo Resposta200
{
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"status": "rascunho",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"external_id": "dias:pop:4821",
"external_ref": {
"origem": "programa-dias",
"pop": "014",
"turma": "2026-10"
},
"origem": "api",
"prazo": "2026-10-31T02:59:00+00:00",
"mensagem": "Olá! Leia o POP de higienização das mãos e assine a ciência até sexta.",
"criado_em": "2026-10-19T13:42:07.481233+00:00",
"concluido_em": null,
"motivo_cancelamento": null,
"arquivos": [
{
"id": "2c8d5e1f-3a4b-4c6d-9e7f-8a9b0c1d2e3f",
"nome": "POP-014-higienizacao-das-maos.pdf",
"sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
"paginas": 3,
"ordem": 1
}
],
"signatarios": [
{
"id": "4d9e6f2a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
"nome": "Mariana Costa Ribeiro",
"funcao": "assinar",
"ordem": 1,
"canal": "email",
"nivel": "avancada",
"status": "aguardando",
"email_mascarado": "m***@clinicadias.com.br",
"telefone_mascarado": null,
"assinado_em": null,
"motivo_recusa": null
},
{
"id": "5e0f7a3b-2c4d-4e6f-9a0b-1c2d3e4f5a6b",
"nome": "Rafael Almeida Pinto",
"funcao": "testemunha",
"ordem": 2,
"canal": "whatsapp",
"nivel": "avancada",
"status": "aguardando",
"email_mascarado": "r***@clinicadias.com.br",
"telefone_mascarado": "+55 31 9****-5432",
"assinado_em": null,
"motivo_recusa": null
}
],
"pdfs_finais": []
}Arquivos
PDFs do envelope (até 20 MB cada, 20 por envelope). Mande por URL https pública (o CardSign baixa, sem seguir redirecionamento), em base64 ou como multipart (arquivo). O servidor confere a assinatura %PDF, conta as páginas e calcula o SHA-256.
Adicionar arquivo
POST
/api/v1/envelopes/{id}/arquivosEscopo:
envelopes:criarExige Idempotency-KeySó no rascunho. Um PDF por chamada — JSON {nome, url} ou {nome, base64}, ou multipart com o campo arquivo.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Content-Type | string | application/json multipart/form-data |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
nomeobrigatório | string | Nome do arquivo (".pdf" é acrescentado se faltar). (1 a 200 caracteres) [Por URL] · Em base64 |
urlobrigatório | string (uri) | https pública; sem redirecionamento. (até 2000 caracteres) [Por URL] |
base64obrigatório | string | Conteúdo do PDF em base64. (8 a 28000000 caracteres) [Em base64] |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
201 | Arquivo | Arquivo guardado. |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
413 | Erro |
|
415 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/arquivos" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-adicionarArquivo-123" \
-H "Content-Type: application/json" \
-d '{
"nome": "Anexo-I-checklist.pdf",
"base64": "JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAuLi4="
}'Exemplo Resposta201
{
"id": "9d4e1f6a-2b3c-4d5e-8f9a-1b2c3d4e5f60",
"nome": "Anexo-I-checklist.pdf",
"sha256": "4f1c9a2b7d3e8f60a1b2c3d4e5f60718293a4b5c6d7e8f9012a3b4c5d6e7f809",
"paginas": 1,
"ordem": 2
}Signatários
Pessoas do envelope. Campos por posição (em % da página, y a partir do topo) ou por âncora (texto procurado nos PDFs, mesmo invisível; cada ocorrência vira um campo). Quem assina sem campos ganha uma caixa de assinatura automática na última página (até 30 pessoas, empilhadas por ordem).
Adicionar signatário
POST
/api/v1/envelopes/{id}/signatariosEscopo:
envelopes:criarExige Idempotency-KeySó no rascunho. Mesmo formato de cada item de signatarios em POST /envelopes. Sem ordem, entra no fim.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Content-Type | string | application/json |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
nomeobrigatório | string | (2 a 200 caracteres) |
funcao | assinar | aprovar | testemunha | observador | (padrão "assinar") |
ordem | integer | Padrão: a posição na lista. Mesma ordem = em paralelo. (de 1 a 50) |
canal | whatsapp | sms | email | link | Por onde vai o convite. Com |
email | string (email) | null | Obrigatório para enviar (exceto observador): o código de confirmação segue por e-mail. (até 200 caracteres) |
telefone | string | null | Com |
cpf | string | null | Com ou sem pontuação; 11 dígitos. (até 20 caracteres) |
nivel | simples | avancada | qualificada | (padrão "avancada") |
campos | array de CampoPosicao ou CampoAncora | Sem campos, quem assina ganha uma caixa automática na última página. (até 50 itens) |
campos[].tipoobrigatório | assinatura | rubrica | data | nome | cpf | [Por posição] · Por âncora |
campos[].arquivo | integer | Índice do arquivo no envelope (1 = primeiro). (de 1 a 20; padrão 1) [Por posição] |
campos[].paginaobrigatório | integer | (de 1 a 5000) [Por posição] |
campos[].xobrigatório | number | (de 0 a 100) [Por posição] |
campos[].yobrigatório | number | (de 0 a 100) [Por posição] |
campos[].larguraobrigatório | number | [Por posição] · Por âncora |
campos[].alturaobrigatório | number | [Por posição] · Por âncora |
campos[].ancoraobrigatório | string | (2 a 100 caracteres) [Por âncora] |
campos[].deslocamento_x | number | % da página a partir do início do texto. (de -100 a 100) [Por âncora] |
campos[].deslocamento_y | number | (de -100 a 100) [Por âncora] |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
201 | Signatario | A pessoa criada. |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
415 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/signatarios" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-adicionarSignatario-123" \
-H "Content-Type: application/json" \
-d '{
"nome": "Juliana Ferreira Lopes",
"funcao": "aprovar",
"canal": "email",
"email": "[email protected]",
"nivel": "simples",
"campos": [
{
"tipo": "assinatura",
"pagina": 1,
"x": 60,
"y": 82,
"largura": 26,
"altura": 7
},
{
"tipo": "data",
"arquivo": 1,
"pagina": 1,
"x": 60,
"y": 90,
"largura": 14,
"altura": 3.5
}
]
}'Exemplo Resposta201
{
"id": "6f1a8b4c-3d5e-4f7a-9b0c-2d3e4f5a6b7c",
"nome": "Juliana Ferreira Lopes",
"funcao": "aprovar",
"ordem": 3,
"canal": "email",
"nivel": "simples",
"status": "aguardando",
"email_mascarado": "j***@clinicadias.com.br",
"telefone_mascarado": null,
"assinado_em": null,
"motivo_recusa": null
}Remover signatário
DELETE
/api/v1/envelopes/{id}/signatarios/{sid}Escopo:
envelopes:criarSó no rascunho. Remove a pessoa e os campos dela.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
sidobrigatóriocaminho | string (uuid) | UUID do signatário. |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
204 | — | Removida (sem corpo). |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X DELETE "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/signatarios/5e0f7a3b-2c4d-4e6f-9a0b-1c2d3e4f5a6b" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta204
(sem corpo)Ações
Mudanças de situação do envelope. Todas passam pelas mesmas conferências do painel e ficam na trilha de auditoria.
Enviar envelope
POST
/api/v1/envelopes/{id}/enviarEscopo:
envelopes:enviarExige Idempotency-KeyAs mesmas conferências do painel (e-mail ou telefone de quem assina, campo de assinatura, CPF…; falhou → 422 regra_violada com a explicação) e os convites. Com {"devolver_links": true} e uma chave que também tem envelopes:gerir, a resposta traz links de quem está na vez, para abrir a assinatura no seu sistema (fica registrado na trilha).
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Content-Type | string | application/json |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
devolver_links | boolean | Devolve os links de assinatura (exige também envelopes:gerir). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | Envelope + objeto | Enviado. Com |
202 | Envelope | Guardado para revisão (chave com "Revisar no CardSign antes de enviar"). O documento continua em |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
415 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/enviar" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-enviarEnvelope-123" \
-H "Content-Type: application/json" \
-d '{
"devolver_links": true
}'Exemplo Resposta200
{
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"status": "andamento",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"external_id": "dias:pop:4821",
"external_ref": {
"origem": "programa-dias",
"pop": "014",
"turma": "2026-10"
},
"origem": "api",
"prazo": "2026-10-31T02:59:00+00:00",
"mensagem": "Olá! Leia o POP de higienização das mãos e assine a ciência até sexta.",
"criado_em": "2026-10-19T13:42:07.481233+00:00",
"concluido_em": null,
"motivo_cancelamento": null,
"arquivos": [
{
"id": "2c8d5e1f-3a4b-4c6d-9e7f-8a9b0c1d2e3f",
"nome": "POP-014-higienizacao-das-maos.pdf",
"sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
"paginas": 3,
"ordem": 1
}
],
"signatarios": [
{
"id": "4d9e6f2a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
"nome": "Mariana Costa Ribeiro",
"funcao": "assinar",
"ordem": 1,
"canal": "email",
"nivel": "avancada",
"status": "na_vez",
"email_mascarado": "m***@clinicadias.com.br",
"telefone_mascarado": null,
"assinado_em": null,
"motivo_recusa": null
},
{
"id": "5e0f7a3b-2c4d-4e6f-9a0b-1c2d3e4f5a6b",
"nome": "Rafael Almeida Pinto",
"funcao": "testemunha",
"ordem": 2,
"canal": "whatsapp",
"nivel": "avancada",
"status": "aguardando",
"email_mascarado": "r***@clinicadias.com.br",
"telefone_mascarado": "+55 31 9****-5432",
"assinado_em": null,
"motivo_recusa": null
}
],
"pdfs_finais": [],
"links": [
{
"signatario_id": "4d9e6f2a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
"url": "https://cardsign.gopixeltecnologiaa.com.br/assinar/EXEMPLO-token-de-assinatura",
"expira_em": "2026-10-31T02:59:00+00:00"
}
]
}Cancelar envelope
POST
/api/v1/envelopes/{id}/cancelarEscopo:
envelopes:gerirExige Idempotency-KeyExige motivo (5 a 500 caracteres), que vai para a trilha e para motivo_cancelamento.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Content-Type | string | application/json |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
motivoobrigatório | string | (5 a 500 caracteres) |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | Envelope | Cancelado. |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
415 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/cancelar" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-cancelarEnvelope-123" \
-H "Content-Type: application/json" \
-d '{
"motivo": "POP substituído pela revisão 2; nova ciência será enviada."
}'Exemplo Resposta200
{
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"status": "cancelado",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"external_id": "dias:pop:4821",
"external_ref": {
"origem": "programa-dias",
"pop": "014",
"turma": "2026-10"
},
"origem": "api",
"prazo": "2026-10-31T02:59:00+00:00",
"mensagem": null,
"criado_em": "2026-10-19T13:42:07.481233+00:00",
"concluido_em": null,
"motivo_cancelamento": "POP substituído pela revisão 2; nova ciência será enviada.",
"arquivos": [
{
"id": "2c8d5e1f-3a4b-4c6d-9e7f-8a9b0c1d2e3f",
"nome": "POP-014-higienizacao-das-maos.pdf",
"sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
"paginas": 3,
"ordem": 1
}
],
"signatarios": [
{
"id": "4d9e6f2a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
"nome": "Mariana Costa Ribeiro",
"funcao": "assinar",
"ordem": 1,
"canal": "email",
"nivel": "avancada",
"status": "aguardando",
"email_mascarado": "m***@clinicadias.com.br",
"telefone_mascarado": null,
"assinado_em": null,
"motivo_recusa": null
}
],
"pdfs_finais": []
}Pausar envelope
POST
/api/v1/envelopes/{id}/pausarEscopo:
envelopes:gerirExige Idempotency-KeySuspende as assinaturas de um envelope em andamento. Sem corpo.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | Envelope | Pausado. |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/pausar" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-pausarEnvelope-123"Exemplo Resposta200
{
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"status": "pausado",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"external_id": "dias:pop:4821",
"external_ref": {
"origem": "programa-dias",
"pop": "014",
"turma": "2026-10"
},
"origem": "api",
"prazo": "2026-10-31T02:59:00+00:00",
"mensagem": null,
"criado_em": "2026-10-19T13:42:07.481233+00:00",
"concluido_em": null,
"motivo_cancelamento": null,
"arquivos": [
{
"id": "2c8d5e1f-3a4b-4c6d-9e7f-8a9b0c1d2e3f",
"nome": "POP-014-higienizacao-das-maos.pdf",
"sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
"paginas": 3,
"ordem": 1
}
],
"signatarios": [
{
"id": "4d9e6f2a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
"nome": "Mariana Costa Ribeiro",
"funcao": "assinar",
"ordem": 1,
"canal": "email",
"nivel": "avancada",
"status": "na_vez",
"email_mascarado": "m***@clinicadias.com.br",
"telefone_mascarado": null,
"assinado_em": null,
"motivo_recusa": null
}
],
"pdfs_finais": []
}Retomar envelope
POST
/api/v1/envelopes/{id}/retomarEscopo:
envelopes:gerirExige Idempotency-KeyVolta um envelope pausado para andamento. Sem corpo.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | Envelope | Retomado. |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/retomar" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-retomarEnvelope-123"Exemplo Resposta200
{
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"status": "andamento",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"external_id": "dias:pop:4821",
"external_ref": {
"origem": "programa-dias",
"pop": "014",
"turma": "2026-10"
},
"origem": "api",
"prazo": "2026-10-31T02:59:00+00:00",
"mensagem": "Olá! Leia o POP de higienização das mãos e assine a ciência até sexta.",
"criado_em": "2026-10-19T13:42:07.481233+00:00",
"concluido_em": null,
"motivo_cancelamento": null,
"arquivos": [
{
"id": "2c8d5e1f-3a4b-4c6d-9e7f-8a9b0c1d2e3f",
"nome": "POP-014-higienizacao-das-maos.pdf",
"sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
"paginas": 3,
"ordem": 1
}
],
"signatarios": [
{
"id": "4d9e6f2a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
"nome": "Mariana Costa Ribeiro",
"funcao": "assinar",
"ordem": 1,
"canal": "email",
"nivel": "avancada",
"status": "na_vez",
"email_mascarado": "m***@clinicadias.com.br",
"telefone_mascarado": null,
"assinado_em": null,
"motivo_recusa": null
},
{
"id": "5e0f7a3b-2c4d-4e6f-9a0b-1c2d3e4f5a6b",
"nome": "Rafael Almeida Pinto",
"funcao": "testemunha",
"ordem": 2,
"canal": "whatsapp",
"nivel": "avancada",
"status": "aguardando",
"email_mascarado": "r***@clinicadias.com.br",
"telefone_mascarado": "+55 31 9****-5432",
"assinado_em": null,
"motivo_recusa": null
}
],
"pdfs_finais": [],
"links": [
{
"signatario_id": "4d9e6f2a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
"url": "https://cardsign.gopixeltecnologiaa.com.br/assinar/EXEMPLO-token-de-assinatura",
"expira_em": "2026-10-31T02:59:00+00:00"
}
]
}Lembrar quem assina
POST
/api/v1/envelopes/{id}/lembreteEscopo:
envelopes:gerirExige Idempotency-KeyGera link novo e reenvia o convite a quem está na vez, ou só à pessoa indicada em signatario_id. Só em andamento.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Content-Type | string | application/json |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
signatario_id | string (uuid) | Só esta pessoa (sem ele |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | objeto | Quantos convites saíram. |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
415 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/lembrete" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-lembrete-123" \
-H "Content-Type: application/json" \
-d '{
"signatario_id": "4d9e6f2a-1b3c-4d5e-8f9a-0b1c2d3e4f5a"
}'Exemplo Resposta200
{
"enviados": 1,
"nao_enviados": []
}Consultas, trilha, PDF e provas
Leitura: listas paginadas, detalhe, trilha de auditoria encadeada, PDF final selado e pacote de provas. Os links de download valem 5 minutos.
Listar envelopes
GET
/api/v1/envelopesEscopo:
documentos:lerEnvelopes das empresas liberadas, mais recentes primeiro (criado_em desc, id desc). Igual a GET /documentos, com external_id em cada item e o filtro external_id. Rascunhos só aparecem com status=rascunho.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
limitequery | integer | Itens por página, de 1 a 200. (de 1 a 200; padrão 50) |
depoisquery | string | Cursor — o valor de |
paginaquery | integer | Número da página (compatibilidade). Só até |
contarquery | 1 |
|
statusquery | rascunho | andamento | pausado | concluido | cancelado | expirado | recusado | Filtra pela situação. |
empresaquery | string (uuid) | UUID de uma empresa liberada. |
desdequery | string | Criados a partir de (AAAA-MM-DD = 00:00 de Brasília, ou ISO 8601). |
atequery | string | Criados antes de (AAAA-MM-DD = 00:00 de Brasília, ou ISO 8601). |
external_idquery | string | O |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | ListaEnvelopes | Uma página de envelopes. |
400 | Erro | Filtro ou paginação inválidos: |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes?desde=2026-10-01" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"pagina": null,
"limite": 50,
"total": null,
"proximo": "2026-10-19T13:42:07.481233+00:00,7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"proxima_url": "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes?limite=50&depois=2026-10-19T13%3A42%3A07.481233%2B00%3A00%2C7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"envelopes": [
{
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"status": "andamento",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"criado_em": "2026-10-19T13:42:07.481233+00:00",
"concluido_em": null,
"prazo": "2026-10-31T02:59:00+00:00",
"external_id": "dias:pop:4821",
"origem": "api"
}
]
}Trilha de auditoria do envelope
GET
/api/v1/envelopes/{id}/trilhaEscopo:
trilha:lerIgual a GET /documentos/{id}/trilha.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | Trilha | A trilha inteira, conferida. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/trilha" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"documento": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"integra": true,
"total": 3,
"eventos": [
{
"id": 18231,
"tipo": "enviado",
"criado_em": "2026-10-19T13:42:31.002914+00:00",
"hash_anterior": null,
"hash": "a1f0c3d2e5b4a7968f0e1d2c3b4a59687f6e5d4c3b2a19087f6e5d4c3b2a1908",
"dados": {}
},
{
"id": 18240,
"tipo": "assinou",
"criado_em": "2026-10-20T10:58:12.903311+00:00",
"hash_anterior": "a1f0c3d2e5b4a7968f0e1d2c3b4a59687f6e5d4c3b2a19087f6e5d4c3b2a1908",
"hash": "b2e1d4c3f6a5b8079e1f2d3c4b5a6978e7f6d5c4b3a2918e7f6d5c4b3a291807",
"dados": {
"nome": "Mariana Costa Ribeiro",
"funcao": "assinar",
"nivel": "avancada",
"metodo": "email"
}
},
{
"id": 18247,
"tipo": "concluido",
"criado_em": "2026-10-20T11:05:31.204118+00:00",
"hash_anterior": "b2e1d4c3f6a5b8079e1f2d3c4b5a6978e7f6d5c4b3a2918e7f6d5c4b3a291807",
"hash": "c3d2e5f4a7b6c9180f2a3e4d5c6b7a89f8e7d6c5b4a3920f8e7d6c5b4a392018",
"dados": {
"sha256": "8e3b1f0c9d2a47b6e5f4c3d2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e"
}
}
]
}PDF final do envelope
GET
/api/v1/envelopes/{id}/pdfEscopo:
documentos:baixarIgual a GET /documentos/{id}/pdf.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | PdfFinal | Links do PDF final selado. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/pdf" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"documento": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"arquivos": [
{
"nome": "POP-014-higienizacao-das-maos-assinado.pdf",
"sha256": "8e3b1f0c9d2a47b6e5f4c3d2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e",
"url": "https://wkkkfrcjotsbyfggcwro.supabase.co/storage/v1/object/sign/documentos/final.pdf?token=exemplo",
"expira_em_segundos": 300
}
]
}Pacote de provas
GET
/api/v1/envelopes/{id}/provasEscopo:
provas:baixarZIP com o PDF final, os originais, o carimbo do tempo, as assinaturas digitais e a trilha. Só para concluídos; link de 5 minutos.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | objeto | Link do pacote. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/provas" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"documento": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"arquivo": {
"nome": "provas-7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b.zip",
"sha256": "c0ffee12ab34cd56ef7890ab12cd34ef567890ab12cd34ef567890ab12cd34ef",
"url": "https://wkkkfrcjotsbyfggcwro.supabase.co/storage/v1/object/sign/documentos/provas.zip?token=exemplo",
"expira_em_segundos": 300
}
}Listar documentos
GET
/api/v1/documentosEscopo:
documentos:lerA lista da API de leitura (formato de antes, sem external_id). Sem rascunhos.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
limitequery | integer | Itens por página, de 1 a 200. (de 1 a 200; padrão 50) |
depoisquery | string | Cursor — o valor de |
paginaquery | integer | Número da página (compatibilidade). Só até |
contarquery | 1 |
|
statusquery | rascunho | andamento | pausado | concluido | cancelado | expirado | recusado | Filtra pela situação. |
empresaquery | string (uuid) | UUID de uma empresa liberada. |
desdequery | string | Criados a partir de (AAAA-MM-DD = 00:00 de Brasília, ou ISO 8601). |
atequery | string | Criados antes de (AAAA-MM-DD = 00:00 de Brasília, ou ISO 8601). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | ListaDocumentos | Uma página de documentos. |
400 | Erro | Filtro ou paginação inválidos: |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/documentos?desde=2026-10-01" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"pagina": 1,
"limite": 50,
"total": 1,
"proximo": null,
"proxima_url": null,
"documentos": [
{
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"status": "concluido",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"criado_em": "2026-10-19T13:42:07.481233+00:00",
"concluido_em": "2026-10-20T11:05:31.204118+00:00",
"prazo": "2026-10-31T02:59:00+00:00"
}
]
}Consultar documento (formato de leitura)
GET
/api/v1/documentos/{id}Escopo:
documentos:lerO detalhe da API de leitura, com a empresa, as pessoas e os PDFs finais. Para o objeto Envelope completo, use GET /envelopes/{id}.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | DocumentoDetalhe | O documento. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/documentos/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"status": "concluido",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"criado_em": "2026-10-19T13:42:07.481233+00:00",
"concluido_em": "2026-10-20T11:05:31.204118+00:00",
"prazo": "2026-10-31T02:59:00+00:00",
"tipo_id": null,
"valor_mensal": null,
"empresa": {
"nome": "Clínica Dias Saúde Ocupacional",
"cnpj": "12345678000190"
},
"signatarios": [
{
"nome": "Mariana Costa Ribeiro",
"funcao": "assinar",
"status": "assinou",
"nivel": "avancada",
"ordem": 1,
"assinado_em": "2026-10-20T10:58:12.903311+00:00"
},
{
"nome": "Rafael Almeida Pinto",
"funcao": "testemunha",
"status": "assinou",
"nivel": "avancada",
"ordem": 2,
"assinado_em": "2026-10-20T11:05:29.118024+00:00"
}
],
"pdfs_finais": [
{
"nome": "POP-014-higienizacao-das-maos-assinado.pdf",
"sha256": "8e3b1f0c9d2a47b6e5f4c3d2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e",
"criado_em": "2026-10-20T11:05:40.552910+00:00"
}
],
"verificar": "https://cardsign.gopixeltecnologiaa.com.br/verificar?h=8e3b1f0c9d2a47b6e5f4c3d2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e"
}Trilha de auditoria
GET
/api/v1/documentos/{id}/trilhaEscopo:
trilha:lerA trilha inteira (lida em páginas e conferida com a cadeia de hashes): tipo, data, hash e hash_anterior de cada evento, e integra (true/false). Sem IP, aparelho, CPF ou destino de código.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | Trilha | A trilha. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/documentos/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/trilha" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"documento": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"integra": true,
"total": 3,
"eventos": [
{
"id": 18231,
"tipo": "enviado",
"criado_em": "2026-10-19T13:42:31.002914+00:00",
"hash_anterior": null,
"hash": "a1f0c3d2e5b4a7968f0e1d2c3b4a59687f6e5d4c3b2a19087f6e5d4c3b2a1908",
"dados": {}
},
{
"id": 18240,
"tipo": "assinou",
"criado_em": "2026-10-20T10:58:12.903311+00:00",
"hash_anterior": "a1f0c3d2e5b4a7968f0e1d2c3b4a59687f6e5d4c3b2a19087f6e5d4c3b2a1908",
"hash": "b2e1d4c3f6a5b8079e1f2d3c4b5a6978e7f6d5c4b3a2918e7f6d5c4b3a291807",
"dados": {
"nome": "Mariana Costa Ribeiro",
"funcao": "assinar",
"nivel": "avancada",
"metodo": "email"
}
},
{
"id": 18247,
"tipo": "concluido",
"criado_em": "2026-10-20T11:05:31.204118+00:00",
"hash_anterior": "b2e1d4c3f6a5b8079e1f2d3c4b5a6978e7f6d5c4b3a2918e7f6d5c4b3a291807",
"hash": "c3d2e5f4a7b6c9180f2a3e4d5c6b7a89f8e7d6c5b4a3920f8e7d6c5b4a392018",
"dados": {
"sha256": "8e3b1f0c9d2a47b6e5f4c3d2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e"
}
}
]
}PDF final selado
GET
/api/v1/documentos/{id}/pdfEscopo:
documentos:baixarLinks de 5 minutos para o PDF final selado, com o SHA-256. Só depois que todos assinam (409 nao_concluido).
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | PdfFinal | Links. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/documentos/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/pdf" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"documento": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"arquivos": [
{
"nome": "POP-014-higienizacao-das-maos-assinado.pdf",
"sha256": "8e3b1f0c9d2a47b6e5f4c3d2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a09f8e",
"url": "https://wkkkfrcjotsbyfggcwro.supabase.co/storage/v1/object/sign/documentos/final.pdf?token=exemplo",
"expira_em_segundos": 300
}
]
}Webhooks
Destinos que recebem um POST a cada evento. No máximo 20 por grupo. O segredo whsec_… volta só na criação (e quando é trocado): guarde-o para conferir o cabeçalho CardSign-Signature.
Gerir webhooks exige o escopo webhooks:gerir e que quem criou a chave tenha org.api com alcance de grupo. Cada destino tem um responsável: ele só recebe eventos das empresas em que o responsável vê os documentos. Mudar url ou empresas faz do dono da chave o novo responsável e troca o segredo (que volta na resposta); as entregas pendentes que o novo responsável não poderia receber são descartadas.
A cada evento o CardSign faz um POST JSON para a URL cadastrada. Sucesso é qualquer 2xx em até 10 s. Falhou? Novo envio em 1 min, 5 min, 30 min, 2 h, 12 h e 24 h; depois a entrega fica falhou (dá para reenviar). 50 falhas seguidas pausam o destino.
No receptor: confira a assinatura em tempo constante, recuse se |agora − t| > 300 s, ignore CardSign-Event-Id já processado e só então busque GET /envelopes/{id}. envelope.concluido só sai depois que o PDF final selado existe.
Cabeçalhos enviados
| Cabeçalho | Tipo | Descrição |
|---|---|---|
CardSign-Event-Id | string | UUID do evento. Igual em todas as tentativas e reenvios — use para ignorar repetições. |
CardSign-Event | string | Tipo do evento. |
CardSign-Signature | string | t=<unix>,v1=<hex HMAC-SHA256(segredo, t + "." + corpo_bruto)>. A chave do HMAC é o segredo inteiro (whsec_…) em UTF-8. |
User-Agent | string | Sempre CardSign-Webhooks/1. |
Corpo do evento
| Campo | Tipo | Descrição |
|---|---|---|
id | string (uuid) | Igual ao cabeçalho CardSign-Event-Id. |
tipo | string | Um de TipoWebhook, ou ping. |
criado_em | string (date-time) | — |
grupo_id | string (uuid) | — |
envelope | objeto | Ausente no ping. |
envelope.id | string (uuid) | — |
envelope.external_id | string | null | — |
envelope.status | rascunho | andamento | pausado | concluido | cancelado | expirado | recusado | — |
envelope.empresa_id | string (uuid) | — |
signatario | objeto | Só nos eventos signatario.* e convite.falhou. |
signatario.id | string (uuid) | — |
signatario.nome | string | — |
signatario.funcao | string | — |
signatario.status | string | — |
Eventos
| Evento | Quando | Descrição |
|---|---|---|
envelope.enviado | Documento enviado | O envelope saiu do rascunho e os convites foram disparados. |
signatario.visualizou | Pessoa abriu o link | Uma pessoa abriu o link de assinatura. Traz signatario. |
signatario.assinou | Pessoa assinou | Uma pessoa assinou. Traz signatario. |
signatario.aprovou | Pessoa aprovou | Uma pessoa com a função aprovar aprovou. Traz signatario. |
signatario.testemunhou | Testemunha assinou | Uma testemunha assinou. Traz signatario. |
signatario.recusou | Pessoa recusou | Uma pessoa recusou; o motivo está em GET /envelopes/{id} (signatarios[].motivo_recusa). Traz signatario. |
convite.falhou | Convite não saiu | O convite (e-mail, WhatsApp ou SMS) de uma pessoa falhou de vez. Traz signatario. |
envelope.concluido | Documento concluído | Todos assinaram. Só sai depois que o PDF final selado existe — pode baixar com GET /envelopes/{id}/pdf. |
envelope.cancelado | Documento cancelado | O envelope foi cancelado (pelo painel ou pela API). |
envelope.expirado | Prazo vencido | O prazo passou sem todas as assinaturas. |
envelope.pausado | Documento pausado | O envelope foi pausado. |
envelope.retomado | Documento retomado | O envelope pausado voltou para andamento. |
envelope.exportar | Marcado para a sua integração | Alguém marcou no painel "Enviar a" a sua integração. Vai só para o destino da chave marcada. Busque
GET /envelopes/{id}: com status concluido, baixe o PDF (/pdf) e as provas e guarde na pasta que você
ligou a pasta.id; antes disso, espere o envelope.concluido (confira exportar.marcado).
|
ping | Teste (ping) | Enviado por POST /webhooks/{id}/testar. Não traz envelope. |
POST no seu sistema · signatario.assinou
{
"id": "7b6c5d4e-3f2a-4b1c-8d9e-0f1a2b3c4d5e",
"tipo": "signatario.assinou",
"criado_em": "2026-10-20T10:58:12.903Z",
"grupo_id": "9a2e7c41-5d3b-4e8f-b1a6-7c0d2f9e8b13",
"envelope": {
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"external_id": "dias:pop:4821",
"status": "andamento",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90"
},
"signatario": {
"id": "4d9e6f2a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",
"nome": "Mariana Costa Ribeiro",
"funcao": "assinar",
"status": "assinou"
}
}Conferir a assinatura · Node
// Node (Express): confira a assinatura com o corpo BRUTO, antes de interpretar o JSON
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const vistos = new Set(); // em produção: tabela com CardSign-Event-Id único
app.post("/api/webhooks/cardsign", express.raw({ type: "application/json" }), (req, res) => {
const corpo = req.body.toString("utf8");
const p = Object.fromEntries(
String(req.get("CardSign-Signature")).split(",").map((x) => x.trim().split("=")),
);
const agora = Math.floor(Date.now() / 1000);
if (!p.t || Math.abs(agora - Number(p.t)) > 300) return res.sendStatus(401);
const esperado = createHmac("sha256", process.env.CARDSIGN_WEBHOOK_SECRET)
.update(`${p.t}.${corpo}`)
.digest();
const recebido = Buffer.from(p.v1 ?? "", "hex");
if (recebido.length !== esperado.length || !timingSafeEqual(recebido, esperado))
return res.sendStatus(401);
const id = req.get("CardSign-Event-Id");
if (vistos.has(id)) return res.sendStatus(200); // repetição: já processado
vistos.add(id);
const evento = JSON.parse(corpo);
// responda rápido (até 10 s) e processe depois: busque GET /envelopes/{id}
res.sendStatus(200);
});Conferir a assinatura · Python
# Python (Flask)
import hmac, hashlib, os, time
from flask import Flask, request, abort
app = Flask(__name__)
SEGREDO = os.environ["CARDSIGN_WEBHOOK_SECRET"].encode()
@app.post("/api/webhooks/cardsign")
def cardsign():
corpo = request.get_data() # bytes brutos
p = dict(x.strip().split("=", 1) for x in request.headers["CardSign-Signature"].split(","))
if abs(time.time() - int(p["t"])) > 300:
abort(401)
esperado = hmac.new(SEGREDO, p["t"].encode() + b"." + corpo, hashlib.sha256).hexdigest()
if not hmac.compare_digest(esperado, p.get("v1", "")):
abort(401)
# ignore CardSign-Event-Id repetido e busque GET /envelopes/{id}
return "", 200Listar webhooks
GET
/api/v1/webhooksEscopo:
webhooks:gerirOs destinos do grupo da chave.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | objeto | Destinos. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/webhooks" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"webhooks": [
{
"id": "8c3f0a6b-4d2e-4f7a-b9c1-6d5e4f3a2b1c",
"url": "https://treinamento.gopixeltecnologia.com/api/webhooks/cardsign",
"eventos": [
"envelope.concluido",
"envelope.cancelado",
"signatario.recusou"
],
"empresas": [
"3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90"
],
"descricao": "Programa DIAS — treinamentos",
"ativo": true,
"falhas_seguidas": 0,
"pausado_em": null,
"pausado_motivo": null,
"segredo_fim": "x9Qk",
"criado_em": "2026-10-20T12:00:03.118204+00:00"
}
]
}Criar webhook
POST
/api/v1/webhooksEscopo:
webhooks:gerirExige Idempotency-KeyCadastra um destino https:// público. O segredo (whsec_…) volta só nesta resposta.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Content-Type | string | application/json |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
urlobrigatório | string (uri) | https:// pública (IP conferido na conexão). (até 500 caracteres) |
eventosobrigatório | array de envelope.enviado | signatario.visualizou | signatario.assinou | signatario.aprovou | signatario.testemunhou | signatario.recusou | convite.falhou | envelope.concluido | envelope.cancelado | envelope.expirado | envelope.pausado | envelope.retomado | envelope.exportar | (até 12 itens) |
empresas | array de string (uuid) | (até 200 itens) |
descricao | string | null | (até 120 caracteres) |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
201 | WebhookCriado | Criado (com o segredo). |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
409 | Erro |
|
415 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/webhooks" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-criarWebhook-123" \
-H "Content-Type: application/json" \
-d '{
"url": "https://treinamento.gopixeltecnologia.com/api/webhooks/cardsign",
"eventos": [
"envelope.enviado",
"signatario.assinou",
"signatario.recusou",
"convite.falhou",
"envelope.concluido",
"envelope.cancelado",
"envelope.expirado"
],
"empresas": [
"3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90"
],
"descricao": "Programa DIAS — treinamentos"
}'Exemplo Resposta201
{
"id": "8c3f0a6b-4d2e-4f7a-b9c1-6d5e4f3a2b1c",
"url": "https://treinamento.gopixeltecnologia.com/api/webhooks/cardsign",
"eventos": [
"envelope.enviado",
"signatario.assinou",
"signatario.recusou",
"convite.falhou",
"envelope.concluido",
"envelope.cancelado",
"envelope.expirado"
],
"empresas": [
"3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90"
],
"descricao": "Programa DIAS — treinamentos",
"ativo": true,
"falhas_seguidas": 0,
"pausado_em": null,
"pausado_motivo": null,
"segredo_fim": "x9Qk",
"criado_em": "2026-10-20T12:00:03.118204+00:00",
"segredo": "whsec_EXEMPLO-nao-use-3kP9vT2mQ8wR5yL1zN7bX4cF6hJ0dA9sx9Qk"
}Alterar webhook
PATCH
/api/v1/webhooks/{id}Escopo:
webhooks:gerirAltere url, eventos, empresas, descricao ou ativo (reativar zera as falhas seguidas). Se url ou empresas mudarem, o dono da chave passa a ser o responsável pelo destino e o segredo é trocado: a resposta traz o segredo novo só nessa vez (o antigo para de valer na hora).
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Content-Type | string | application/json |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Corpo da requisição
| Campo | Tipo | Descrição |
|---|---|---|
url | string (uri) | (até 500 caracteres) |
eventos | array de envelope.enviado | signatario.visualizou | signatario.assinou | signatario.aprovou | signatario.testemunhou | signatario.recusou | convite.falhou | envelope.concluido | envelope.cancelado | envelope.expirado | envelope.pausado | envelope.retomado | envelope.exportar | (até 12 itens) |
empresas | array de string (uuid) | (até 200 itens) |
descricao | string | null | (até 120 caracteres) |
ativo | boolean | — |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | WebhookAlterado | O destino atualizado (com |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
415 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X PATCH "https://cardsign.gopixeltecnologiaa.com.br/api/v1/webhooks/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"ativo": true,
"eventos": [
"envelope.concluido",
"envelope.cancelado",
"signatario.recusou"
]
}'Exemplo Resposta200
{
"id": "8c3f0a6b-4d2e-4f7a-b9c1-6d5e4f3a2b1c",
"url": "https://treinamento.gopixeltecnologia.com/api/webhooks/cardsign",
"eventos": [
"envelope.concluido",
"envelope.cancelado",
"signatario.recusou"
],
"empresas": [
"3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90"
],
"descricao": "Programa DIAS — treinamentos",
"ativo": true,
"falhas_seguidas": 0,
"pausado_em": null,
"pausado_motivo": null,
"segredo_fim": "x9Qk",
"criado_em": "2026-10-20T12:00:03.118204+00:00"
}Remover webhook
DELETE
/api/v1/webhooks/{id}Escopo:
webhooks:gerirRemove o destino e as entregas pendentes dele.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
204 | — | Removido (sem corpo). |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X DELETE "https://cardsign.gopixeltecnologiaa.com.br/api/v1/webhooks/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta204
(sem corpo)Trocar o segredo do webhook
POST
/api/v1/webhooks/{id}/segredoEscopo:
webhooks:gerirExige Idempotency-KeyGera um segredo novo (o antigo para de valer na hora) e o devolve só nesta resposta. O dono da chave passa a ser o responsável pelo destino. Sem corpo.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | WebhookCriado | O destino, com o segredo novo. |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/webhooks/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/segredo" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-trocarSegredoWebhook-123"Exemplo Resposta200
{
"id": "8c3f0a6b-4d2e-4f7a-b9c1-6d5e4f3a2b1c",
"url": "https://treinamento.gopixeltecnologia.com/api/webhooks/cardsign",
"eventos": [
"envelope.concluido",
"envelope.cancelado",
"signatario.recusou"
],
"empresas": [
"3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90"
],
"descricao": "Programa DIAS — treinamentos",
"ativo": true,
"falhas_seguidas": 0,
"pausado_em": null,
"pausado_motivo": null,
"segredo_fim": "m4Zt",
"criado_em": "2026-10-20T12:00:03.118204+00:00",
"segredo": "whsec_EXEMPLO-nao-use-9bW2qL7xT4nR1vK8sD5fG3hJ6pA0cZ2em4Zt"
}Testar webhook
POST
/api/v1/webhooks/{id}/testarEscopo:
webhooks:gerirExige Idempotency-KeyEnfileira um evento ping para o destino (entregue em até 1 minuto). Sem corpo.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
202 | objeto | Na fila. |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/webhooks/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/testar" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-testarWebhook-123"Exemplo Resposta202
{
"entrega_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"evento_id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d"
}Entregas do webhook
GET
/api/v1/webhooks/{id}/entregasEscopo:
webhooks:gerirAs últimas 100 entregas do destino, mais recentes primeiro.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
200 | objeto | Entregas. |
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/webhooks/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/entregas" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"entregas": [
{
"id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
"evento_id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
"tipo": "envelope.concluido",
"status": "entregue",
"tentativas": 1,
"http_status": 200,
"ms": 184,
"erro": null,
"criado_em": "2026-10-20T11:05:40.912003+00:00",
"proxima_em": null
},
{
"id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"evento_id": "7b6c5d4e-3f2a-4b1c-8d9e-0f1a2b3c4d5e",
"tipo": "signatario.assinou",
"status": "pendente",
"tentativas": 2,
"http_status": 503,
"ms": 10012,
"erro": "HTTP 503",
"criado_em": "2026-10-20T10:58:13.004417+00:00",
"proxima_em": "2026-10-20T11:34:13.004417+00:00"
}
]
}Reenviar entrega
POST
/api/v1/webhooks/{id}/entregas/{eid}/reenviarEscopo:
webhooks:gerirExige Idempotency-KeyPõe a entrega de novo na fila agora, com o mesmo evento_id (o receptor reconhece a repetição). Sem corpo.
Cabeçalhos
| Cabeçalho | Tipo | Descrição |
|---|---|---|
Authorizationobrigatório | string | Bearer cs_… — a chave da API. |
Idempotency-Keyobrigatório | string | 1 a 200 caracteres. A mesma chave com o mesmo corpo em 24 h devolve a mesma resposta. |
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
idobrigatóriocaminho | string (uuid) | UUID do envelope (ou do webhook, nas rotas /webhooks). |
eidobrigatóriocaminho | string (uuid) | UUID da entrega. |
Respostas
| Código | Tipo | Descrição |
|---|---|---|
202 | objeto | Na fila. |
400 | Erro |
|
401 | Erro | Chave ausente ou inválida: |
403 | Erro | Sem acesso: |
404 | Erro |
|
409 | Erro |
|
422 | Erro |
|
429 | Erro |
|
503 | Erro |
|
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/webhooks/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/entregas/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d/reenviar" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-reenviarEntrega-123"Exemplo Resposta202
{
"reenviada": true
}Idempotência
Todo POST exige o cabeçalho Idempotency-Key (1 a 200 caracteres ASCII visíveis). Com ele, repetir um pedido depois de uma queda de rede é seguro: o CardSign guarda a resposta por 24 horas. Use uma chave por ação do seu sistema, por exemplo dias-<id do envio>-criar e dias-<id do envio>-enviar.
Só o sucesso fica guardado: recusas (4xx) e falhas (5xx) não ficam, então corrija o que faltava e tente de novo com a mesma chave.
O que acontece
| Código | Tipo | Descrição |
|---|---|---|
| status original | idempotent-replayed: true | Mesma chave + mesmo corpo (SHA-256) em 24 h: a resposta guardada, sem refazer nada. |
| 422 | idempotencia_conflito | Mesma chave com outro corpo (ou outra rota). |
| 409 | idempotencia_em_andamento | O primeiro pedido com essa chave ainda está rodando; tente de novo após retry-after (2 s). |
| 400 | sem_idempotency_key | POST sem o cabeçalho. |
Exemplo Request
curl -X POST "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes/7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b/enviar" \
-H "Authorization: Bearer $CARDSIGN_CHAVE" \
-H "Idempotency-Key: minha-integracao-enviarEnvelope-123" \
-H "Content-Type: application/json" \
-d '{
"devolver_links": true
}'Exemplo Resposta422
{
"erro": {
"codigo": "idempotencia_conflito",
"mensagem": "Esta Idempotency-Key já foi usada com outro corpo (ou outra rota) nas últimas 24 h."
}
}Paginação
GET /documentos e GET /envelopes voltam em páginas, mais recentes primeiro (criado_em desc, id desc).
- Cursor (recomendado): cada resposta traz
proximoeproxima_url; mandedepois=<proximo>para a página seguinte.proximo: null= acabou. Sem teto. - `pagina` continua valendo, mas só até
pagina × limite ≤ 10000(além disso,400 pagina_alta_demais). - `total` só vem na primeira página sem cursor; nas outras é
null(peça comcontar=1).
Parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
limite | integer | Itens por página, de 1 a 200. (de 1 a 200; padrão 50) |
depois | string | Cursor — o valor de proximo da resposta anterior (<criado_em>,<id>). Ignora pagina. |
pagina | integer | Número da página (compatibilidade). Só até pagina × limite ≤ 10000; além disso use depois. (padrão 1) |
contar | 1 | 1 para trazer total também fora da primeira página. |
status | rascunho | andamento | pausado | concluido | cancelado | expirado | recusado | Filtra pela situação. |
empresa | string (uuid) | UUID de uma empresa liberada. |
desde | string | Criados a partir de (AAAA-MM-DD = 00:00 de Brasília, ou ISO 8601). |
ate | string | Criados antes de (AAAA-MM-DD = 00:00 de Brasília, ou ISO 8601). |
external_id | string | O external_id exato informado na criação (1 a 200 caracteres). (1 a 200 caracteres) |
Exemplo Request
curl -X GET "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes?desde=2026-10-01" \
-H "Authorization: Bearer $CARDSIGN_CHAVE"Exemplo Resposta200
{
"pagina": null,
"limite": 50,
"total": null,
"proximo": "2026-10-19T13:42:07.481233+00:00,7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"proxima_url": "https://cardsign.gopixeltecnologiaa.com.br/api/v1/envelopes?limite=50&depois=2026-10-19T13%3A42%3A07.481233%2B00%3A00%2C7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"envelopes": [
{
"id": "7b1e4c2d-9f3a-4d6e-8a5b-1c2d3e4f5a6b",
"titulo": "POP 014 — Higienização das mãos (ciência do colaborador)",
"status": "andamento",
"empresa_id": "3f6c1d2a-8b4e-4f1a-9c7d-2e5b8a1f4c90",
"criado_em": "2026-10-19T13:42:07.481233+00:00",
"concluido_em": null,
"prazo": "2026-10-31T02:59:00+00:00",
"external_id": "dias:pop:4821",
"origem": "api"
}
]
}Erros
Todo erro tem o mesmo formato: codigo estável (para o seu código decidir), mensagem em português (para pessoas) e, quando ajuda, detalhes com o campo exato (ex.: signatarios[0].email). Cada chamada fica registrada na aba Chamadas de Conta › API e chaves.
Códigos de erro
| Código | Tipo | Descrição |
|---|---|---|
400 | sem_idempotency_key | POST de escrita sem o cabeçalho Idempotency-Key |
400 | json_invalido | Corpo que não é JSON (ou multipart sem o campo dados) |
400 | parametro_invalido | Filtro da lista inválido |
400 | cursor_invalido | "depois" que não veio de "proximo" |
400 | pagina_alta_demais | pagina × limite acima de 10.000 (use o cursor) |
401 | sem_chave | Sem Authorization: Bearer cs_… |
401 | chave_invalida | Chave que não existe |
401 | chave_revogada | Chave revogada |
401 | chave_expirada | Chave vencida |
401 | chave_sem_responsavel | Quem criou a chave saiu do grupo |
403 | ip_nao_autorizado | IP fora da lista da chave |
403 | sem_escopo | A chave não tem o escopo da rota |
403 | sem_permissao | Quem criou a chave não tem a permissão (nesta empresa) |
404 | nao_encontrado | Rota que não existe |
404 | documento_nao_encontrado | Documento/envelope fora do alcance da chave |
404 | signatario_nao_encontrado | Pessoa que não é deste envelope |
404 | webhook_nao_encontrado | Destino de webhook de outro grupo ou removido |
404 | entrega_nao_encontrada | Entrega de outro destino |
405 | metodo | Método não aceito nesta rota (veja Allow) |
409 | nao_concluido | PDF final ou provas antes da conclusão |
409 | estado_invalido | Ação que a situação do envelope não permite |
409 | external_id_em_uso | external_id já usado por esta chave (detalhes traz o envelope_id) |
409 | idempotencia_em_andamento | A mesma Idempotency-Key ainda está sendo processada |
413 | grande_demais | Corpo acima de 30 MB, PDF acima de 20 MB ou PDFs do pedido somando mais de 30 MB |
415 | tipo_nao_suportado | Content-Type que não é JSON nem multipart/form-data |
422 | validacao | Campos inválidos (veja detalhes) |
422 | idempotencia_conflito | Idempotency-Key repetida com outro corpo |
422 | arquivo_invalido | Arquivo que não é PDF (%PDF) ou está corrompido |
422 | download_falhou | Não deu para baixar o PDF da URL informada |
422 | url_invalida | URL que não é https pública |
422 | ancora_nao_encontrada | Texto da âncora não está no PDF |
422 | regra_violada | Regra do CardSign (ex.: falta e-mail, falta campo de assinatura) |
429 | limite | Mais de 120 chamadas por minuto (veja retry-after) |
500 | erro_interno | Erro inesperado |
503 | indisponivel | Não deu para conferir o acesso agora, servidor ocupado lendo PDFs ou pedido acima de 90 s (veja retry-after) |
503 | trilha_indisponivel | Não deu para ler a trilha inteira agora |
Exemplo Resposta422
{
"erro": {
"codigo": "validacao",
"mensagem": "Corpo inválido.",
"detalhes": [
{
"campo": "signatarios[0].email",
"mensagem": "Invalid email address"
},
{
"campo": "prazo",
"mensagem": "O prazo já passou."
}
]
}
}Postman
Coleções prontas para testar a API sem escrever código: cada requisição tem descrição, testes automáticos e guarda os ids nas variáveis da coleção. A coleção põe uma Idempotency-Key nova em todo POST.
- Coleção CardSign API v1Autorização, fluxo completo, ações, consultas, webhooks e erros esperados — com testes.
- Ambiente SandboxCardSign local (http://localhost:8080).
- Ambiente Produçãohttps://cardsign.gopixeltecnologiaa.com.br
- Simulador de webhooks (DIAS)Envia cada evento ao receptor do Programa DIAS, assinado com HMAC.
- Baixe a coleção e um ambiente. No Postman, Import › arraste os arquivos (ou File › Import).
- Escolha o ambiente no canto superior direito e preencha
api_key(é secreta),email_signatario(seu e-mail, para receber os convites de teste) e, se quiser,empresa_idewebhook_url. - Rode 00 Autorização › Quem sou eu — se
empresa_idestiver vazio, ele é preenchido com a primeira empresa da chave. - Rode as pastas na ordem, ou a coleção inteira no Runner (botão Run). Os resultados dos testes aparecem na aba Test Results.
- Para testar o receptor do Programa DIAS, use o Simulador de webhooks: defina
webhook_segredo(owhsec_…) e envie cada evento, assinado como o CardSign assina.
Pré-requisição da coleção
// Idempotency-Key em todo POST que ainda não tem uma
if (pm.request.method === "POST" && !pm.request.headers.has("Idempotency-Key")) {
pm.request.headers.add({
key: "Idempotency-Key",
value: pm.variables.replaceIn("{{$guid}}"),
});
}Changelog
1.0.1 · 21/10/2026
- Webhooks: mudar url ou empresas (PATCH /webhooks/{id}) faz do dono da chave o responsável pelo destino e troca o segredo, que volta na resposta (campo segredo) só nessa vez. Novo POST /webhooks/{id}/segredo para trocar o segredo.
- Webhooks: gerir pela API exige que quem criou a chave tenha org.api com alcance de grupo (a mesma regra da tela). Reenvio só de entregas que o responsável de agora poderia receber; pendentes há mais de 72 h viram falhou.
- PDFs: no máximo 30 MB somando todos os arquivos de um pedido (413 grande_demais) e 90 s para baixar e ler (503 indisponivel com retry-after). Com o servidor ocupado lendo PDFs de outros pedidos, 503 indisponivel com retry-after.
- Idempotency-Key no multipart: o hash é do campo dados (JSON canônico) e do nome + SHA-256 de cada arquivo, não do corpo bruto (o boundary não conta). Reserva sem resposta só é liberada depois de 10 min.
1.0.0 · 20/10/2026
- API de escrita: criar envelope (JSON ou multipart), arquivos por URL ou base64, signatários com campos por posição ou âncora, enviar (com devolver_links), cancelar, pausar, retomar e lembrete.
- Webhooks assinados (HMAC-SHA256) com reenvio automático, teste (ping), histórico de entregas e reenvio manual.
- Novas leituras: /eu, /empresas, /modelos, /envelopes (com external_id) e /envelopes/{id}/provas.
- Idempotency-Key obrigatória em todo POST; paginação por cursor em /documentos e /envelopes.
- Documentação pública em /docs/api, OpenAPI 3.1 e coleções Postman.
0.9.0 · 01/09/2026
- API de leitura: /documentos, /documentos/{id}, /documentos/{id}/trilha e /documentos/{id}/pdf.