Documentação da API

Use a API do ZiaSign pra criar documentos e disparar assinaturas eletrônicas direto do seu sistema — imobiliária, ERP, ou qualquer plataforma própria.

Autenticação

Toda chamada precisa do cabeçalho:

Authorization: Bearer SUA_CHAVE_DE_API

A chave é gerada no painel, em Chaves de API. Ela só aparece completa uma vez, no momento da criação — guarde num lugar seguro (ex: variável de ambiente no seu sistema).

Criar um documento e enviar pra assinatura

POST/api/v1/documentos.php

Corpo (JSON):

{
  "titulo": "Contrato de locação — Rua X, 123",
  "arquivo_nome": "contrato.pdf",
  "arquivo_base64": "JVBERi0xLjQKJc...",
  "signatarios": [
    {
      "nome": "João da Silva",
      "cpf": "111.444.777-35",
      "email": "joao@email.com",
      "telefone": "(11) 98888-7777",
      "canal": "ambos"
    }
  ]
}

arquivo_base64: o conteúdo do PDF codificado em base64 (não é upload de arquivo, é o conteúdo direto no JSON)
signatarios: um ou mais. Cada um precisa de nome, cpf e email.
canal: opcional. Aceita email, whatsapp ou ambos. Se omitido, o padrão é email, mantendo compatibilidade com integrações anteriores.
telefone: opcional para e-mail e obrigatório quando canal for whatsapp ou ambos.
Envios por WhatsApp pela API exigem que a empresa esteja no plano Pro.

Resposta (201):

{
  "sucesso": true,
  "documento_id": 42,
  "codigo_verificacao": "ZS-8F3A2K",
  "signatarios": [
    {
      "id": 101,
      "nome": "João da Silva",
      "email": "joao@email.com",
      "link_assinatura": "https://www.ziasign.com.br/assinar/..."
    }
  ]
}

Os convites são disparados automaticamente conforme o canal de cada signatário. Em email, o convite e o código seguem por e-mail; em whatsapp, o fluxo usa WhatsApp; em ambos, os dois canais são utilizados.

Compatibilidade: integrações existentes não precisam ser alteradas. Se canal não for enviado, o ZiaSign continuará usando e-mail.

Consultar o status de um documento

GET/api/v1/documentos.php?id=42

{
  "sucesso": true,
  "documento": {
    "id": 42,
    "titulo": "Contrato de locação — Rua X, 123",
    "status": "enviado",
    "codigo_verificacao": "ZS-8F3A2K",
    "concluido_em": null,
    "link_verificacao": "https://www.ziasign.com.br/verificar?codigo=ZS-8F3A2K",
    "signatarios": [
      {
        "id": 101,
        "nome": "João da Silva",
        "email": "joao@email.com",
        "status": "visualizado",
        "assinado_em": null
      }
    ]
  }
}

status do documento: rascunho, enviado, assinado, cancelado.
status de cada signatário: pendente, visualizado, assinado, recusado.

Erros

Toda resposta de erro segue o formato:

{ "erro": "Mensagem explicando o que deu errado" }

Códigos usados: 400 (dado inválido/faltando), 401 (chave de API ausente/inválida), 403 (recurso não disponível no plano), 404 (documento não encontrado), 405 (método HTTP errado), 500 (erro interno).

Próximos passos

Ainda não implementado — em desenvolvimento.

Webhook: notificar seu sistema automaticamente quando um documento for assinado, em vez de precisar ficar consultando o status
Assinatura sequencial: hoje todos os signatários recebem o convite ao mesmo tempo